aurelia-blur-attribute

[Introduction]

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. Online Demo

[Installing The Plugin]

In your JSPM-based project install the plugin via jspm with following command

jspm install aurelia-blur-attribute

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

npm install aurelia-blur-attribute --save

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

au import aurelia-blur-attribute

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

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

Make sure you use manual bootstrapping. In order to do so open your index.html and locate the element with the attribute aurelia-app. Change it to look like this:

  <body aurelia-app="main">...</body>

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

  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: true, // 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-attribute', listeningModeOptions);
 
    aurelia.start().then(a => a.setRoot());
  }

[Using The Plugin]

There are a few scenarios you can take advantage of the Aurelia blur plugin.

You can use the dialog service to control when a form should be hidden. This is a common case, consider the following dom structure

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:

  <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 if.bind="formIsBlur" blur.capture="formIsBlur = true">
      <input />
      <select></select>
      <input />
    </form>
  </div>

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.

  <div>
    <button click.delegate="formIsBlur = false">Show Form</button>
    <form if.bind="formIsBlur" blur.bind="formIsBlur">
      <input />
      <select ></select>
      <input />
    </form>

Notice the attribute differences: blur.capture / blur.trigger vs blur.bind. When using blur.bind, we are using the plugin, instead event listener.

Usage Examples / Scenarios

TODO

Building The Code

To build the code, follow these steps.

Ensure that NodeJS is installed. This provides the platform on which the build tooling runs.
From the project folder, execute the following command:

npm install

Ensure that Gulp is installed. If you need to install it, use the following command:

npm install -g gulp

To build the code, you can now run:

npm run build

You will find the compiled code in the dist folder, available in three module formats: AMD, CommonJS and ES6.
See gulpfile.js for other tasks related to generating the docs and linting.

Running The Tests

npm run test

Acknowledgement

Thanks goes to Dwayne Charrington for his Aurelia-TypeScript starter package https://github.com/Vheissu/aurelia-typescript-plugin