Minimal Custom Elements

Factory for creating minimal custom elements.

Installation

$ npm install minimal-custom-element --save

Usage

var createCustomElement = require( 'minimal-custom-element' );

To create a new custom element,

var element = createCustomElement( 'my-element-name' );

where my-element-name is the custom element name. A name must start with a-z, contain a hyphen -, and be alphanumeric. For additional naming rules, see validate-element-name and its associated source code.

The element instance has the following methods...

element.attr( [name, [value]] )

This method is a setter/getter. If no arguments are provided, returns an object containing all attribute-value pairs. If only a name is provided, returns the corresponding attribute value. If the attribute does not exist, returns undefined. If a name and value are provided, sets the attribute value.

// Set an attribute value:
element.attr( 'class', 'beep' );
element.attr( 'id', 'boop' );

// Get the `class` attribute's value:
element.attr( 'class' );
// Returns 'beep'

// Get all attribute value pairs:
element.attr();
// Returns {'class':'beep','id':'boop'}

Note: to set an attribute value, the value must be either a string, boolean, or number.

element.selfClosing( [bool] )

This method is a setter/getter. If no boolean is provided, returns a boolean indicating if an element is a self-closing element. If a boolean is provided, sets whether an element should be considered a self-closing element. To set the self-closing status,

element.selfClosing( true );

By default, custom elements are assumed to not be self-closing; i.e., they have end-tags.

element.append( element )

Appends another element (Element or Text instance) to an element. If the element is a self-closing element, this method will throw an Error.

var el = createCustomElement( 'xfig-chart' );

element.append( el );

When an element is serialized, nested elements are serialized in the order in which they were appended.

element.toString()

Serializes an element as a string.

element.toString();
// Returns '<tag>...</tag>'

Examples

// Create a new custom parent container...

var container = createCustomElement( 'my-container' );
container.attr( 'class', 'container' );

// Build other components...

var fig = createCustomElement( 'my-figure' );
fig.attr( 'class', 'figure' );

var chart = createCustomElement( 'my-chart' );
chart.attr( 'class', 'chart' );

// Create the document structure...

container.append( fig );
fig.append( chart );

// Serialize to string...

console.log( container.toString() );
// Returns: '<my-container class="container"><my-figure class="figure"><my-chart class="chart"></my-chart></my-figure></my-container>'

To run the example code from the top-level application directory,

$ node ./examples/index.js

Tests

Unit

Unit tests use the Mocha test framework with Chai assertions. To run the tests, execute the following command in the top-level application directory:

$ make test

All new feature development should have corresponding unit tests to validate correct functionality.

Test Coverage

This repository uses Istanbul as its code coverage tool. To generate a test coverage report, execute the following command in the top-level application directory:

$ make test-cov

Istanbul creates a ./reports/coverage directory. To access an HTML version of the report,

$ open reports/coverage/lcov-report/index.html

License

MIT license.

Copyright

Copyright © 2014. Athan Reines.