├── .gitignore
├── LICENSE
├── README.md
├── example
└── index.html
├── package.json
└── src
├── jquery.onmutate.js
└── jquery.onmutate.min.js
/.gitignore:
--------------------------------------------------------------------------------
1 | .jshintrc
--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
1 | The MIT License (MIT)
2 |
3 | Copyright (c) 2014 eclecto
4 |
5 | Permission is hereby granted, free of charge, to any person obtaining a copy
6 | of this software and associated documentation files (the "Software"), to deal
7 | in the Software without restriction, including without limitation the rights
8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9 | copies of the Software, and to permit persons to whom the Software is
10 | furnished to do so, subject to the following conditions:
11 |
12 | The above copyright notice and this permission notice shall be included in all
13 | copies or substantial portions of the Software.
14 |
15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21 | SOFTWARE.
22 |
23 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | jQuery-onMutate
2 | ===============
3 |
4 | This plugin is a wrapper for the MutationObserver class, with a fallback to setInterval, so you can execute code when elements matching a given selector are created or have their attributes or text changed. It includes three methods: .onCreate(), .onModify(), .onText(), and .onMutate().
5 |
6 | This plugin is dependent on jQuery (tested on version 1.6.4)
7 |
8 | Installation
9 | ------------
10 |
11 | ```
12 | npm install --save jquery-onmutate
13 | ```
14 |
15 | Usage
16 | -----
17 |
18 | ```
19 | var onMutate = require('jquery-onmutate');
20 | var jQuery = require('jquery');
21 |
22 | onMutate(jQuery);
23 | ```
24 |
25 | API
26 | ===
27 |
28 | .onCreate()
29 | -----------
30 |
31 | Attaches a listener to an existing parent element, and executes a callback when a new descendent element matching a given selector is created. If a matching element already exists, the callback will execute immediately.
32 |
33 | `parent.onCreate(selector, callback[, multi = false]);`
34 |
35 | **parent** (jQuery) a single parent element that is a known ancestor of the created element(s). Only the first element in the set will be used.
36 |
37 | **selector** (string) is a valid jQuery selector for the new element(s). OnMutate will poll for a valid new element using `jQuery(selector, parent)`
38 |
39 | **callback** (function) the callback executed when a new matching element is created. It receives one argument, **elements**, which is a jQuery object containing the new elements.
40 |
41 | **multi** (boolean) determines whether the observer will continue to poll for new elements after a match is found. If false, the observer will shut itself off after the first match(es); this includes if matching elements already exist when onCreate is called. Otherwise, it will continue to poll, but will only operate on each created element once.
42 |
43 | `$.onCreate()` will attach the onCreate listener to the document, i.e. is the same as `$(document).onCreate()`.
44 |
45 | `parent.onCreate('detach');`
46 |
47 | This usage shuts off the onCreate listener.
48 |
49 | .onModify()
50 | -----------
51 |
52 | Attaches a listener to a single element, and executes a callback whenever one of its attributes is changed with optional conditions. While the callback executes the listener will be momentarily shut off, to prevent infinite loops if the callback also changes the element's attributes.
53 |
54 | `element.onModify([attributes[, match,]] callback[, multi = false]);`
55 |
56 | **element** (jQuery) the element to be observed.
57 |
58 | **attributes** (string) is a space-separated list of attributes to watch. If omitted, the callback will execute on any attribute change.
59 |
60 | **match** (string|RegExp) is a string or RegExp that will be matched against the new value of any modified attribute(s). If you set a match then you must also specify the **attributes** to watch.
61 |
62 | **callback** (function) is the function to execute when a qualifying change is made to the element's attributes. It receives one argument, **element**, which is a jQuery object containing the affected element.
63 |
64 | **multi** (boolean) determines whether the observer will continue to poll for changes after the callback executes. If false, the observer will shut itself off after the first qualifying change; otherwise, it will continue to poll.
65 |
66 | `element.onModify('detach');`
67 |
68 | This usage shuts off the onModify listener.
69 |
70 | .onText()
71 | ---------
72 |
73 | Attaches a listener to a single element, and executes a callback whenever its text content changes with optional conditions. While the callback executes the listener will be momentarily shut off, to prevent infinite loops if the callback also changes the element's text.
74 |
75 | `element.onText([match,] callback[, multi = false])`
76 |
77 | **element** (jQuery) is the element to be observed.
78 |
79 | **match** (string|RegExp) is an optional string or RegExp that will be matched against element's new text content, as read with jQuery's `.text()` method.
80 |
81 | **callback** (function) is the function to execute when a qualifying change is made to the element's text content. It receives one argument, `element`, which is a jQuery object containing the affected element.
82 |
83 | **multi** (boolean) determines whether the observer will continue to poll changes after the callback executes. If false, the observer will shut itself off after the first qualifying change; otherwise, it will continue to poll.
84 |
85 | `element.onText('detach');`
86 |
87 | This usage shuts off the onText listener.
88 |
89 | .onMutate()
90 | -----------
91 |
92 | An alternative way to call one of the methods above, passing the type of mutation as an argument.
93 |
94 | `element.onMutate(type, ...)`
95 |
96 | **element** (jQuery) is the element to be observed.
97 |
98 | **type** (string) should be "create", "modify", or "text".
99 |
100 | Additional arguments are specific to the method being invoked.
101 |
102 | Additional Notes:
103 | -----------------
104 | - .onCreate() internally creates a MutationObserver that observes with the `childList` and `subtree` options.
105 | - .onModify() internally creates a MutationObserver that observes with the `attributes` option.
106 | - .onText() internally creates a MutationObserver that observes with the `characterData`, `childList`, and `subtree` options. This is so it can recognize text node insertion and deletion as a text change, as well as observing characterData changes to existing text nodes.
107 | - For browsers that do not support MutationObserver, this plugin will check all observed elements at 50ms intervals for changes that match the conditions. Because of this, there can be a slight delay/flash before the callback executes for these browsers.
--------------------------------------------------------------------------------
/example/index.html:
--------------------------------------------------------------------------------
1 |
2 |
3 |