@drupal/once
Mark DOM elements as processed to prevent multiple initializations.
Examples
<!-- Use as a module -->
<script type="module">
import once from 'https://unpkg.com/@drupal/once/src/once.js';
const elements = once('my-once-id', 'div');
// Initialize elements.
elements.forEach(el => el.innerHTML = 'processed');
</script>
<!-- Use as a regular script -->
<script src="https://unpkg.com/@drupal/once"></script>
<script>
const elements = once('my-once-id', 'div');
// Initialize elements.
elements.forEach(el => el.innerHTML = 'processed');
</script>
<!-- Using a single element as input-->
<script src="https://unpkg.com/@drupal/once"></script>
<script>
// once methods always return an array, to simplify the use with a single
// element use destructuring or the shift method.
const [myElement] = once('my-once-id', document.body);
const myElement = once('my-once-id', document.body).shift();
</script>
API
Array.<Element>
once(id, selector, [context]) ⇒ Ensures a JavaScript callback is only executed once on a set of elements.
Filters a NodeList or array of elements, removing those already processed
by a callback with a given id.
This method adds a data-once
attribute on DOM elements. The value of
this attribute identifies if a given callback has been executed on that
element.
Kind: global function
Returns: Array.<Element>
- An array of elements that have not yet been processed by a once call
with a given id.
Param | Type | Default | Description |
---|---|---|---|
id | string |
The id of the once call. | |
selector |
NodeList | Array.<Element> | Element | string
|
A NodeList or array of elements. | |
[context] |
Document | Element
|
document |
An element to use as context for querySelectorAll. |
Example (Basic usage)
const elements = once('my-once-id', '[data-myelement]');
Example (Input parameters accepted)
// NodeList.
once('my-once-id', document.querySelectorAll('[data-myelement]'));
// Array or Array-like of Element.
once('my-once-id', jQuery('[data-myelement]'));
// A CSS selector without a context.
once('my-once-id', '[data-myelement]');
// A CSS selector with a context.
once('my-once-id', '[data-myelement]', document.head);
// Single Element.
once('my-once-id', document.querySelector('#some-id'));
Example (Using a single element)
// Once always returns an array, even when passing a single element. Some
// forms that can be used to keep code readable.
// Destructuring:
const [myElement] = once('my-once-id', document.body);
// By changing the resulting array, es5 compatible.
const myElement = once('my-once-id', document.body).shift();
-
once(id, selector, [context]) ⇒
Array.<Element>
-
.remove(id, selector, [context]) ⇒
Array.<Element>
-
.filter(id, selector, [context]) ⇒
Array.<Element>
-
.find([id], [context]) ⇒
Array.<Element>
-
.remove(id, selector, [context]) ⇒
Array.<Element>
once.remove(id, selector, [context]) ⇒ Removes a once id from an element's data-drupal-once attribute value.
If a once id is removed from an element's data-drupal-once attribute value, the JavaScript callback associated with that id can be executed on that element again.
Kind: static method of once
Returns: Array.<Element>
- A filtered array of elements that had been processed by the provided id,
and are now able to be processed again.
Param | Type | Default | Description |
---|---|---|---|
id | string |
The id of a once call. | |
selector |
NodeList | Array.<Element> | Element | string
|
A NodeList or array of elements to remove the once id from. | |
[context] |
Document | Element
|
document |
An element to use as context for querySelectorAll. |
Example (Basic usage)
const elements = once.remove('my-once-id', '[data-myelement]');
Example (Input parameters accepted)
// NodeList.
once.remove('my-once-id', document.querySelectorAll('[data-myelement]'));
// Array or Array-like of Element.
once.remove('my-once-id', jQuery('[data-myelement]'));
// A CSS selector without a context.
once.remove('my-once-id', '[data-myelement]');
// A CSS selector with a context.
once.remove('my-once-id', '[data-myelement]', document.head);
// Single Element.
once.remove('my-once-id', document.querySelector('#some-id'));
Array.<Element>
once.filter(id, selector, [context]) ⇒ Finds elements that have been processed by a given once id.
Behaves like once and remove without changing the DOM. To select all DOM nodes processed by a given id, use find.
Kind: static method of once
Returns: Array.<Element>
- A filtered array of elements that have already been processed by the
provided once id.
Param | Type | Default | Description |
---|---|---|---|
id | string |
The id of the once call. | |
selector |
NodeList | Array.<Element> | Element | string
|
A NodeList or array of elements to remove the once id from. | |
[context] |
Document | Element
|
document |
An element to use as context for querySelectorAll. |
Example (Basic usage)
const filteredElements = once.filter('my-once-id', '[data-myelement]');
Example (Input parameters accepted)
// NodeList.
once.filter('my-once-id', document.querySelectorAll('[data-myelement]'));
// Array or Array-like of Element.
once.filter('my-once-id', jQuery('[data-myelement]'));
// A CSS selector without a context.
once.filter('my-once-id', '[data-myelement]');
// A CSS selector with a context.
once.filter('my-once-id', '[data-myelement]', document.head);
// Single Element.
once.filter('my-once-id', document.querySelector('#some-id'));
Array.<Element>
once.find([id], [context]) ⇒ Finds elements that have been processed by a given once id.
Query the 'context' element for elements that already have the corresponding once id value.
Kind: static method of once
Returns: Array.<Element>
- A filtered array of elements that have already been processed by the
provided once id.
Param | Type | Default | Description |
---|---|---|---|
[id] | string |
The id of the once call. | |
[context] |
Document | Element
|
document |
Scope of the search for matching elements. |
Example (Basic usage)
const oncedElements = once.find('my-once-id');
Example (Input parameters accepted)
// Call without parameters, return all elements with a `data-once` attribute.
once.find();
// Call without a context.
once.find('my-once-id');
// Call with a context.
once.find('my-once-id', document.head);