Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/muicss/sentineljs
Detect new DOM nodes using CSS selectors (650 bytes)
https://github.com/muicss/sentineljs
dom javascript
Last synced: 3 months ago
JSON representation
Detect new DOM nodes using CSS selectors (650 bytes)
- Host: GitHub
- URL: https://github.com/muicss/sentineljs
- Owner: kubetail-org
- License: mit
- Created: 2017-09-18T07:45:24.000Z (about 7 years ago)
- Default Branch: master
- Last Pushed: 2023-07-31T03:54:38.000Z (over 1 year ago)
- Last Synced: 2024-05-22T23:46:50.128Z (5 months ago)
- Topics: dom, javascript
- Language: JavaScript
- Homepage:
- Size: 173 KB
- Stars: 1,126
- Watchers: 18
- Forks: 51
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE.txt
- Authors: AUTHORS.txt
Awesome Lists containing this project
README
# SentinelJS
SentinelJS is a tiny JavaScript library that lets you detect new DOM nodes using CSS selectors (668 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:
```html
sentinel.on('custom-element', function(el) {
// A new <custom-element> has been detected
el.innerHTML = 'The sentinel is always watching.';
});
```
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). Another issue to be aware of is that SentinelJS will not detect elements with CSS style `display:none` (but it will detect elements with `visibility:hidden`).
The latest version of SentinelJS can be found in the `dist/` directory in this repository:
* [sentinel.js](https://raw.githubusercontent.com/muicss/sentineljs/master/dist/sentinel.js)
* [sentinel.min.js](https://raw.githubusercontent.com/muicss/sentineljs/master/dist/sentinel.min.js)
You can also use it as a CJS or AMD module:
```bash
$ npm install --save sentinel-js
```
```javascript
var sentinel = require('sentinel-js');
sentinel.on('custom-element', function(el) {
// A new has been detected
el.innerHTML = 'The sentinel is always watching.';
});
```
SentinelJS is 668 bytes (minified + gzipped).
## Quickstart
```html
// 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);
};
Add another DIV
```
[View Demo »](https://jsfiddle.net/muicss/rbqLbjzf/)
## 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 "!"):
@keyframes slidein {
from: {margin-left: 100%}
to: {margin-left: 0%;}
}
.my-div {
animation-duration: 3s;
animation-name: slide-in, node-inserted;
}
// trigger on "node-inserted" animation event name (using "!")
sentinel.on('!node-inserted', function(el) {
el.insertHTML = 'The sentinel is always watching.';
});
```
#### 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:
```html
// 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.';
});
});
```
### Custom Stylesheet Placement
By default, SentinelJS will insert a new `` tag into the beginning of the `<head>` of the document. If you want to control the location of SentinelJS's CSS you can define your own hardcoded style tag with `id="sentinel-css"` instead:
```html
<!doctype html>
<html>
<head>
<style id="sentinel-css">
// 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);
};
Add another DIV