Skip to content

Nilbog class

Jump to bottom
James Anthony Bruno edited this page Apr 25, 2018 · 6 revisions

Nilbog class

A Nilbog instance assigns observers to prevent certain mutating actions on DOM elements.

Table of contents

Safe mode

For a more detailed explanation, see Conflict Management.

Safe mode keeps a record of every observer assigned by an instance of Nilbog. This prevents conflicts if there are multiple observers trying to operate on the same mutated element.

Pros

  • No infinite feedback loops between multiple observers

Cons

  • Foreign scripts could potentially find the list of observers and disconnect all of them.
  • Will only track within the instance. So if another instance of Nilbog is created, there's still the potential for a feedback loop.

Methods

new Nilbog(safe) 

const nilbog = new Nilbog()
const nilbog = new Nilbog(false)  // safe mode: off

Arguments

  • safe (optional, default: true) - Prevents conflicts between multiple Nilbog observers.

nilbog.preventCreate(selector, options = {})

Prevents creation of elements matching selector.

Arguments

  • selector (required) - Elements matching this will not be allowed to be created.

Options

  • parent (optional, default: document.documentElement) - Element to watch on. If this element is destroyed, observation will cease.

Returns

nilbog.preventDelete(selector, options = {})

Prevents deletion of elements matching selector.

Arguments

  • selector (required) - Elements matching this will not be allowed to be deleted.

Options

  • parent (optional, default: document.documentElement) - Element to watch on. If this element is destroyed, observation will cease.
  • onTreeDeletion (optional, default: false) - If a parent of a matched element is deleted, what should Nilbog do?
    • false - Do nothing. It's gone forever.
    • "recreate-full-tree" - Recreate the entire tree of the deleted parent element.
    • "recreate-direct-path" - Recreate the path(s) leading to the matched element(s), removing unnecessary relatives.
    • "place-at-top-level" - Place matched elements where the deleted parent element was.

Returns

nilbog.protectText(selector, options = {})

Prevents modification of inner text of elements matching selector.

Arguments

  • selector (required) - Elements matching this will not be allowed to have their inner text modified.

Options

  • parent (optional, default: document.documentElement) - Element to watch on. If this element is destroyed, observation will cease.

Returns

nilbog.protectAttributes(selector, options = {})

Prevents actions on attributes of elements matching selector.

Arguments

  • selector (required) - Elements matching this will have their attributes protected.

Options

  • parent (optional, default: document.documentElement) - Element to watch on. If this element is destroyed, observation will cease.
  • rules (optional, default: { allow: false, prevent: true }) - Prevent/allow creation, deletion, and/or modification of specific or all attributes.

Returns

⚠️ Notice

This will refuse to act on changes to the class attribute. Use protectClasses instead.

nilbog.protectClasses(selector, options = {})

Prevents actions on classes of elements matching selector.

Arguments

  • selector (required) - Elements matching this will not be allowed to have their classes protected.

Options

  • parent (optional, default: document.documentElement) - Element to watch on. If this element is destroyed, observation will cease.
  • rules (optional, default: { allow: false, prevent: true }) - Prevent/allow creation or deletion of specific or all classes.

Returns

nilbog.freeze(selector, options = {})

Prevents deletion and protects text, classes, and attributes of element.

Arguments

  • selector (required) - Elements matching this will not be allowed to be mutated.

Options

  • parent (optional, default: document.documentElement) - Element to watch on. If this element is destroyed, observation will cease.

Returns

  • Object:
    • preventDelete: Observer
    • protectText: Observer
    • protectClasses: Observer
    • protectAttributes: Observer

Properties

  • safe (type boolean) - Is safe mode on?
  • conflictManager (type ConflictManager) - Resolves conflicts when safe mode is on.

Selectors

Nilbog uses jQuery-like selectors. It can either be a CSS-style selector (div#id.class), an HTML element (document.getElementById('id')), or a list of elements and/or selectors.

Rulesets

The protectClasses and protectAttributes observers share a ruleset based configuration. Both offer discrimination based on creation and deletion. protectAttributes additionally offers modification. By default, everything is prevented with no allowances. Check out the examples section below to see how ruleset configuration works.

Examples

// Default ruleset when `rules` is undefined
nilbog.protectAttributes(selector, {
  rules: {
    allow: false,  // No allowances
    prevent: true  // Prevent everything
  }
})

// Above is equivalent to:
nilbog.protectAttributes(selector, {
  rules: {
    allow: {
      create: false,  // Don't allow creation
      delete: false,  // Don't allow deletion
      modify: false  // Don't allow modification
    },
    prevent: {
      create: true,  // Prevent all creation
      delete: true,  // Prevent all deletion
      modify: true  // Prevent all modification
  }
})

// Exception-based rules
nilbog.protectAttributes(selector, {
  rules: {
    allow: {
      create: false,  // Don't allow creation
      delete: false,  // Don't allow deletion
      modify: ['attr-1', 'attr-2']  // Allow modification of these attributes
    },
    prevent: true  // Prevent everything
})
nilbog.protectAttributes(selector, {
  rules: {
    allow: {
      create: true,  // Allow creation
      delete: true,  // Allow deletion
      modify: ['attr-1', 'attr-2']  // Allow modification of only these attributes
    },
    prevent: {
      create: ['attr-3'],  // Prevent creation of only this attribute
      delete: false,  // Don't prevent deletion
      modify: true  // Prevent modification
    }
  }
})
Clone this wiki locally