Namespace: Elements:prime

Elements:prime

Source:

Methods

prime(node, init, classChangesopt, nullable, markerAttributesNameopt, nullable) → {Basic.Deferred}

Offers an execution frame for element preparation like setting handlers and transforming dom. Takes a function including the initialization code of an element and wraps it with a check if this initialization was already executed (via data-attribute) as well as a document ready handler to make sure no initializations are executed with a half-ready dom.

If the initialization function returns a Promise or Deferred, the returned Deferred will resolve or reject accordingly with the same result value or rejection. If init does not return a Promise or Deferred, the returned Deferred will resolve as soon as document ready was reached. So, to be able to work with applied changes on the element after calling prime you have three options:

  1. Either make sure document ready occurred before prime(), so init gets called synchronously right away.
  2. Wrap the code after prime a DOM-ready-check as well, to establish a synchronous event order.
  3. Use the returned Deferred's .then().

During priming, the node receives three data-attributes, stating the current step. The attribute name is built according to the value of markerAttributeNames like this:

  1. data-${markerAttributeNames}="true" => as soon as prime is executed on the node
  2. data-${markerAttributeNames}-ready="true" => as soon as the init function has been executed and the dom is ready
  3. data-${markerAttributeNames}-resolved="true" => as soon as the returned Deferred has resolved
Parameters:
Name Type Attributes Default Description
node HTMLElement

the element to prime
init function

the function containing all initialization code for the node, the return value may either also be a Promise or Deferred (probably resolving to a value), the return value will be used to resolve the returned Deferred of the function; if you need to detect repeated prime calls on the same element, it is a good idea to let init return something other than "undefined", since that value also signifies a repeated call
classChanges Object.<String, (String|Array.<String>)> <optional>
<nullable>
 null

if set, may contain the keys "add" and/or "remove" holding standard class strings or arrays of standard class strings, defining which classes to add and/or remove once priming is done, helpful to automatically remove visual cloaking or set ready markers; adding has precedence over removing
markerAttributesName String <optional>
<nullable>
 'primed'

this function uses data-attributes to mark priming status, this is the name used to construct these attributes (default: data-primed*="...")
Source:
Throws:

  • error if node is not a usable HTML element

  • error if init is not a function

Returns:
resolves to the return value of init function or to `undefined` if element was already primed
Type
Basic.Deferred
Example
prime(widget, () => { return Promise.resolve(); });
prime(anotherWidget, () => { return somethingLongRunningAsync(); })).then(function(){ ... })
prime(yetAnotherWidget, node => { magicallyTransform(node); }, {remove : 'cloaked'});