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

MethodReturn typeBrief description
addContent(content)ElementAppends the given node as the last child of the Element node.
addContent(index, content)ElementInserts the given node at the given index among all nodes that are immediate children of the Element node.
cloneContent()Content[]Creates unattached copies of all nodes that are immediate children of the {@code Element} node.
detach()ContentDetaches the node from its parent Element node.
getAllContent()Content[]Gets all nodes that are immediate children of the {@code Element} node.
getAttribute(name)AttributeGets the attribute for this Element node with the given name and no namespace.
getAttribute(name, namespace)AttributeGets the attribute for this Element node with the given name and namespace.
getAttributes()Attribute[]Gets all attributes for this Element node, in the order they appear in the document.
getChild(name)ElementGets the first Element node with the given name and no namespace that is an immediate child of this Element node.
getChild(name, namespace)ElementGets the first Element node with the given name and namespace that is an immediate child of this Element node.
getChildText(name)StringGets the text value of the node with the given name and no namespace, if the node is an immediate child of the Element node.
getChildText(name, namespace)StringGets the text value of the node with the given name and namespace, if the node is an immediate child of the Element node.
getChildren()Element[]Gets all Element nodes that are immediate children of this Element node, in the order they appear in the document.
getChildren(name)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.
getChildren(name, namespace)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.
getContent(index)ContentGets the node at the given index among all nodes that are immediate children of the {@code Element} node.
getContentSize()IntegerGets the number of nodes that are immediate children of the {@code Element} node.
getDescendants()Content[]Gets all nodes that are direct or indirect children of the {@code Element} node, in the order they appear in the document.
getDocument()DocumentGets the XML document that contains the {@code Element} node.
getName()StringGets the local name of the Element node.
getNamespace()NamespaceGets the namespace for the Element node.
getNamespace(prefix)NamespaceGets the namespace with the given prefix for the Element node.
getParentElement()ElementGets the node's parent Element node.
getQualifiedName()StringGets the local name and namespace prefix of the Element node, in the form [namespacePrefix]:[localName].
getText()StringGets the text value of the Element node.
getValue()StringGets the text value of all nodes that are direct or indirect children of the node, in the order they appear in the document.
isAncestorOf(other)BooleanDetermines whether this Element node is a direct or indirect parent of a given Element node.
isRootElement()BooleanDetermines whether the Element node is the document's root node.
removeAttribute(attribute)BooleanRemoves the given attribute for this Element node, if such an attribute exists.
removeAttribute(attributeName)BooleanRemoves the attribute for this Element node with the given name and no namespace, if such an attribute exists.
removeAttribute(attributeName, namespace)BooleanRemoves the attribute for this Element node with the given name and namespace, if such an attribute exists.
removeContent()Content[]Removes all nodes that are immediate children of the {@code Element} node.
removeContent(content)BooleanRemoves the given node, if the node is an immediate child of the {@code Element} node.
removeContent(index)ContentRemoves the node at the given index among all nodes that are immediate children of the {@code Element} node.
setAttribute(attribute)ElementSets the given attribute for this Element node.
setAttribute(name, value)ElementSets the attribute for this Element node with the given name, value, and no namespace.
setAttribute(name, value, namespace)ElementSets the attribute for this Element node with the given name, value, and namespace.
setName(name)ElementSets the local name of the Element node.
setNamespace(namespace)ElementSets the namespace for the Element node.
setText(text)ElementSets 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

NameTypeDescription
contentContentthe 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

NameTypeDescription
indexIntegerthe index at which to insert the node among all nodes that are immediate children of the Element node
contentContentthe 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

NameTypeDescription
nameStringthe 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

NameTypeDescription
nameStringthe name of the attribute
namespaceNamespacethe 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

NameTypeDescription
nameStringthe 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

NameTypeDescription
nameStringthe name of the child Element node
namespaceNamespacethe 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

NameTypeDescription
nameStringthe 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

NameTypeDescription
nameStringthe name of the child node
namespaceNamespacethe 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

NameTypeDescription
nameStringthe 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

NameTypeDescription
nameStringthe name of the child Element nodes
namespaceNamespacethe 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

NameTypeDescription
indexIntegerthe 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

NameTypeDescription
prefixStringthe 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

NameTypeDescription
otherElementthe other Element node

Return

Booleantrue 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

Booleantrue 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

NameTypeDescription
attributeAttributethe attribute

Return

Booleantrue 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

NameTypeDescription
attributeNameStringthe name of the attribute

Return

Booleantrue 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

NameTypeDescription
attributeNameStringthe name of the attribute
namespaceNamespacethe namespace of the attribute

Return

Booleantrue 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

NameTypeDescription
contentContentthe node to remove

Return

Booleantrue 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

NameTypeDescription
indexIntegerthe 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

NameTypeDescription
attributeAttributethe 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

NameTypeDescription
nameStringthe name of the attribute to set
valueStringthe 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

NameTypeDescription
nameStringthe name of the attribute to set
valueStringthe value of the attribute to set
namespaceNamespacethe 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

NameTypeDescription
nameStringthe local name to set

Return

Element — the Element node, for chaining


setNamespace(namespace)

Sets the namespace for the Element node.

Parameters

NameTypeDescription
namespaceNamespacethe 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

NameTypeDescription
textStringthe text to set

Return

Element — the Element node, for chaining