Neglected Puppy Market

    sentinel-js

    0.0.5 • Public • Published

    SentinelJS

    SentinelJS is a tiny JavaScript library that lets you detect new DOM nodes using CSS selectors (653 bytes).

    Introduction

    SentinelJS is a tiny JavaScript library that makes it easy to set up a watch function that will notify you anytime a new node is added to the DOM that matches a given CSS rule. Among other things, you can take advantage of this to implement custom-elements and make other in-place modifications to new DOM elements:

    <script>
      sentinel.on('custom-element', function(el) {
        // A new <custom-element> has been detected
        el.innerHTML = 'The sentinel is always watching.';
      });
    </script> 
    <custom-element></custom-element>

    SentinelJS uses dynamically-defined CSS animation rules (@keyframes) to hook into browser animationstart events when a new node matching a given CSS selector is added to the DOM. In general this should be more performant than using a Mutation Observer to watch the entire document tree for changes and iterating through all new child nodes recursively. SentinelJS performs one hash key lookup on calls to the animationstart event so the performance overhead is minimal. If you define the animation-name property on a CSS rule that overlaps with the selector in your SentinelJS watch function then only one of those animations will be called which could cause unexpected behavior. To get around this you can trigger SentinelJS watches from your CSS using custom animation names (see below).

    The latest version of SentinelJS can be found in the dist/ directory in this repository:

    You can also use it as a CJS or AMD module:

    $ npm install --save sentinel-js
    var sentinel = require('sentinel-js');
     
    sentinel.on('custom-element', function(el) {
      // A new <custom-element> has been detected
      el.innerHTML = 'The sentinel is always watching.';
    });

    SentinelJS is 653 bytes (minified + gzipped).

    Quickstart

    <!doctype html>
    <html>
      <head>
        <script src="//cdn.rawgit.com/muicss/sentineljs/0.0.5/dist/sentinel.min.js"></script> 
        <script>
          // use the `sentinel` global object
          sentinel.on('.my-div', function(el) {
            el.innerHTML = 'The sentinel is always watching.';
          });
     
          // add a new div to the DOM
          function addDiv() {
            var newEl = document.createElement('div');
            newEl.className = 'my-div';
            document.body.appendChild(newEl);
          };
        </script> 
      </head>
      <body>
        <button onclick="addDiv();">Add another DIV</button>
        <div class="my-div"></div>
      </body>
    </html>

    View Demo »

    Browser Support

    • IE10+
    • Opera 12+
    • Safari 5+
    • Chrome
    • Firefox
    • iOS 6+
    • Android 4.4+

    Documentation

    API

    on() - Add a watch for new DOM nodes

    on(cssSelectors, callbackFn)
    
      * cssSelectors {Array or String} - A single selector string or an array
      * callbackFn {Function} - The callback function
    
    Examples:
    
    1. Set up a watch for a single CSS selector:
    
       sentinel.on('.my-div', function(el) {
         // add an input box
         var inputEl = document.createElement('input');
         el.appendChild(inputEl);
       });
      
    2. Set up a watch for multiple CSS selectors:
     
       sentinel.on(['.my-div1', '.my-div2'], function(el) {
         // add an input box
         var inputEl = document.createElement('input');
         el.appendChild(inputEl);
       });
    
    3. Trigger a watch function using custom CSS (using "!"):
    
       <style>
         @keyframes slidein {
           from: {margin-left: 100%}
           to: {margin-left: 0%;}
         }
    
         .my-div {
           animation-duration: 3s;
           animation-name: slide-in, node-inserted;
         }
       </style>
       <script>
         // trigger on "node-inserted" animation event name (using "!")
         sentinel.on('!node-inserted', function(el) {
           el.insertHTML = 'The sentinel is always watching.';
         });
       </script>
    

    off() - Remove a watch or a callback

    off(cssSelectors[, callbackFn])
    
      * cssSelectors {Array or String} - A single selector string or an array
      * callbackFn {Function} - The callback function you want to remove the watch for (optional)
    
    Examples:
    
    1. Remove a callback:
     
       function myCallback(el) { /* do something awesome */ }
    
       // add listener
       sentinel.on('.my-div', myCallback);
    
       // remove listener
       sentinel.off('.my-div', myCallback);
    
    2. Remove a watch:
    
       // add multiple callbacks
       sentinel.on('.my-div', function fn1(el) {});
       sentinel.on('.my-div', function fn2(el) {});
    
       // remove all callbacks
       sentinel.off('.my-div');
    

    reset() - Remove all watches and callbacks

    reset()
    
    Examples:
    
    1. Remove all watches and callbacks from the sentinel library:
    
       // add multiple callbacks
       sentinel.on('.my-div1', function fn1(el) {});
       sentinel.on('.my-div2', function fn2(el) {});
    
       // remove all watches and callbacks
       sentinel.reset();
    

    Async Loading

    To make it easy to use SentinelJS asynchronously, the library dispatches a sentinel-load event that will notify you when the library is ready to be used:

    <!doctype html>
    <html>
      <head>
        <script src="//cdn.rawgit.com/muicss/sentineljs/0.0.5/dist/sentinel.min.js" async></script> 
        <script>
          // use the `sentinel-load` event to detect load time
          document.addEventListener('sentinel-load', function() {
            // now the `sentinel` global object is available
            sentinel.on('.my-div', function(el) {
              el.innerHTML = 'The sentinel is always watching.';
            });
          });
        </script> 
      </head>
      <body>
        <div class="my-div"></div>
      </body>
    </html>

    Icons made by Freepik from www.flaticon.com is licensed by CC 3.0 BY

    Install

    npm i sentinel-js

    DownloadsWeekly Downloads

    1,948

    Version

    0.0.5

    License

    MIT

    Unpacked Size

    329 kB

    Total Files

    26

    Last publish

    Collaborators

    • muicss