Class Element

  • The Element object represents an XML Element node and provides methods for manipulating its content, attributes, and relationships within an XML document.

  • You can add, remove, and retrieve content (including child elements and other nodes) from an Element using methods like addContent, removeContent, getAllContent, getChildren, and getContent.

  • Attributes of an Element can be accessed, set, and removed using methods like getAttribute, getAttributes, setAttribute, and removeAttribute.

  • The name and text value of an Element can be retrieved and set using getName, getQualifiedName, getText, setText, and getValue.

  • Methods are available to check the parent and document of an Element, determine if it is the root element, and detach it from its parent.
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.
let xml = '<things>' +
    '<plates>12</plates>' +
    '<bowls>18</bowls>' +
    '<cups>25</cups>' +
    '</things>';
const document = XmlService.parse(xml);
const root = document.getRootElement();
const items = root.getChildren();
let total = 0;
for (let i = 0; i < items.length; i++) {
  total += Number(items[i].getText());
}
const 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

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

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

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

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

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

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