Skip to content

Latest commit

 

History

History
117 lines (75 loc) · 4.64 KB

README.md

File metadata and controls

117 lines (75 loc) · 4.64 KB
Raw

Nilbog

npm npm npm bundle size (minified + gzip)

MutationObserver shortcuts to prevent certain actions on nodes.

Nilbog will reverse certain actions taken on nodes, preserving an original state. Currently, Nilbog can prevent creation and deletion, as well as protect the text, attributes, and classes of nodes.

Table of contents

Install

With npm installed, run

$ npm install nilbog

Or, with Yarn,

$ yarn add nilbog

Alternatively, download nilbog.min.js

Usage

const nilbog = new Nilbog()

nilbog.preventCreate('.prevent-create')
nilbog.preventDelete('.prevent-delete')
nilbog.protectText('.protect-text')
nilbog.protectAttributes('.protect-attributes')
nilbog.protectClasses('#protect-classes')
nilbog.freeze('#freeze')

View the test folder for working examples.

Adding to page

Import directly into your JavaScript (for use with tools like Webpack, Browserify, and Parcel):

import Nilbog from 'nilbog'

const nilbog = new Nilbog()

Download and use nilbog.min.js

<script type="text/javascript" src="js/nilbog.min.js"></script>
<script type="text/javascript">
  var nilbog = new Nilbog()
</script>

CDNs

jsDelivr
<script type="text/javascript" src="https://cdn.jsdelivr.net/npm/[email protected]/browser/nilbog.min.js"></script>
unpkg
<script type="text/javascript" src="https://unpkg.com/[email protected]/browser/nilbog.min.js"></script>

Script placement

Browsers will load and execute JavaScript as it encounters it as it processes the HTML file unless the script tags have the async or defer attributes (see "Understanding the Critical Rendering Path" by Ire Aderinokun for more information). If Nilbog observers that watch for element creation are instantiated before the rest of document has been fully rendered, they will be fired as subsequent matching elements are rendered. This will generate the following side effects:

  • preventCreate will not allow any subsequent matching nodes from rendering, even if they were originally on the page. This may actually be to your advantage if you'd like to employ this sort of behavior.
  • protectText will prevent protected elements from having any inner text, due to the element originally having no text as it renders its full tree.

To prevent this, place your scripts before the end of the body element or use the defer attribute to tell the browser to execute the script once the page has been fully rendered.

Browser compatibility

Nilbog is based entirely on the MutationObserver native class (including the prefixed WebkitMutationObserver). If this class is not present, Nilbog will not work at all.

Nilbog is written in ES6 which is transpiled using Babel. It does not include polyfills for some ES6 features that are not handled by Babel, such as Array.from, Array.prototype.filter, etc. because this could add unnecessary bloat and logic in case these features are already polyfilled. This affects only unsupported browsers such as IE <= 11. If you intend to support such browsers, I suggest using polyfill.io or core-js.

API

See the Wiki for the complete API.

Name

“Nilbog... it's Goblin spelled backwards!”

On top of being the name of the town in the amazing Troll 2, a nilbog is a creature found in tabletop roleplaying games such as Dungeons & Dragons and Pathfinder. The nilbogs have an ability called "Reveral of Fortune" that causes those around it to act opposite of their own desires, much like this module!

See also

License

MIT © James Anthony Bruno