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:
ShowHide trigger - click me! Some example content Some more example content test
Create our widget Class
In ./widgets/ShowHide/index.js
const OPEN_CLASS = 'is-open' { superel thistrigger = el thiscontent = el thiscontentstyledisplay = ? 'block' : 'none' thistrigger } { event this } { thiscontentstyledisplay = ? 'none' : 'block' }
Add widget to registry and parse for widgets in app.js
// Add widgets to the registry/* NOTE: this is the ES6 equivalent ofdefineWidgets({ ShowHide: ShowHide})*/ // Parse the dom for widget instances
API
Classes
Functions
- defineWidgets(widgets)
Adds an object of widget classes to the registry library
- 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- getInstance(ref)
Get a widget instance from the registry
- getDescendants(parent, [widgetType]) ⇒
array
Gets all descendants of the passed element.
- destroyInstance(widgetRef, [recursive])
Removes a widget instance from the registry (doesn't remove the element itself, just the widget instances)
- destroyDescendants(parent, [widgetType])
Removes descendant widgets from the registry (does not remove the actual dom nodes)
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) |
HTMLElement
widget.el : The html element that the instance was created using
Kind: instance property of Widget
String
widget.ref : 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
Object
widget.options : 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
// The default widget options { 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
Object
widget.getOptions() ⇒ 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 |
Promise.<Array>
parse(el, [pattern], [typeFn]) ⇒ 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 |
array
getDescendants(parent, [widgetType]) ⇒ 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. |