Skip to content
Runner of JavaScript handlers and enhancers.
JavaScript
Branch: master
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
src Add basic constants file Feb 28, 2019
test Fix expect functions due to jest update Feb 28, 2019
.editorconfig Add .mjs files to .editorconfig Jul 5, 2019
.eslintignore Add ESLint Oct 25, 2018
.eslintrc Require @grrr-utils Nov 21, 2018
.gitignore Add package-lock.json to .gitignore in favour of yarn.lock Oct 25, 2018
.npmignore
.travis.yml Remove obsolete and update remaining dependencies Feb 28, 2019
README.md Update README Feb 28, 2019
babel.config.js Remove obsolete and update remaining dependencies Feb 28, 2019
index.mjs Add index.mjs for centralized exports since build step is removed Feb 28, 2019
package.json Add homepage entry to package.json Aug 15, 2019
yarn.lock Update dependencies Jul 25, 2019

README.md

Hansel

Build Status

Runner of handlers and enhancers

  • Lightweight (less than 1kb minified and gzipped)
  • Transpile to desired browser target
  • No dependencies (except a minor utility function)

Based on the article "Progressive enhancement with handlers and enhancers" by Hidde de Vries. We've been using this model for many years with great pleasure, fine-tuning here and there.

Read the article for a deeper explanation.

Installation

Using npm:

npm install @grrr/hansel

Note: depending on your setup additional configuration might be needed (see below).

Usage

Import into your main JavaScript file:

import { enhance, handle } from '@grrr/hansel';

enhance(document.documentElement, {
    enhancer1(elm) {
    },
    enhancer2(elm) {
    },
    enhancerN(elm) {
    }
});

handle(document.documentElement, {
    handler1(elm, event) {
    },
    handler2(elm, event) {
    },
    handlerN(elm) {
    }
});

Enhancers

enhance will look for DOM nodes containing the data-enhancer attribute. The second argument is a lookup table for enhancer functions. The value of the data-enhancer attribute will be matched with the table and if found, executed, given the element as first argument:

// Given <p data-enhancer="foo" data-message="Hello!"></p>

enhance(document.documentElement, {
  foo(elm) {
    console.log(elm.getAttribute('data-message')); // "Hello!"
  }
});

Multiple enhancers are possible by comma-separating them:

<div data-enhancer="foo,bar"></div>

Handlers

Handlers are called on click, using a global event listener on the document. Meta-clicks are caught and not passed on to the handler.

// Given <button data-handler="shout" data-message="Hello!">shout</button>

handle(document.documentElement, {
  shout(elm, e) {
    alert(elm.getAttribute('data-message')); // "Hello!"
    e.preventDefault();
  }
});

Multiple handlers are possible by comma-separating them:

<a data-handler="foo,bar" href="/">Do the thing</a>

Furthermore

Thanks to the global click listener, handlers do not have to be re-initialized to dynamically added content. The presence of a data-handler attribute is enough.

Enhancers are run immediately however, so you might want to run them again, for instance when loading new DOM nodes in response to an AJAX call. The first argument to enhance is the container element within which nodes are searched. Therefore, you can pass the parent to the newly created nodes as reference to enhance all its children:

const myContainer = document.querySelector('foo');
myContainer.innerHTML = htmlContainingEnhancedElements;

enhance(myContainer, myEnhancers);

Usage with build tools

This package is published with untranspiled JavaScript. All files are in the form of ECMAScript Modules (ESM), with .mjs as file extension. This means that you'll need to transpile the package yourself.

Not every build tool or bundler will recognize .mjs files correctly, and not every setup will transpile these files when they're in the node_modules folder. Here's a list with commonly used tools and usage instructions:

Webpack

The latest version of Webpack should transpile .mjs files properly when used with the default Babel loader (babel-loader).

Rollup

The latest version of Rollup should transpile .mjs files properly when used with the default Babel plugin (rollup-plugin-babel).

Browserify

Use the following babelify settings to transform .mjs files in the node_modules:

global: true,
ignore: /\/node_modules\/(?!.*.*\/.*.mjs)/,

The esmify plugin might also prove to be usefull.

Babel

If you're transpiling with Babel in any other setup, use the following ignore pattern to properly ignore the node_modules and allow .mjs files to be transpiled:

ignore: [/\/node_modules\/(?!.*.*\/.*.mjs)/],

This can be added in your babel.config.js, .babelrc or package.json; quotes will be necessary for JSON-based configurations.

You can’t perform that action at this time.