Skip to content

Commit

Permalink
updated docs to better reflect which features were introduced with wh…
Browse files Browse the repository at this point in the history
…ich version.
  • Loading branch information
LinusBorg committed Jan 2, 2018
1 parent d9ad473 commit 081b93a
Show file tree
Hide file tree
Showing 6 changed files with 71 additions and 37 deletions.
14 changes: 9 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,21 +6,25 @@
<img src="http://linusborg.github.io/portal-vue/assets/logo.png" alt="PortalVue Logo">
</p>


For more detailed documentation and additional Information, please visit <a href="http://linusborg.github.io/portal-vue">the docs</a>

> The documentation is for version 1.3.0-beta, but all things except the sections about scoped slots apply to previous versions as well.
## Installation

```
npm install --save portal-vue
// 1.3.0-beta with scopedSlots support:
npm i portal-vue@next
// current stable:
npm i portal-vue
```

// in .js
```javascript
import PortalVue from 'portal-vue'
Vue.use(PortalVue)
```



## Usage

```html
Expand Down
28 changes: 15 additions & 13 deletions docs/config.js
Original file line number Diff line number Diff line change
Expand Up @@ -6,22 +6,24 @@ docute.init({
{ title: 'PortalVue', path: '/' },
{ title: 'Usage Guide', path: '/guide' },
{ title: 'Examples', path: '/examples' },
{ title: 'Documentation', type: 'dropdown', items: [
{ title: 'Installation Instructions', type: 'label' },
{ title: 'Installation', path: '/docs/installation' },
{ type: 'sep' },
{ title: 'Components', type: 'label' },
{ title: 'Portal', path: '/docs/portal' },
{ title: 'PortalTarget', path: '/docs/portal-target' },
{ title: 'Special Objects', type: 'label' },
{ title: 'Wormhole', path: '/docs/wormhole' },
],
{
title: 'Documentation',
type: 'dropdown',
items: [
{ title: 'Current: v1.3.0-beta.0', path: '#' },
{ title: 'Installation Instructions', type: 'label' },
{ title: 'Installation', path: '/docs/installation' },
{ type: 'sep' },
{ title: 'Components', type: 'label' },
{ title: 'Portal', path: '/docs/portal' },
{ title: 'PortalTarget', path: '/docs/portal-target' },
{ title: 'Special Objects', type: 'label' },
{ title: 'Wormhole', path: '/docs/wormhole' },
],
},
{ title: 'Caveats', path: '/docs/caveats' },
],
repo: 'linusborg/portal-vue',
twitter: 'Linus_Borg',
plugins: [
docuteIframe(),
],
plugins: [docuteIframe()],
})
12 changes: 12 additions & 0 deletions docs/docs/portal-target.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,8 @@ This component is an outlet for any content that was sent by a `<portal>` compon

### `multiple`

> since `1.2.0`
When `multiple` is `true`, the portal will be able to receive and render content from multiple `Portal` component at the same time.

You should use the `order` prop on the `Portal` to define the order in which the contents should be rendered:
Expand Down Expand Up @@ -75,6 +77,8 @@ When set to true, the component will check if the sent content has only one root

### `slotProps`

> since `1.3.0`
| Type | Required | Default |
| -------- | -------- | ------- |
| `Object` | no | `{}` |
Expand Down Expand Up @@ -133,6 +137,8 @@ Defines the type of tag that should be rendered as a root component.

### `transition`

> since `1.2.0`
| Type | Required | Default |
| ----------------------- | -------- | ------- |
| `Boolean|String|Object` | no | none |
Expand Down Expand Up @@ -161,6 +167,8 @@ You can use the `transitionEvents` prop to pass event listeners for that transit

### `transitionEvents`

> since `1.2.0`
| Type | Required | Default |
| -------- | -------- | ------- |
| `Object` | no | none |
Expand All @@ -180,6 +188,8 @@ Accepts an object whose keys match the transition component's events. Each key's

### Default slot

> since `1.1.0`
Any existing slot content is rendered in case that no content from any source Portal is available.

Example:
Expand All @@ -201,6 +211,8 @@ Example:

## Events API

> since `1.1.0`
### `change`

Emitted everytime the component re-renders because the content from the `Portal` changed.
Expand Down
4 changes: 4 additions & 0 deletions docs/docs/portal.md
Original file line number Diff line number Diff line change
Expand Up @@ -55,6 +55,8 @@ But it might be a good idea to name your `Portal` components so you can debug th

### `order`

> since `1.2.0`
| Type | Required | Default |
| ----------------- | -------- | --------------- |
| `[String,Number]` | no\* | a random String |
Expand Down Expand Up @@ -113,6 +115,8 @@ When set to true, the component will check if the sent content has only one root

### `slotProps`

> since `1.3.0`
| Type | Required | Default |
| -------- | -------- | ------- |
| `Object` | no | `{}` |
Expand Down
46 changes: 27 additions & 19 deletions docs/docs/wormhole.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,8 @@ The Wormhole is not a component, it's an object that connects the `Portal`s to t
You can use this object to programmatically send content to a `PortalTarget`,
check weither a target exists, has content, and where that content was sent from.

<p class="tip">This feature was introdcued with version `1.1.0`</p>

## Methods

### open()
Expand All @@ -13,15 +15,16 @@ The `open` method accepts one argument, an object with the following properties:

`Wormhole.open({to, from, passengers})`

|Property|Required|Default|Explanation|
|--------|--------|-------|-----------|
|to|yes||The name of the `PortalTarget` to send to|
|from|yes||The name of the `Portal` this conent comes from.|
|passengers|no||An array of vNodes - the content to be sent to the `PortalTarget`|
| Property | Required | Default | Explanation |
| ---------- | -------- | ------- | ----------------------------------------------------------------- |
| to | yes | | The name of the `PortalTarget` to send to |
| from | yes | | The name of the `Portal` this conent comes from. |
| passengers | no | | An array of vNodes - the content to be sent to the `PortalTarget` |

Even if you ue this method programmatically and there is not source `Portal`, you still have to provide `from` - every content sent through the wormhole needs a source.

Examples:

```javascript
import { Wormhole } from 'portal-vue'

Expand All @@ -35,9 +38,10 @@ methods: {
})
}
}

```

This is the programmatic equivalent of the following:

```html
<portal to="destination" name="my-portal">
<p>This will be displayed in the Target!</p>
Expand All @@ -52,11 +56,11 @@ It accepts two arguments, an object and an optional `force` flag.

`Wormhole.close({ to, from }, force = false)`

|Argument/Property|Required|Default|Explanation|
|--------|--------|-------|-----------|
|to|yes||The name of the `PortalTarget` whose content should be removed|
|from|no||Name of the Portal that the content was created with. Can be left out if the `force` flag is set|
|force|no|false|If this is true, the `PortalTarget`s content will be removed even if `from` doesn't match|
| Argument/Property | Required | Default | Explanation |
| ----------------- | -------- | ------- | ------------------------------------------------------------------------------------------------ |
| to | yes | | The name of the `PortalTarget` whose content should be removed |
| from | no | | Name of the Portal that the content was created with. Can be left out if the `force` flag is set |
| force | no | false | If this is true, the `PortalTarget`s content will be removed even if `from` doesn't match |

Why do you have to provide the `from` name (or use `force`)?

Expand All @@ -65,6 +69,7 @@ The close() method is also used by `Portal` components to remove the content fro
We can override this behaviour with the `force` argument.

Example:

```javascript
methods: {
clearPortalTarget() {
Expand Down Expand Up @@ -97,19 +102,21 @@ methods: {
Returns `true` if there's a `PortalTarget` with the given name active.

Example:

```javascript
Wormhole.hasTarget('destination')
// => true
Wormhole.hasTarget('destination')
// => true
```

### hasContentFor()

Returns `true` if there's a `PortalTarget` with the given name active, **and** there's content shown by the `PortalTarget`.

Example:

```javascript
Wormhole.hasContentFor('destination')
// => true
Wormhole.hasContentFor('destination')
// => true
```

### getSourceFor()
Expand All @@ -119,8 +126,8 @@ Example:
Returns the name of the source that sent the current content to the given target. Returns `undefined` if no content/source exists.

```javascript
Wormhole.getSourceFor('destination')
// => 'my-portal'
Wormhole.getSourceFor('destination')
// => 'my-portal'
```

### getContentFor()
Expand All @@ -130,7 +137,8 @@ Returns the name of the source that sent the current content to the given target
Returns the content that is currently being displayed in a `PortalTarget` wiht the given `to` name.

Example:

```javascript
Wormhole.getContentFor('destination')
// => Array<VNode>
Wormhole.getContentFor('destination')
// => Array<VNode>
```
4 changes: 4 additions & 0 deletions docs/guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -146,6 +146,8 @@ The `slim` property also works on `<portal>` components when the are `disabled`.

### Using Scoped Slots

> since `1.3.0`
PortalVue can also be used with [Scoped Slots](https://vuejs.org/v2/guide/components.html#Scoped-Slots)! This allows you to send a scoped slot to a PortalTarget, which can then provide props for the slot content:

```html
Expand All @@ -170,6 +172,8 @@ PortalVue can also be used with [Scoped Slots](https://vuejs.org/v2/guide/compon

### Transitions

> since `1.2.0`
You can pass transitions to a `<portal>` without problems. It will behave just the same when the content is being rendered in the `<portal-target>`:

```html
Expand Down

0 comments on commit 081b93a

Please sign in to comment.