.build()

Create new elements and content for inserting into the document.

Syntax

neon.build(specification)

specification

Describes the elements or nodes to create. This may be a string, Object, Array or DOM node. The syntax is described below.

Return value

This method is chainable.

This method returns a Neon object containing all of the newly created elements, replacing the previous selection. In case the created elements included multiple levels of heirarchy, the returned object will contain the top level elements, and their children can be accessed by accessing their respective childNodes attributes.

Description

This method allows you to create new DOM elements and other nodes for insertion into the document, using a convenient syntax. This method can create a single node, or multiple nodes at once in a heirarchical configuration.

specification syntax

The supplied specification will be used as a guide for creating the DOM nodes.

specification may be one of:

• string

  A string represents a single DOM text node, whose contents shall be the the contents of the string.

  Example:

  textnode = neon.build("Text content");

• Object

  An object represents a single DOM element node.

  The object must have one property whose name is the name of the element, and whose contents represent the element's contents. This may be a string, Object or Array specification. This allows nodes to be nested inside other nodes. For an empty element, this may be null or the empty string ("").

  Examples:

  // Single list item
  listitem = neon.build({li: "List item"});
  
  // Unordered list with a list item nested inside
  mylist = neon.build({ul: {li: "List item"}});
  
  // Empty hr element
  ruler = neon.build({hr: null});
  

  An object may also contain one or more attributes. These are represented as properties whose name begins with an added dollar sign, and whose value is a string representing the attribute value.

  Examples:

  // Link
  mylink = neon.build({a: "Link text", $href: "http://example.com"});
  
  // Image
  myimage = neon.build({img: null, $src: "image.gif", $alt: "Alt text"});
  

  The order of properties inside the object is not important, as long as there is one and only one property without a dollar sign, which will be used as the element name.

• Array

  The specification may be an Array containing zero or more other strings, Objects and Arrays representing multiple sibling nodes.

  Examples:

  // Multiple list items at top level
  listitems = neon.build([{li: "Item 1"}, {li: "Item 2"}]);
  
  // Multiple cells in a table row
  tablerow = neon.build({tr: [{td: "Cell 1"}, {td: "Cell 2"}]});

The specification syntax is compatible with JSON, so it can be generated and transmitted by many server-side languages if necessary. It is expressive, taking up fewer bytes than the equivalent HTML would.

Instead of a specification conforming to the above JSON-compatible syntax, it is also possible to specify one or more already-created DOM nodes. This is more useful when using .append() or .insert(), as with those methods it provides a convenient way to move existing nodes around in the document.

Examples

The following simple example returns a single list item containing a text node:

listitem = neon.build({li: "List item text"});

The following complex example shows many nodes being created at once.

menuspec = {ul: [
    {li: {a: "Yahoo", $href: "http://yahoo.com"}},
    {li: {a: "Google", $href: "http://google.com"}}
    ], $class: "menu"};
menu = neon.build(menuspec);

Follow @neonjs