Blue-widgets NPM

blue-widgets

blue-widgets** is a class-based widget library for adding complex javascript functionality to existing DOM elements

v3 breaking changes

WeakMap() support required

Parse order has changed of the widgets in order to better support composeability. So whereas before widgets were parsed in the order they were discovered, now descendant widgets are parsed first. So if I now call getDescendants in the onWidgetsReady lifecycle method, all descendants will have already been initialised.

Browser Support

IE11+ and all other modern browsers out of the box. For support down to IE9 you'll need to polyfill WeakMap()

Installation

npm install blue-widgets

Tutorial

Creating a basic widget

Take this html:

<body>
  <div data-widget="ShowHide">
    <a href="#" data-trigger>ShowHide trigger - click me!</a>
    <div data-content>
      <p>Some example content</p>
      <p>Some more example content</p>
      <table>
        <tr>
          <td>
            test
          </td>
        </tr>
      </table>
    </div>
  </div>
</body>

Create our widget Class

In ./widgets/ShowHide/index.js

import { hasClass, toggleClass } from 'blue-js'
import { Widget } from 'blue-widgets'

const OPEN_CLASS = 'is-open'

class ShowHide extends Widget {
  constructor (el) {
    super(el)
    this.trigger = el.querySelector('[data-trigger]')
    this.content = el.querySelector('[data-content]')

    this.content.style.display = hasClass(el, OPEN_CLASS) ? 'block' : 'none'

    this.trigger.addEventListener('click', this.onTriggerClick.bind(this), false)
  }
  onTriggerClick (event) {
    event.preventDefault()
    this.toggle()
  }
  toggle () {
    this.content.style.display = hasClass(this.el, OPEN_CLASS) ? 'none' : 'block'
    toggleClass(this.el, OPEN_CLASS)
  }
}

export default ShowHide

Add widget to registry and parse for widgets in app.js

import { defineWidgets, parse } from 'blue-widgets'
import ShowHide from './widgets/ShowHide'

// Add widgets to the registry
defineWidgets({
  ShowHide
})
/* NOTE: this is the ES6 equivalent of
defineWidgets({
  ShowHide: ShowHide
})
*/

// Parse the dom for widget instances
parse()

API

Classes

Functions

Widget

Kind: global class

Widget
- new Widget(el, [opts])
- .el : HTMLElement
- .ref : String
- .options : Object
- .getOptions() ⇒ Object
- .onWidgetsReady()
- .beforeRemove()

new Widget(el, opts)

The base Widget class from which other widgets are extended. Technically the parser can create widgets using any Class at all (rather than only ones that extend off the Widget class). This base widget provides some convenience setup options and lifecycle methods that work well with the parser/registry though.

Param	Type	Description
el	HTMLElement	The dom node of the Widget instance
opts	Object	Optional options to be passed to the constructor. Only used if the widget is constructed directly (using the `new` keyword rather than using the parser)

widget.el : HTMLElement

The html element that the instance was created using

Kind: instance property of Widget

widget.ref : String

The reference of the widget in the registry. Only set if the widget was created using the parser. Defaults to the elements data-ref attribute - if not set the registry will automatically create a unique ref during parsing.

Kind: instance property of Widget
Default: 'The elements data-ref attribute'
Read only: true

widget.options : Object

The widget options. An object created by merging this.getOptions(), opts from the constructor, and the base elements dataset.

Kind: instance property of Widget
Example

class CustomWidget extends Widget {
  // The default widget options
  getOptions () {
    return { openClass: 'is-open' }
  }
}

// Override option in the html <div data-widget="CustomWidget" data-open-class="open">
// this.options in the widget instance would be { openClass: 'open' } in this case

widget.getOptions() ⇒ Object

Returns the default widget options

Kind: instance method of Widget
Returns: Object - The default widget options

widget.onWidgetsReady()

Lifecycle method: Fires when all widgets in the current parse cycle have been created

Kind: instance method of Widget

widget.beforeRemove()

Lifecycle method: Fires when a widget is destroyed using registry.destroy or registry.destroyDescendants

Kind: instance method of Widget

defineWidgets(widgets)

Adds an object of widget classes to the registry library

Kind: global function

Param	Type	Description
widgets	Object.<string, Class>	Object of key value pair widgets to add to the library. The key is the name and the value is the Class itself

parse(el, pattern, typeFn) ⇒ Promise.<Array>

Parse an element for widget instances and add them to the registry. By default looks for elements with a data-widget attribute

Kind: global function
Returns: Promise.<Array> - A Promise fulfilled with an array of the parsed instances

Param	Type	Default	Description
el	HTMLElement		A dom element
pattern	string	"data-widget"	Optional string for setting the selector pattern to match in the querySelectorAll call
typeFn	function	el => el.dataset.widget	Optional function for returning the type to look up in the registry'

getInstance(ref)

Get a widget instance from the registry

Kind: global function

Param	Type	Description
ref	string \| HTMLElement	The ref of the widget we want to fetch, or the actual html element the widget was created on

getDescendants(parent, widgetType) ⇒ array

Gets all descendants of the passed element.

Kind: global function
Returns: array - An array containing the matching descendants

Param	Type	Description
parent	HTMLElement	The parent dom element
widgetType	string \| Class	The type of the widget - as a string will only match instances of those widget classes that are stored under that exact name - as a Class will match all widgets that are instances of that class including subclasses.

destroyInstance(widgetRef, recursive)

Removes a widget instance from the registry (doesn't remove the element itself, just the widget instances)

Kind: global function

Param	Type	Default	Description
widgetRef	string \| HTMLElement		The ref of the widget we want to remove, or the actual html element the widget was created on
recursive	boolean	true	Whether to also destory a widgets descendants

destroyDescendants(parent, widgetType)

Removes descendant widgets from the registry (does not remove the actual dom nodes)

Kind: global function

Param	Type	Description
parent	HTMLElement	The parent dom element
widgetType	string \| Class	Optional type of the widget children to remove - as a string will only match instances of those widget classes that are stored under that exact name - as a Class will match all widgets that are instances of that class including subclasses.