Skip to content

Commit

Permalink
feat(docs): Expanded popover component docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@tmorehouse
tmorehouse committed Aug 31, 2017
1 parent 68138cb commit ccd1c7c
Showing 1 changed file with 102 additions and 53 deletions.
155 changes: 102 additions & 53 deletions docs/components/popover/README.md
View file
Expand Up @@ -6,14 +6,14 @@ element via the `<b-popover>` component or [`v-b-popover`](/docs/directives/popo
## Overview ## Overview


Things to know when using popover component: Things to know when using popover component:
- Popovers rely on the 3rd party library Popper.js for positioning. The library is bundled wit Bootstrap-Vue! - Popovers rely on the 3rd party library Popper.js for positioning. The library is bundled with Bootstrap-Vue dist files!
- Popovers with zero-length title and contnt are never displayed. - Popovers with zero-length title _and_ content are never displayed.
- Triggering popovers on hidden elements will not work. - Triggering popovers on hidden elements will not work.
- Popovers for `disabled` elements must be triggered on a wrapper element. - Popovers for `disabled` elements must be triggered on a wrapper element.
- When triggered from hyperlinks that span multiple lines, popovers will be centered. Use white-space: nowrap; on your `<a>`s, `<b-link>`s and `<router-link>`s to avoid this behavior. - When triggered from hyperlinks that span multiple lines, popovers will be centered. Use `white-space: nowrap;` on your `<a>`s, `<b-link>`s and `<router-link>`s to avoid this behavior.
- Popovers must be hidden before their corresponding elements have been removed from the DOM. - Popovers must be hidden before their corresponding markup elements have been removed from the DOM.


The `<b-popover>` component inserts a hidden (`display:none`) `<div>` container The `<b-popover>` component inserts a hidden (`display: none;`) `<div>` container
element at the point in the DOM where the `<b-popover>` component is placed. This may element at the point in the DOM where the `<b-popover>` component is placed. This may
affect layout and/or styling of components such as `<b-button-group>`, `<b-button-toolbar>`, affect layout and/or styling of components such as `<b-button-group>`, `<b-button-toolbar>`,
and `<b-input-group>`. To avoid these posible layout issues, place the `<b-popover>` and `<b-input-group>`. To avoid these posible layout issues, place the `<b-popover>`
Expand All @@ -23,8 +23,14 @@ The target element **must** exist in the document before `<b-popover>` is mounte
If the target element is not found during mount, the popover will never open. Always If the target element is not found during mount, the popover will never open. Always
place your `<b-popover>` component lower in the DOM than your target element. place your `<b-popover>` component lower in the DOM than your target element.


**Note:** _When using slots for content and/or title, `<b-popover>` transfers the
rendered DOM from those slots into the popover's markup when shown, and returns
them back to the `<b-popover>` component when hidden. This may cause some issues
in rare circumstances, so please test your implmentation accordingly! The `title`
and `content` props do not have this behavior. For simple popovers, we recommend
using the `v-b-popover` directive and enable the `html` modifer if needed._


## `<b-popover>` Component Usage ## `<b-popover>` Component basic usage
```html ```html
<template> <template>
<b-container fluid> <b-container fluid>
Expand Down Expand Up @@ -59,8 +65,9 @@ place your `<b-popover>` component lower in the DOM than your target element.
<b-btn id="exPopover3" variant="primary">Using slots</b-btn> <b-btn id="exPopover3" variant="primary">Using slots</b-btn>
<b-popover target-id="exPopover3"> <b-popover target-id="exPopover3">
<template slot="title">Content via Slots</template> <template slot="title">Content via Slots</template>
Embedding content <span class="text-danger">using slots</span> affords you Embedding content <span class="text-danger">using slots</span>
<em>greater <strong>control.</strong></em> and basic HTML support/ affords you <em>greater <strong>control.</strong></em> and
basic HTML support.
</b-popover> </b-popover>
</b-col> </b-col>
</b-row> </b-row>
Expand All @@ -71,7 +78,7 @@ place your `<b-popover>` component lower in the DOM than your target element.
<!-- popover-1.vue --> <!-- popover-1.vue -->
``` ```


### Component Options ### Component options via props


| Prop | Default | Description | Supported values | Prop | Default | Description | Supported values
| ---- | ------- | ----------- | ---------------- | ---- | ------- | ----------- | ----------------
Expand All @@ -82,31 +89,94 @@ place your `<b-popover>` component lower in the DOM than your target element.
| `triggers` | `hover focus` | Space separated list of which event(s) will trigger open/close of popover | `hover`, `focus`, `click`. Note `blur` is a special use case to close popover on next click. | `triggers` | `hover focus` | Space separated list of which event(s) will trigger open/close of popover | `hover`, `focus`, `click`. Note `blur` is a special use case to close popover on next click.
| `no-fade` | `false` | Disable fade animation when set to `true` | `true` or `false` | `no-fade` | `false` | Disable fade animation when set to `true` | `true` or `false`
| `delay` | `0` | Number of milliseconds to delay showing and hidding of popover | `0` and up, integers only. | `delay` | `0` | Number of milliseconds to delay showing and hidding of popover | `0` and up, integers only.
| `offset` | `0` | Number of pixels to shift the center of the popover | Any negative or positive integer | `offset` | `0` | Number of pixels to shift the center of the popover. Also affects the position of the popover arrow. | Any negative or positive integer




### Advanced usage with reactive content ## `v-b-popover` Directive usage


You can even make your popover content interactive: Just need quick popovers without too much markup? Use the
[`v-b-popover` directive](/docs/directives/popover):

```html
<template>
<b-container fluid>

<h4 class="mt-sm-4 ms-sm-4 text-muted">Placement</h4>
<b-row>
<b-col md="3" class="py-3 text-center">
<b-btn v-b-popover.hover.top="'I am Top'"
title="Popover!"
variant="primary">Top</b-btn>
</b-col>
<b-col md="3" class="py-3 text-center">
<b-btn v-b-popover.hover.left="'I am Left'"
title="Popover!"
variant="primary">Left</b-btn>
</b-col>
<b-col md="3" class="py-3 text-center">
<b-btn v-b-popover.hover.right="'I am Right'"
title="Popover!"
variant="primary">Right</b-btn>
</b-col>
<b-col md="3" class="py-3 text-center">
<b-btn v-b-popover.hover.bottom="'I am Bottom'"
title="Popover!"
variant="primary">Bottom</b-btn>
</b-col>
</b-row>

</b-container>
</template>

<!-- popover-directive-1.vue -->
```

Refer to the [`v-b-popover` directive](/docs/directives/popover) documentation for detailed
information on the directive usage.

## Advanced `<b-popover>` usage with reactive content

You can even make your `<b-popover>` content interactive. Just remember not to use the
`focus`, `hover` or `blur` triggers (use only `click`), otherwsie your popover will
close automatically as soon as someone trys to interact with the content.

If you absolutely must use a trigger other than `click` (or want to disable closing of the
popover when the trigger element is clicked a second time), then you can either:
- Listen for the `hide` event on the `<b-popover>` element, and call the `preventDefault()` method (when apropriate) on the `BvEvent` passed to your `hide` handler, or
- Disable your trigger element (if possible) as soon as the popover opens (via the `show` event), and re-enable it when apropriate.

For practical purposes, interactive content popovers should be minimal. The maximum
width of the popover is hard coded by Bootstrap V4 CSS to `276px`. Tall popovers on
small screens can be harder to deal with on mobile devices (such as smart-phones).


```html ```html
<template> <template>
<div> <div>
<div class="my-3"> <div class="my-3">
<b-btn id="exPopoverReactive1" variant="primary">Reactive Content Using Slots</b-btn> <!-- our triggering (target) element -->
<b-btn id="exPopoverReactive1"
:disabled="disabled"
variant="primary">
Reactive Content Using Slots
</b-btn>
</div> </div>

<!-- output from teh popover interaction -->
<b-card title="Returned values:" v-if="input1Return && input2Return"> <b-card title="Returned values:" v-if="input1Return && input2Return">
<p class="card-text" style="max-width:20rem;"> <p class="card-text" style="max-width:20rem;">
Name: <strong>{{ input1Return }}</strong><br> Name: <strong>{{ input1Return }}</strong><br>
Color: <strong>{{ input2Return }}</strong> Color: <strong>{{ input2Return }}</strong>
</p> </p>
</b-card> </b-card>


<!-- Our popover title and content render container -->
<!-- We use placement 'auto' so popover fits in the best spot on viewport -->
<b-popover target-id="exPopoverReactive1" <b-popover target-id="exPopoverReactive1"
trigger="click", trigger="click",
placement="auto" placement="auto"
ref="popover" ref="popover"
@show="clearValues"> @show="onShow"
@hidden="onHidden">
<template slot="title"> <template slot="title">
<b-btn @click="onClose" class="close" aria-label="Close"> <b-btn @click="onClose" class="close" aria-label="Close">
<span class="d-inline-block" aria-hidden="true">&times;</span> <span class="d-inline-block" aria-hidden="true">&times;</span>
Expand All @@ -120,86 +190,65 @@ You can even make your popover content interactive:
<b-form-select size="sm" v-model="input2" :options="options"></b-form-select> <b-form-select size="sm" v-model="input2" :options="options"></b-form-select>
</b-form-group> </b-form-group>
<b-alert show> <b-alert show>
<h6>Values:</h6> <h6>Current Values:</h6>
Name: <strong>{{ input1 }}</strong><br> Name: <strong>{{ input1 }}</strong><br>
Color: <strong>{{ input2 }}</strong> Color: <strong>{{ input2 }}</strong>
</b-alert> </b-alert>
<b-btn @click="onCancel" size="sm" variant="danger">Cancel</b-btn> <b-btn @click="onCancel" size="sm" variant="danger">Cancel</b-btn>
<b-btn @click="onOk" size="sm" variant="primary">Ok</b-btn> <b-btn @click="onOk" size="sm" variant="primary">Ok</b-btn>
</b-popover> </b-popover>
</div> </div>
</template> </template>


<script> <script>
export default { export default {
data: { data: {
input1: '', input1: '',
input2: '', input2: '',
options: [{text:'- Chose 1 -', value:''},'Red','Green','Blue'], options: [{text:'- Choose 1 -', value:''},'Red','Green','Blue'],
input1Return: '', input1Return: '',
input2Return: '', input2Return: '',
disabled: false
}, },
methods: { methods: {
onClose() { onClose() {
// Emitting 'close' on the popover will trigger it to hide for us
this.$refs.popover.$emit('close'); this.$refs.popover.$emit('close');
}, },
onCancel() { onCancel() {
// Emitting 'close' on the popover will trigger it to hide for us
this.$refs.popover.$emit('close'); this.$refs.popover.$emit('close');
}, },
onOk() { onOk() {
if (!this.input1 || !this.input2) { if (!this.input1 || !this.input2) {
alert('Please enter something'); alert('Please enter something');
} else { } else {
alert('Thats great!'); alert('Thats great!');
// Emitting 'close' on the popover will trigger it to hide for us
this.$refs.popover.$emit('close'); this.$refs.popover.$emit('close');
// "Return" our popover "form" results
this.input1Return = this.input1; this.input1Return = this.input1;
this.input2Return = this.input2; this.input2Return = this.input2;
} }
}, },
clearValues() { onShow() {
// This is called just before the popover is shown // This is called just before the popover is shown
// Reset our popover "form" variables
this.input1 = ''; this.input1 = '';
this.input2 = ''; this.input2 = '';
this.input1Return = ''; this.input1Return = '';
this.input2Return = ''; this.input2Return = '';
// Disable our trigger button to prevent popover closing on second click
this.disabled = true;
},
onHidden() {
// Called just after the popover has finished hiding
// We re-enable our button
this.disabled = false;
} }
} }
}; };
</script> </script>


<!-- popover-2.vue --> <!-- popover-advanced-1.vue -->
``` ```


## `v-b-popover` Directive Usage

Just need quick popovers without too much markup? Use the `v-b-popover` directive:

```html
<template>
<b-container fluid>

<h4 class="mt-sm-4 ms-sm-4 text-muted">Placement</h4>
<b-row>
<b-col md="3" class="py-3 text-center">
<b-btn v-b-popover.hover.top="'I am Top'" title="Popover!" variant="primary">Top</b-btn>
</b-col>
<b-col md="3" class="py-3 text-center">
<b-btn v-b-popover.hover.left="'I am Left'" title="Popover!" variant="primary">Left</b-btn>
</b-col>
<b-col md="3" class="py-3 text-center">
<b-btn v-b-popover.hover.right="'I am Right'" title="Popover!" variant="primary">Right</b-btn>
</b-col>
<b-col md="3" class="py-3 text-center">
<b-btn v-b-popover.hover.bottom="'I am Bottom'" title="Popover!" variant="primary">Bottom</b-btn>
</b-col>
</b-row>

</b-container>
</template>

<!-- popover-directive-1.vue -->
```

Refer to the [`v-b-popover` directive](/docs/directives/popover) documentation for detailed
information on the directive usage.

0 comments on commit ccd1c7c

Please sign in to comment.