Introduction

During the course of writing *-Roids, I quickly became desirous of an easier way to dynamically create elements in my SVG documents. I found myself typing the same lines of code over and over again and decided that a JavaScript object could be used in place of this code.

The object creation may seem a little strange to you unless you come from a Perl background. Perl and JavaScript have the ability to associate words with values. These are usually referred to as associative arrays or hashes. These hashes make for a convenient way to refer to SVG element attributes.

The attributes parameter in the constructor method uses an anonymous objects to pass multiple named properties. The only catch is that you will need to place single-quotes around property names that contain hyphens.

Reference

Object Variables

Node_Builder.VERSION

This is a number which represents the current version number for this implementation of the Node_Builder object. This can be used by scripts to check that the correct version of the object is being used.

Methods

constructor - new Node_Builder(type, attributes, text);

This method is used to create a new Node_Builder object. The parameters passed to the constructor method define the element type, the element's attributes and the element's style properties.

type is a string which is the type of element that you are creating. For instance, if I need to create a <rect> element, then my type would be "rect".

attributes is an object whose property names are equivalent to the attribute names you use when creating an element. For example, if your rectangle is defined as follows:

<rect x="5" y="5" />

then you will need to create an anonymous object with an x property equal to 5 and a y property equal to 5. The following line creates an anonymous object with these properties defined.

{ x:5, y:5 }

Please note that hypenated properties will need to be surrounded by single-quote. For example, the following anonymous object sets the stroke-width attribute:

{ x:5, y:5, 'stroke-width': 5 }

text is an optional string parameter. If this parameter exists when calling the Node_Builder constructor, then a new text element will be created using the text parameter as it's contents.

appendTo(parent);

This method creates a new node using the values in object's type, attributes, and styles properties. After the node has been created, it is appended to the node which is passed in the parent parameter.

parent is the node in the DOM to which you would like to append the node that is created by this object.

remove();

This method removes the node the object represents. All properties are reinitialized.

Properties

type is a string which is the type of the element that this object represents.

attributes is an object whose property names and values match the attributes that were used to create the node this object represents.

text is a string which, if defined, is the contents of a text node element. This parameter is used when creating text-based elements.

node is a reference to the node that was created by this object. This is provided as a convenience to the programmer. This property is used when the node is deleted from the DOM.

parent is a reference to the node which contains the node created by this object. This is provided as a convenience to the programmer. This property is used when the node needs to be deleted from the DOM.

data is a reference to the node which contains the text of this object. This is provided as a convenience to the programmer. This property is used to change the text contents of the object.

Use

Loading Node_Builder into your SVG document

In order to use the Node_Builder object in your SVG file, you will need to insert a <script> element inside of your <svg> element. As an example, if Node_Builder.js is in the same directory as your SVG document, then you would include the Node_Builder object with the following text:

<script xlink:href="Node_Builder.js" />

Creating an Element

In order to dynamically create a new element in your SVG document, you will need to create a new Node_Builder object. The following example creates a new circle at (10,10) with a radius of 3 and then adds it to the DOM to be displayed.

The first parameter is the same name that you would use to create the element using SVG only. In this example we are creating a "circle" element. The second parameter is an anonymous object whose properties are the same names that you would use when you declare an SVG element. The third parameter is an anonymous object whose properties are the same names that you would use in the style attribute when you declare an SVG element. The above example is equivalent to:

<circle cx="10" cy="10" style="fill: blue" />

The final statement in the example adds the node created by the Node_Builder object to the DOM. The parameter, SVGDoc in this example, is the parent to which the new node needs to be appended. Typically, the parent node is found using the SVG's document's getElementByID() method.

Creating a Hierarchy

Creating a hierarchy of elements is only slightly more complicated. The following example recreates this SVG tree:

Now that we have all of the individual elements, now it's time to build the tree. Every Node_Builder object has a node parameter which is a reference to the node the object creates; however, this property is not defined until we call append(parent) on the object. In order to add the <rect> and <circle> elements to the <g>, we need to know <g>'s node, but that doesn't exist yet. To remedy this, we add the <g> element to the SVG document, and then add the <rect> and <circle> to the <g> element. That completes the hierarchy.

Other Examples

Download

History

Version 1.3

Added (hackish) support for the xlink namespace. If the attribute begins with "xlink:", then the attribute will be set via setAttribute(xlinkNS, attribute-name, attribute-value). A better implementation would allow the user to specify the namespace.

Version 1.2

I have removed all uses of the getStyle() method call to (hopefully) make Node_Builder more viewer-independent

Removed styles parameter from constructor

Removed styles attribute from Node_Builder object

Removed style attribute from Node_Builder object

Removed logic to convert underscores in an attribute to hyphens. Simply quoting hyphenated attributes removes the necessity of this code.

Version 1.1

Added VERSION property

Changed append() to appendTo() to avoid possible confusion with the appendChild() DOM method

Added remove() method

Added support for optional data parameter in constructor to support text-based elements.