Class Element

Element

A representation of an XML Element node.

// Adds up the values listed in a sample XML document and adds a new element with the total.
var xml = '<things>'
    + '<plates>12</plates>'
    + '<bowls>18</bowls>'
    + '<cups>25</cups>'
    + '</things>';
var document = XmlService.parse(xml);
var root = document.getRootElement();
var items = root.getChildren();
var total = 0;
for (var i = 0; i < items.length; i++) {
  total += Number(items[i].getText());
}
var totalElement = XmlService.createElement('total').setText(total);
root.addContent(totalElement);
xml = XmlService.getPrettyFormat().format(document);
Logger.log(xml);

Methods

Method Return type Brief description
Element Appends the given node as the last child of the Element node.
Element Inserts the given node at the given index among all nodes that are immediate children of the Element node.
Content[] Creates unattached copies of all nodes that are immediate children of the {@code Element} node.
Content Detaches the node from its parent Element node.
Content[] Gets all nodes that are immediate children of the {@code Element} node.
Attribute Gets the attribute for this Element node with the given name and no namespace.
Attribute Gets the attribute for this Element node with the given name and namespace.
Attribute[] Gets all attributes for this Element node, in the order they appear in the document.
Element Gets the first Element node with the given name and no namespace that is an immediate child of this Element node.
Element Gets the first Element node with the given name and namespace that is an immediate child of this Element node.
String Gets the text value of the node with the given name and no namespace, if the node is an immediate child of the Element node.
String Gets the text value of the node with the given name and namespace, if the node is an immediate child of the Element node.
Element[] Gets all Element nodes that are immediate children of this Element node, in the order they appear in the document.
Element[] Gets all Element nodes with the given name and no namespace that are immediate children of this Element node, in the order they appear in the document.
Element[] Gets all Element nodes with the given name and namespace that are immediate children of this Element node, in the order they appear in the document.
Content Gets the node at the given index among all nodes that are immediate children of the {@code Element} node.
Integer Gets the number of nodes that are immediate children of the {@code Element} node.
Content[] Gets all nodes that are direct or indirect children of the {@code Element} node, in the order they appear in the document.
Document Gets the XML document that contains the {@code Element} node.
String Gets the local name of the Element node.
Namespace Gets the namespace for the Element node.
Namespace Gets the namespace with the given prefix for the Element node.
Element Gets the node's parent Element node.
String Gets the local name and namespace prefix of the Element node, in the form [namespacePrefix]:[localName] .
String Gets the text value of the Element node.
String Gets the text value of all nodes that are direct or indirect children of the node, in the order they appear in the document.
Boolean Determines whether this Element node is a direct or indirect parent of a given Element node.
Boolean Determines whether the Element node is the document's root node.
Boolean Removes the given attribute for this Element node, if such an attribute exists.
Boolean Removes the attribute for this Element node with the given name and no namespace, if such an attribute exists.
Boolean Removes the attribute for this Element node with the given name and namespace, if such an attribute exists.
Content[] Removes all nodes that are immediate children of the {@code Element} node.
Boolean Removes the given node, if the node is an immediate child of the {@code Element} node.
Content Removes the node at the given index among all nodes that are immediate children of the {@code Element} node.
Element Sets the given attribute for this Element node.
Element Sets the attribute for this Element node with the given name, value, and no namespace.
Element Sets the attribute for this Element node with the given name, value, and namespace.
Element Sets the local name of the Element node.
Element Sets the namespace for the Element node.
Element Sets the text value of the Element node.

Detailed documentation

addContent(content)

Appends the given node as the last child of the Element node. The content argument can be a Element object or any node object that corresponds to a type listed in ContentType .

Parameters

Name Type Description
content
Content the node to append

Return

Element — the Element node, for chaining


addContent(index, content)

Inserts the given node at the given index among all nodes that are immediate children of the Element node. The content argument can be a Element object or any node object that corresponds to a type listed in ContentType .

Parameters

Name Type Description
index
Integer the index at which to insert the node among all nodes that are immediate children of the Element node
content
Content the node to insert

Return

Element — the Element node, for chaining


cloneContent()

Creates unattached copies of all nodes that are immediate children of the {@code Element} node.

Return

Content[] — an array of unattached copies of all nodes that are immediate children of the {@code Element} node


detach()

Detaches the node from its parent Element node. If the node does not have a parent, this method has no effect.

Return

Content — the detached node


getAllContent()

Gets all nodes that are immediate children of the {@code Element} node.

Return

Content[] — an array of all nodes that are immediate children of the {@code Element} node


getAttribute(name)

Gets the attribute for this Element node with the given name and no namespace. If there is no such attribute, this method returns null .

Parameters

Name Type Description
name
String the name of the attribute

Return

Attribute — the attribute, or null if there is no attribute with the given name and no namespace


getAttribute(name, namespace)

Gets the attribute for this Element node with the given name and namespace. If there is no such node, this method returns null .

Parameters

Name Type Description
name
String the name of the attribute
namespace
Namespace the namespace of the attribute

Return

Attribute — the attribute, or null if there is no attribute with the given name and namespace


getAttributes()

Gets all attributes for this Element node, in the order they appear in the document.

Return

Attribute[] — an array of all attributes for this Element node


getChild(name)

Gets the first Element node with the given name and no namespace that is an immediate child of this Element node. If there is no such node, this method returns null .

Parameters

Name Type Description
name
String the name of the child Element node

Return

Element — the Element node, or null if there is no immediate child Element node with the given name and no namespace


getChild(name, namespace)

Gets the first Element node with the given name and namespace that is an immediate child of this Element node. If there is no such node, this method returns null .

Parameters

Name Type Description
name
String the name of the child Element node
namespace
Namespace the namespace of the child Element node

Return

Element — the Element node, or null if there is no immediate child Element node with the given name and namespace


getChildText(name)

Gets the text value of the node with the given name and no namespace, if the node is an immediate child of the Element node. If there is no such node, this method returns null .

Parameters

Name Type Description
name
String the name of the child node

Return

String — the text value of the child node, or null if there is no immediate child node with the given name and no namespace


getChildText(name, namespace)

Gets the text value of the node with the given name and namespace, if the node is an immediate child of the Element node. If there is no such node, this method returns null .

Parameters

Name Type Description
name
String the name of the child node
namespace
Namespace the namespace of the child node

Return

String — the text value of the child node, or null if there is no immediate child node with the given name and namespace


getChildren()

Gets all Element nodes that are immediate children of this Element node, in the order they appear in the document.

Return

Element[] — an array of all Element nodes that are immediate children of this Element node


getChildren(name)

Gets all Element nodes with the given name and no namespace that are immediate children of this Element node, in the order they appear in the document.

Parameters

Name Type Description
name
String the name of the child Element nodes

Return

Element[] — an array of all Element nodes with the given name and no namespace that are immediate children of this Element node


getChildren(name, namespace)

Gets all Element nodes with the given name and namespace that are immediate children of this Element node, in the order they appear in the document.

Parameters

Name Type Description
name
String the name of the child Element nodes
namespace
Namespace the namespace of the child Element nodes

Return

Element[] — an array of all Element nodes with the given name and namespace that are immediate children of this Element node


getContent(index)

Gets the node at the given index among all nodes that are immediate children of the {@code Element} node. If there is no node at the given index, this method returns null .

Parameters

Name Type Description
index
Integer the index for the node among all nodes that are immediate children of the {@code Element} node

Return

Content — the node, or null if there is no node at the given index


getContentSize()

Gets the number of nodes that are immediate children of the {@code Element} node.

Return

Integer — the number of nodes that are immediate children of the {@code Element} node


getDescendants()

Gets all nodes that are direct or indirect children of the {@code Element} node, in the order they appear in the document.

Return

Content[] — an array of all nodes that are direct or indirect children of the {@code Element} node


getDocument()

Gets the XML document that contains the {@code Element} node.

Return

Document — the document that contains the {@code Element} node


getName()

Gets the local name of the Element node. If the node has a namespace prefix, use getQualifiedName() or getNamespace() . getPrefix() to get the prefix.

Return

String — the local name of the Element node


getNamespace()

Gets the namespace for the Element node.

Return

Namespace — the namespace for the Element node


getNamespace(prefix)

Gets the namespace with the given prefix for the Element node.

Parameters

Name Type Description
prefix
String the prefix for the namespace

Return

Namespace — the namespace with the given prefix for the Element node


getParentElement()

Gets the node's parent Element node. If the node does not have a parent, this method returns null .

Return

Element — the parent Element node


getQualifiedName()

Gets the local name and namespace prefix of the Element node, in the form [namespacePrefix]:[localName] . If the node does not have a namespace prefix, use getName() .

Return

String — the local name and namespace prefix of the Element node, in the form [namespacePrefix]:[localName]


getText()

Gets the text value of the Element node.

Return

String — the text value of the Element node


getValue()

Gets the text value of all nodes that are direct or indirect children of the node, in the order they appear in the document.

Return

String — the text value of all nodes that are direct or indirect children of the node


isAncestorOf(other)

Determines whether this Element node is a direct or indirect parent of a given Element node.

Parameters

Name Type Description
other
Element the other Element node

Return

Boolean true if this Element node is a direct or indirect parent of the given Element node; false if not


isRootElement()

Determines whether the Element node is the document's root node.

Return

Boolean true if the Element node is the document's root node; false if not


removeAttribute(attribute)

Removes the given attribute for this Element node, if such an attribute exists.

Parameters

Name Type Description
attribute
Attribute the attribute

Return

Boolean true if the attribute existed and was removed; false if not


removeAttribute(attributeName)

Removes the attribute for this Element node with the given name and no namespace, if such an attribute exists.

Parameters

Name Type Description
attributeName
String the name of the attribute

Return

Boolean true if the attribute existed and was removed; false if not


removeAttribute(attributeName, namespace)

Removes the attribute for this Element node with the given name and namespace, if such an attribute exists.

Parameters

Name Type Description
attributeName
String the name of the attribute
namespace
Namespace the namespace of the attribute

Return

Boolean true if the attribute existed and was removed; false if not


removeContent()

Removes all nodes that are immediate children of the {@code Element} node.

Return

Content[] — an array of all nodes that were immediate children of the {@code Element} node before they were removed


removeContent(content)

Removes the given node, if the node is an immediate child of the {@code Element} node. The content argument can be a Element object or any node object that corresponds to a type listed in ContentType .

Parameters

Name Type Description
content
Content the node to remove

Return

Boolean true if the node was an immediate child and was removed; false if not


removeContent(index)

Removes the node at the given index among all nodes that are immediate children of the {@code Element} node. If there is no node at the given index, this method returns null .

Parameters

Name Type Description
index
Integer the index for the node among all nodes that are immediate children of the {@code Element} node

Return

Content — the node that was removed, or null if there is no node at the given index


setAttribute(attribute)

Sets the given attribute for this Element node.

Parameters

Name Type Description
attribute
Attribute the attribute to set

Return

Element — the Element node, for chaining


setAttribute(name, value)

Sets the attribute for this Element node with the given name, value, and no namespace.

Parameters

Name Type Description
name
String the name of the attribute to set
value
String the value of the attribute to set

Return

Element — the Element node, for chaining


setAttribute(name, value, namespace)

Sets the attribute for this Element node with the given name, value, and namespace.

Parameters

Name Type Description
name
String the name of the attribute to set
value
String the value of the attribute to set
namespace
Namespace the namespace of the attribute to set

Return

Element — the Element node, for chaining


setName(name)

Sets the local name of the Element node. To set a namespace prefix for the node, use setNamespace(namespace) in conjunction with XmlService.getNamespace(prefix, uri) .

Parameters

Name Type Description
name
String the local name to set

Return

Element — the Element node, for chaining


setNamespace(namespace)

Sets the namespace for the Element node.

Parameters

Name Type Description
namespace
Namespace the namespace to set

Return

Element — the Element node, for chaining


setText(text)

Sets the text value of the Element node. If the node already contains a text value or any child nodes, this method overwrites the old content. To append or insert content instead, use addContent(content) or addContent(index, content) .

Parameters

Name Type Description
text
String the text to set

Return

Element — the Element node, for chaining