Skip to content
fbasso edited this page Oct 6, 2014 · 3 revisions

Custom attributes

What are they ?

To understand the concept, please consider the following template:

{template hello(model)}
    <div class="{'foo', 'bar': model.isBar}" collapse onswipe="{model.swipeHandler(event)}">
        Hello {model.name}!
        <input type="text" model="{model.name}"/><br/>
    </div>
{/template}

In the the HTMLElement, it contains several custom attributes in fact: class, collapse, onswipe and model. A custom attribute is either a standard attribute but with a custom value/behavior, or a non standard one.

They can be defined in the core of the framework (class, model), as part of an optional module of the framework (onswipe from Gestures), or at application level (collapse).

Implementation

Initial implementation was done in PR https://github.com/ariatemplates/hashspace/pull/257

Global registry

Custom attributes are registered globally via a method defined in hsp/rt.js. Once registered, they will apply to the full application.
For example:

var hsp = require("../rt");
var ClassHandler = require('./attributes/class');
hsp.registerCustomAttributes("class", ClassHandler);
var ModelValueHandler = require('./attributes/modelvalue');
hsp.registerCustomAttributes(["model", "value"], ModelValueHandler, 0, ["input", "textarea"]);

The idea here is to associate one or more custom attributes to a handler with a priority for all or some HTML elements.
The priority determines the order in which the handlers will be created and called back in case several handlers are defined for the same attribute and node.

Handler

The handler is a javascript object which defines some methods (see API below). It is instantiated by Hashspace for every matching element created (i.e. EltNode instances).
It can be defined using the hsp/klass.js utility, or with a raw javascript object. See simple examples in the tests: https://github.com/mlaval/hashspace/blob/customAttributes/test/rt/customAttributes.spec.hsp

API

  • $constructor(nodeInstance, callback): executed when the EltNode instance is created (from EltNode.createNode())
  • $setValue(name, value): executed when the value of attribute name has changed (from EltNode.refreshAttributes())
  • $onAttributesRefresh(): executed after the refresh of all attributes (from EltNode.refreshAttributes())
  • $handleEvent(event): executed when the Eltnode instance in handling an event (from EltNode.handleEvent)), the custom attribute should delegate event listeners to the node, using the register helper (see below).
  • $dispose(): executed when the EltNode is disposed (from EltNode.$dispose())

It is important to note that EltNode.refreshAttributes() is executed during the craete of the node instance, and in any subsequent refresh if one attribute is dirty.

Helpers in EltNode

The custom attribute receives a node instance in its $constructor. So it can fully integrate Hashspace's processes if the developer knows the inside mechanism.
To facilitate that, a set of helpers have been added to EltNode.

API

  • setAttributeValueInModel(name, value): set the attribute value in the data model
  • getAttributeValueInModel(name): get the attribute value in the data model
  • addEventListeners(eventNames): register a list of event listeners, they are added to the current element if not already part of the evtHandlers
  • getAncestorByCustomAttribute(name): return the first ancestor with the given custom attribute
  • getCustomAttributeHandlers(name): return the an array of the custom attribute handler instances for a given custom attribute

Samples

In PR #257, several features have been transformed into custom attributes:

In addition, a first version of the dropdown custom attribute for hashspace bootstrap is also available: https://github.com/mlaval/hashspace-bootstrap/blob/dropdown/src/dropdown/dropdown.js