widjet

A simple and lightweight widget helper for the web.

Installation

npm install --save widjet

Usage

The simplest example of how to define and use a widget is as follow:

// Imports the widjet module
import widgets from 'widjet'

// Defines a simple widget that adds a class to the element it receives
widgets.define('my-widget-name', options => element => {
  element.classList.add('my-widget')
})

// Setup how and when the widget will be applied on the page
widgets('my-widget-name', '.widget-target-selector', {on: 'load'})

Widgets Definition

In the example above the first function is called the definition function, it's called on every use of the widget through the widgets function and it receives the options defined at that moment. It can either returns a function or an object.

The second function, returned by the definition function, is called the element handling function and will be called for every elements matched by the selector. This function will receive two arguments, the target element and the widget instance created for the target element. When called the function this object will refer to the Widget instance.

Inside the element handling function, you can register hooks for the widget lifecycle.

import widgets from 'widjet'

widgets.define('my-widget-name', options => (element, widget) => {
  // We're gonna use `widget` instead of `this` to register the lifecycle hooks
  // as we're using a fat arrow function
  widget.onInitialize = function () { console.log('initialized') }
  widget.onActivate = function () { console.log('activated') }
  widget.onDeactivate = function () { console.log('deactivated') }
  widget.onDispose = function () { console.log('disposed') }

  // ...

  // If the function returns a disposable-like object, it'll be used when
  // the widget will be disposed of
  return {
    dispose: function () {
      // dispose routine
    }
  }
})

In that example, the onInitialize hook is redundant since the definition function is executed during the widget initialization.

Another way, that is more convenient if you need to define all these lifecycle hooks, is to returns an object instead of a function in the definition function:

import widgets from 'widjet'

widgets.define('my-widget-name', options => {
  initialize: function () { console.log('initialized') },
  activate: function () { console.log('activated') },
  deactivate: function () { console.log('deactivated') },
  dispose: function () { console.log('disposed') }
})

The advantage of the former version is that you can benefit from the function closure for the various hooks. The latter version, on the other hand, promotes a more OOP-like structure where you'll have to store on the object what you want to access in the various methods.

Widgets Consumption

Once defined, a widget isn't automatically applied to a page, before that it must be registered with some page elements. This is done using the widgets function like this:

import widgets from 'widjet'

// Setup how and when the widget will be applied on the page
widgets('my-widget-name', '.widget-target-selector', {on: 'load'})

The first parameter is the name of the widget to register. The second argument is the CSS query (as supported by the querySelector and querySelectorAll methods) to match the elements that will be affected by the widget. The last argument is an option object where you can specify the various conditions for the widget to apply.

In the example above, the on option defines the events onto which the query will be performed to find elements fot this widget.

You can find the complete list of options below, any options that are not consumed by the widgets function will be passed to the widget.

Any option that is not in the list above will be collected and passed to the widget as its options.

A widget can't be applied twice on the same element. This is ensured by adding a specific class to the widget's element that marks the element as handled. When the widget is disposed, the class is removed and the element can be targeted again.