minimal-svg-element v0.0.3

Minimal SVG Elements

Factory for creating minimal SVG elements.

Installation

$ npm install minimal-svg-element --save

Usage

var createSVGElement = require( 'minimal-svg-element' );

To create a new SVG element,

var element = createSVGElement( '{{name}}' );

where {{name}} is a valid SVG element name.

var element = createSVGElement( 'svg' );

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()

Returns a boolean indicating if an element is a self-closing element.

element.selfClosing();

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 = createSVGElement( 'g' );

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 svg canvas...

var canvas = createSVGElement( 'svg' );
canvas
	.attr( 'class', 'canvas' )
	.attr( 'width', 500 )
	.attr( 'height', 500 );

// Build layers...

var graph = createSVGElement( 'g' );
graph.attr( 'class', 'graph' );

var datum = createSVGElement( 'circle' );
datum
	.attr( 'class', 'datum' )
	.attr( 'cx', 100 )
	.attr( 'cy', 100 )
	.attr( 'r', 5 );

// Assemble the layers...

canvas.append( graph );
graph.append( datum );

// Serialize to string...

console.log( canvas.toString() );
// Returns: '<svg class="canvas" width="500" height="500"><g class="graph"><circle class="datum" cx="100" cy="100" r="5"></circle></g></svg>'

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

$ node ./examples/index.js

Notes

When creating SVG elements, you are encouraged to set the parent svg element namespace. Doing so enables user-agents to determine the XML tag dialect and properly render SVG elements.

var canvas = createSVGElement( 'svg' );

canvas
	.attr( 'xmlns', 'http://www.w3.org/2000/svg' )
	.attr( 'xmlns:xlink', 'http://www.w3.org/1999/xlink' )
	.attr( 'xmlns:ev', 'http://www.w3.org/2001/xml-events' );

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.