jquery-mutation-summary javascript library

Donate $5 now Donate $25 now Donate $100 now More options

⚠️ This project has been archived

No future updates are planned. Feel free to continue using it, but expect no support.

A jQuery wrapper/plugin for mutation-summary, the DOM mutation-observers wrapper. It adds easy, chainable .mutationSummary() calls to your jQuery objects.

Mutation Summary is a JavaScript library that makes observing changes to the DOM fast, easy and safe.

The Mutation Summary library aggregates multiple DOM mutations to a neat changeset, optionally filtered by CSS-style selectors. Have a look at this fun and informative 8 minute screen cast by Rafael Z Weinstein, the creator of mutation-summary.

• Project page
• Source on Github

Get it

• jquery.mutation-summary.js

Demos

• example/shuffle.html: A copy of the original shuffle.html example, but with this library as the default option. Shuffle.html is explained in the mutation-summary screen cast.
• example/demo.html: Listening to simple mutations in a list.

Usage

See mutation-summary API reference for details on callback(summary[]), queries and other options.

Public methods

// Connect mutation observation
$(selector).mutationSummary("connect", options);
$(selector).mutationSummary("connect", callback(summary[]) [, observeOwnChanges], queries);

// Diconnect all mutation observation
$(selector).mutationSummary("disconnect");

// To disconnect a previous "connect" call only, pass the same parameters
$(selector).mutationSummary("disconnect", options);
$(selector).mutationSummary("disconnect", callback(summary[]) [, observeOwnChanges], queries);

Example

// Use document to listen to all events on the page (you might want to be more specific)
var $observerSummaryRoot = $(document);

// Simplest callback, just logging to the console
function callback(summaries){
	console.log(summaries);
}

// Connect mutation-summary
$observerSummaryRoot.mutationSummary("connect", callback, [{ all: true }]);

// Do something to trigger mutationSummary
$("<a />", { href: "https://joelpurra.com/projects/jquery-mutation-summary/"}).text("Go to the jquery-mutation-summary website").appendTo("body");

// Disconnect when done listening
$observerSummaryRoot.mutationSummary("disconnect");

Original purpose

Developed to get a jQuery chainable version of the mutation-summary library.

DOM Mutation Observers are useful for watching changes made to the DOM elements (including their attributes and contents) that are out of your control. These external changes may come from other jQuery plugins, non-jQuery scripts, legacy code or even flash objects that modifies the page around it. If you have previously used DOM Mutation Events, please note that they have been deprecated.

Dependencies

jquery-mutation-summary’s runtime dependencies are

• mutation-summary
• jQuery

Browser compatibility

Should be as compatible as mutation-summary is - see the wiki page on browser support for Mutation Observers as well as caniuse.com/mutationobserver. jQuery is assumed to be available in these environments.

TODO

Patches/pull requests welcome!

• Write tests.
• Write example callback filters that act only on, for example, removed attributes or added elements.
• Add support for namespaced/filtered events, for example mutationSummary.element.added or mutationSummary.attribute.valueChanged.

jquery-mutation-summary copyright (c) 2012, 2013, 2014, 2015, 2016, 2017, Joel Purra. All rights reserved. When using jquery-mutation-summary, comply to at least one of the three available licenses: BSD, MIT, GPL. Your donations are appreciated!