README

DomEdit

A declarative DOM editor.

Example

Inputs
_helloworld.html: <div id="hello" />	_helloworld.mods: { "#hello": { "content" : "Hello World!", "discard-attr" : "id", "@class" : "greeting" } }
Output
<div class="greeting">Hello World!</div>

Install

npm install domedit

Run

CLI

domedit -f mods-file html-file

Gulp

var domedit = require('domedit');

// For each html file html/**/x.html,
// apply file mods/**/x.mods, creating file dist/**/x.html.
gulp.task('domedit', function() {
  return gulp.src(['html/**/*.html')
    .pipe(domedit({modsdir: 'mods'}))
    .pipe(gulp.dest('./dist'));
});

The argument to the domedit function may be any of the following:

{modsfile: "filename"}: A string containing the name of the mods file.
{modsfile: function()}: A function that takes a file name and returns a mods file name. The function is passed two arguments: the file basename (e.g. x), and the file full name (e.g. blah/blah/blah/x.html).
{modsfile: {basename:modname, ...}}: An object with file basenames as properties and mods file names as property values.
{modsdir: "dirname"}: A string containing the name of the mods file base directory. Mods files are selected by matching their relative path with the relative path of the HTML file and by matching their basename with the basename of the HTML file. Mods files must have the suffix '.mods'.

Program API

var domedit = require('domedit');
var editedHtml = domedit(html, mods{, log});
    // html may be a filename or a string, and may be complete or partial HTML
    // mods is a mods object
    // log defaults to console.warn

Mods file syntax

The DomEdit mods file is a JSON file containing a single object. Each property of the object is a CSS selector that may match one or more elements within the HTML file. Each selector property value is an object containing a set of changes to apply to each matched element. Each change consists of a directive and a value.

Mods file directives

Directive	Value
@name	Text to be used as the value of the name attribute. If the attribute does not exist, it will be added.
@@name	This directive allows attributes with the same name as other DomEdit directives to be added to an element.
after	Text or HTML to insert immediately after the element's end tag.
after-content	Text or HTML to insert immediately before the element's end tag.
before	Text or HTML to insert immediately before the element's start tag.
before-content	Text or HTML to insert immediately after the element's start tag.
content	Text or HTML to replace the content of the element.
discard	One of the following: `element`: The element and its content will be removed from the output. `tag`: The element's start and end tags will be removed from the output. `content`: The element's content will be removed from the output.
discard-attr(s)	A space- or comma-separated list of attributes to be removed from the output.
wrap	HTML to be inserted between the element and its parent. This HTML becomes a child of the parent, and the selected element becomes a child of the right-most last child of the inserted HTML.
wrap-content	HTML to be inserted between the element and its content. This HTML becomes a child of the element, and the element's content becomes a child of the rightt-most last child of the inserted HTML.

Notes

HTML elements used within a directive must be complete (with both start and end tags).
Selectors and directives have no sequence. Do not depend on sequence of operations.
All discards (including discard-attr(s)) are deferred until after all other edits are run, so that discards do not break selectors.

TODO

Support text replacement (s/x/y/{g}) for attribute values and content.
Support DOM range selection for a subset of directives.
Support array type as top level of JSON file for sequenced operations.

Usage no npm install needed!