Skip to content

Commit

Permalink
fix(readme): correct doc
Browse files Browse the repository at this point in the history
  • Loading branch information
@bigopon
bigopon committed Jan 15, 2018
1 parent c751614 commit be38f1a
Show file tree
Hide file tree
Showing 3 changed files with 122 additions and 74 deletions.
5 changes: 3 additions & 2 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -100,8 +100,9 @@ A simple solution is to use CSS: `position: fixed` on the list and calculat its
</template>
```

`portal` attribute may seem tobe an overkill, but it helps you separate DOM path of different parts in your custom element, whist still binds them
to the same underlying view model, which should helps better DOM manangement, including event model in some cases. Following is an example of final rendered DOM tree for `<combobox/>` above:
`portal` attribute may seem to be an overkill, but beside styling, it also helps you separate DOM path of different parts in your custom element,
whist still binds them to the same underlying view model, which should helps better DOM manangement, including event model in some cases.
Following is an example of final rendered DOM tree for `<combobox/>` above:

```html
<body>
Expand Down
189 changes: 118 additions & 71 deletions doc/article/en-US.md
View file
Original file line number Diff line number Diff line change
@@ -1,108 +1,155 @@
---
{
"name": "Aurelia Blur Plugin",
"culture": "en-US",
"description": "The guide of the blur plugin for Aurelia.",
"engines" : { "aurelia-doc" : "^1.0.0" },
"author": {
"name": "Binh Vo",
"url": "http://bigopon.surge.sh"
},
"contributors": [],
"translators": [],
"keywords": ["Blur", "Focus", "JavaScript"]
}
---
# aurelia-portal-attribute

## [Introduction](aurelia-doc://section/1/version/1.0.0)
[![Join the chat at https://gitter.im/aurelia/discuss](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/aurelia/discuss?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
[![CircleCI](https://circleci.com/gh/bigopon/aurelia-portal-attribute.svg?style=svg)](https://circleci.com/gh/bigopon/aurelia-portal-attribute)

This article covers the blur plugin for Aurelia. This plugin is created for managing focus in your application. The plugin supports the use of dynamic elements matching, via either element references or CSS selectors.
## [Introduction]

This article covers the portal attribute plugin for Aurelia. This plugin is created for managing rendering flow of part of custom element in an Aurelia application. The plugin supports the use of dynamic elements matching as render target, via either element references or CSS selectors. [Online Demo](http://aurelia-portal.bigopon.surge.sh/)

## [Installing The Plugin](aurelia-doc://section/2/version/1.0.0)

## [Installing The Plugin]

1. In your **JSPM**-based project install the plugin via `jspm` with following command

```shell
jspm install aurelia-blur-plugin
jspm install aurelia-portal-attribute
```

If you use **Webpack**, install the plugin with the following command

```shell
npm install aurelia-blur-plugin --save
npm install aurelia-portal-attribute --save
```

If you use the **Aurelia CLI**, install the plugin with the following command

```shell
npm install aurelia-blur-plugin --save
au import aurelia-portal-attribute
```

alternatively you can manually add these dependencies to your vendor bundle:

```json
...
"dependencies": [
{
"name": "aurelia-portal-attribute",
"path": "../node_modules/aurelia-portal-attribute/dist/amd",
"main": "aurelia-portal-attribute"
}
]
```

2. Make sure you use [manual bootstrapping](http://aurelia.io/docs#startup-and-configuration). In order to do so open your `index.html` and locate the element with the attribute aurelia-app. Change it to look like this:

<code-listing heading="index.html">
<source-code lang="HTML">
```html
<body aurelia-app="main">...</body>
</source-code>
</code-listing>
```

3. Create (if you haven't already) a file `main.js` in your `src` folder with following content:
3. In `main.js` in your `src`:

<code-listing heading="main.js">
<source-code lang="ES 2015">
```js
export function configure(aurelia) {

/**
* We will cover reasons behind these options in later sections
*/
let listeningModeOptions = {
pointer: false, // listen for pointer event interaction
touch: false, // listen for touch event interaction
mouse: false, // listen for mouse event interaction
focus: false, // listen for foucs event
windowBlur: false // listen for window blur event (navigating away from window)
}

aurelia.use
.standardConfiguration()
.developmentLogging()
.plugin('aurelia-blur-plugin', listeningModeOptions);
.standardConfiguration()
.plugin(PLATFORM.moduleName('aurelia-portal-attribute'))

aurelia.start().then(a => a.setRoot());
}
</source-code>
</code-listing>
```

## [Using The Plugin]

There are a few scenarios you can take advantage of the attribute.

## [Using The Plugin](aurelia-doc://section/3/version/1.0.0)
1. There is part of the element that needs to be rendered into document body.
This is a common case, as the component may be nested under a `overflow: hidden` ancestor and it won't be able to display properly. Consider the following dom structure of a custom `<combobox />` element:

There are a few scenarios you can take advantage of the Aurelia blur plugin.
```html
<template class="combobox">
<div class="input-ct">
<input ref="input" value.bind="filterText" />
<div>
<ul class="list-group items-list">
<li repeat.for="item of items | filter: filterText" class="list-group-item">${item.name}</li>
</ul>
</template>
```

1. You can use the dialog service to control when a form should be hidden.
This is a common case, consider the following dom structure
This structure often works fine when we have `ul.list-group.item-list` CSS: `position: absolute; top: 100%;` But it will not work when the custom element is nested inside an element with `overflow: hidden`, or inside an element with scroll, like following example:

![](http://i.imgur.com/oBF5Ryv.png)
```html
<!-- app.html -->
<div style="height: 200px; overflow: auto;">
<!-- oopps, my list got clipped -->
<combobox></combobox>
</div>
```

It's clear that our intent is only trigger the blur, when we interact with any elements outside the form element. One may implement it like following:
A simple solution is to use CSS: `position: fixed` on the list and calculat its position, or the `portal` attribute like the following example:

<code-listing heading="naive-blur.js">
<source-code lang="html">
```html
<template class="combobox">
<div class="input-ct">
<input ref="input" value.bind="filterText" />
<div>
<button click.delegate="formIsBlur = false">Show Form</button>
<form if.bind="formIsBlur">
<input blur.trigger="formIsBlur = true" />
<select blur.trigger="formIsBlur = true"></select>
<input blur.trigger="formIsBlur = true" />
</form>

<!-- Or more optimized version -->
<form blur.capture="formIsBlur = true">
<input />
<select></select>
<input />
</form>
</div>
</source-code>
</code-listing>

This is often insufficient, as what we do want is to react when either (pointer/ touch/ mouse) down, or focus on elements outside of the form, but what we will get is any focus navigation between inputs. The plugin solves this for you, by listening to some critical events to determine if focus is still inside an element.
<ul portal class="list-group items-list">
<li repeat.for="item of items | filter: filterText" class="list-group-item">${item.name}</li>
</ul>
</template>
```

`portal` attribute may seem to be an overkill, but beside styling, it also helps you separate DOM path of different parts in your custom element,
whist still binds them to the same underlying view model, which should helps better DOM manangement, including event model in some cases.
Following is an example of final rendered DOM tree for `<combobox/>` above:

```html
<body>
<app>
<combobox>
<!-- combobox internal elements -->
</combobox>
</app>
<!-- combobox item list in the body -->
<ul class="list-group items-list">
<li class="list-group-item">item 1</li>
<li class="list-group-item">item 2</li>
<li class="list-group-item">item 3</li>
...
<!-- more items -->
</ul>
</body>
```

## Usage Examples / Scenarios

TODO

## Building The Code

To build the code, follow these steps.

1. Ensure that [NodeJS](http://nodejs.org/) is installed. This provides the platform on which the build tooling runs.
2. From the project folder, execute the following command:

```shell
npm install
```

3. To build the code, you can now run:

```shell
npm run build
```

4. You will find the compiled code in the `dist` folder, available in three module formats: AMD, CommonJS and ES6.

## Running The Tests

```shell
npm test
```

## Acknowledgement
Thanks goes to Dwayne Charrington for his Aurelia-TypeScript starter package https://github.com/Vheissu/aurelia-typescript-plugin
2 changes: 1 addition & 1 deletion package.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -119,4 +119,4 @@
"release": {
"verifyConditions": "condition-circle"
}
}
}

0 comments on commit be38f1a

Please sign in to comment.