Converse converse.js

API Documentation

Class: Builder

Builder(name, attrsopt)

This class provides an interface similar to JQuery but for building DOM elements easily and rapidly. All the functions except for toString() and tree() return the object, so calls can be chained.

The corresponding DOM manipulations to get a similar fragment would be a lot more tedious and probably involve several helper variables.

Since adding children makes new operations operate on the child, up() is provided to traverse up the tree. To add two children, do

builder.c('child1', ...).up().c('child2', ...)

The next operation on the Builder will be relative to the second child.

Constructor

new Builder(name, attrsopt)

The attributes should be passed in object notation.

Parameters:
Name Type Attributes Description
name string

The name of the root element.
attrs StanzaAttrs <optional>

The attributes for the root element in object notation.
Source:
Example
// Here's an example using the $iq() builder helper.
 $iq({to: 'you', from: 'me', type: 'get', id: '1'})
     .c('query', {xmlns: 'strophe:example'})
     .c('example')
     .toString()

 // The above generates this XML fragment
 //  <iq to='you' from='me' type='get' id='1'>
 //    <query xmlns='strophe:example'>
 //      <example/>
 //    </query>
 //  </iq>

Methods

attrs(moreattrs) → {Builder}

Add or modify attributes of the current element.

The attributes should be passed in object notation. This function does not move the current element pointer.

Parameters:
Name Type Description
moreattrs Object.<string, (string|number|null)>

The attributes to add/modify in object notation. If an attribute is set to null or undefined, it will be removed.
Source:
Returns:

The Strophe.Builder object.

Type
Builder

c(name, attrsopt, textopt) → {Builder}

Add a child to the current element and make it the new current element.

This function moves the current element pointer to the child, unless text is provided. If you need to add another child, it is necessary to use up() to go back to the parent in the tree.

Parameters:
Name Type Attributes Description
name string

The name of the child.
attrs Object.<string, string> | string <optional>

The attributes of the child in object notation.
text string <optional>

The text to add to the child.
Source:
Returns:

The Strophe.Builder object.

Type
Builder

cnode(elem) → {Builder}

Add a child to the current element and make it the new current element.

This function is the same as c() except that instead of using a name and an attributes object to create the child it uses an existing DOM element object.

Parameters:
Name Type Description
elem Element

A DOM element.
Source:
Returns:

The Strophe.Builder object.

Type
Builder

h(html) → {Builder}

Replace current element contents with the HTML passed in.

This does not make the child the new current element

Parameters:
Name Type Description
html string

The html to insert as contents of current element.
Source:
Returns:

The Strophe.Builder object.

Type
Builder

root() → {Builder}

Make the root element the new current element.

When at a deeply nested element in the tree, this function can be used to jump back to the root of the tree, instead of having to repeatedly call up().

Source:
Returns:

The Strophe.Builder object.

Type
Builder

t(text) → {Builder}

Add a child text element.

This does not make the child the new current element since there are no children of text elements.

Parameters:
Name Type Description
text string

The text data to append to the current element.
Source:
Returns:

The Strophe.Builder object.

Type
Builder

toString() → {string}

Serialize the DOM tree to a String.

This function returns a string serialization of the current DOM tree. It is often used internally to pass data to a Strophe.Request object.

Source:
Returns:

The serialized DOM tree in a String.

Type
string

tree() → {Element}

Return the DOM tree.

This function returns the current DOM tree as an element object. This is suitable for passing to functions like Strophe.Connection.send().

Source:
Returns:

The DOM tree as a element object.

Type
Element

up() → {Builder}

Make the current parent element the new current element. This function is often used after c() to traverse back up the tree.

Source:
Returns:

The Strophe.Builder object.

Type
Builder
Example
// For example, to add two children to the same element
 builder.c('child1', {}).up().c('child2', {});