Latest Version: 2.0 RC 3 14 March 2017

Node Masking

One of the core bits of functionality of the elementals.js is how various DOM walking functions are able to mask the returned or walked elements by either their Element.nodeType or Element.tagName.

All functions that take a nodeMask can accept either a tagName or nodeMask. The former is relatively self explanatory. If you were to call:

var firstLi = _.nodeFirst(_d.body, 'li');

You will get the first LI in the document body.

Using a nodeMask is a bit more complex. It is performed using a binary mask where the Element.nodeType being tested is used to shift the value "1" left by nodeType minus 1. This value is then binary "and"ed against the mask as our test.

For example, if we wanted to find text nodes -- aka nodeType 3 -- we would send a mask of 4, as 1 << (3 - 1) == 4. Because a binary AND is performed, we can check for multiple nodeTypes at once. For example if we wanted to search for TEXT_NODE (type 3, mask 4) and COMMENT_NODE (type 8, mask 128) at the same time, we would pass 131, aka 0x84 hex.

The following values are predefined in the Elementals library to aid with this:

_.NODEMASK_ELEMENT    = 0x0001;
_.NODEMASK_TEXT       = 0x0004;
_.NODEMASK_COMMENT    = 0x0080;
_.NODEMASK_DOCTYPE    = 0x0200;

No reference values are provided for deprecated node types.

As such if you wanted to search body for the first text or comment node, you could simply call:

var e = _.nodeFirst(_d.body, _.NODEMASK_TEXT || _.NODEMASK_COMMENT);

On all functions that verify node masks, if no mask or tagName is passed _.NODEMASK_ELEMENT is used as the default.