DOM Observer API

spy.on()

async

Enables the passed components identified by the passed names to observe the matched DOM elements.

  • Accepts arguments as strings and arrays of strings.
    You can pass component names as individual arguments, as an array, or as a string separated by commas or spaces.
    Each value is seen as a new argument.
    Accepts an optional last argument as an object with the following options:
    Option
    Type
    Default
    Description
    subtree
    boolean
    true
    Set to true to enable monitoring of the entire subtree of nodes rooted at the target.
    All properties will apply to the entire subtree rather than just the target node.
    Changes in a descendant subtree will still be observed even after the descendant is removed, until the removal notification is delivered.
    childList
    boolean
    true
    Set to true to monitor the target node (and its descendants, if subtree is true) for added or removed child nodes.
    attributes
    boolean
    true
    Set to true to monitor attribute value changes on the observed nodes.
    attributeFilter
    array
    none
    An array of attribute names to monitor, if omitted, all attribute changes trigger notifications.
    attributeOldValue
    boolean
    true
    Set to true to capture the previous value of any changing attribute while monitoring for attribute changes on nodes.
    characterData
    boolean
    true
    Set to true to monitor the target node (and its descendants, if subtree is true) for changes to its character data.
    characterDataOldValue
    boolean
    true
    Set to true to capture the previous text value whenever it changes on monitored nodes.
    All options are optional.
    If an "events.mutation" object is defined in the "config.js" configuration file, it will override the default values.
  • A new observer will be enabled for each combination of component and matched DOM element.
  • For each trigger notification on the matched DOM elements, the observing components will be called, and a MutationRecord object will be passed to each observer component.
  • Returns true if the observer was successfully enabled, false otherwise.
  • It is not necessary to wait for the method to be executed using await if not needed.
Example: 
$('div').spy.on('component_1');
// Enable the component 'component_1' to observe the <div> element.

$('div ?').spy.on('component_1', 'component_2');
$('div ?').spy.on(['component_1', 'component_2']);
$('div ?').spy.on('component_1, component_2');
$('div ?').spy.on('component_1 component_2');
// Enable the components 'component_1' and 'component_2' to observe all <div> elements.

$('div ?').spy.on('component_1', 'component_2', {
   subtree: true,
   childList: true,
   attributes: true,
   attributeFilter: ['class', 'data-book'],
   attributeOldValue: true,
   characterData: true,
   characterDataOldValue: true
});
// Enable the components 'component_1' and 'component_2' to observe all <div> elements based on the provided options.

await $('div').spy.on('component_1');
// Waits for the method to complete its execution.
Previous spy.get() Next spy.off()