Class 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

Method	Return type	Brief description
`addContent(content)`	`Element`	Appends the given node as the last child of the `Element` node.
`addContent(index, content)`	`Element`	Inserts 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()`	`Content`	Detaches the node from its parent `Element` node.
`getAllContent()`	`Content[]`	Gets all nodes that are immediate children of the {@code Element} node.
`getAttribute(name)`	`Attribute`	Gets the attribute for this `Element` node with the given name and no namespace.
`getAttribute(name, namespace)`	`Attribute`	Gets 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)`	`Element`	Gets the first `Element` node with the given name and no namespace that is an immediate child of this `Element` node.
`getChild(name, namespace)`	`Element`	Gets the first `Element` node with the given name and namespace that is an immediate child of this `Element` node.
`getChildText(name)`	`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.
`getChildText(name, namespace)`	`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.
`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)`	`Content`	Gets the node at the given index among all nodes that are immediate children of the {@code Element} node.
`getContentSize()`	`Integer`	Gets 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()`	`Document`	Gets the XML document that contains the {@code Element} node.
`getName()`	`String`	Gets the local name of the `Element` node.
`getNamespace()`	`Namespace`	Gets the namespace for the `Element` node.
`getNamespace(prefix)`	`Namespace`	Gets the namespace with the given prefix for the `Element` node.
`getParentElement()`	`Element`	Gets the node's parent `Element` node.
`getQualifiedName()`	`String`	Gets the local name and namespace prefix of the `Element` node, in the form `[namespacePrefix]:[localName]`.
`getText()`	`String`	Gets the text value of the `Element` node.
`getValue()`	`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.
`isAncestorOf(other)`	`Boolean`	Determines whether this `Element` node is a direct or indirect parent of a given `Element` node.
`isRootElement()`	`Boolean`	Determines whether the `Element` node is the document's root node.
`removeAttribute(attribute)`	`Boolean`	Removes the given attribute for this `Element` node, if such an attribute exists.
`removeAttribute(attributeName)`	`Boolean`	Removes the attribute for this `Element` node with the given name and no namespace, if such an attribute exists.
`removeAttribute(attributeName, namespace)`	`Boolean`	Removes 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)`	`Boolean`	Removes the given node, if the node is an immediate child of the {@code Element} node.
`removeContent(index)`	`Content`	Removes the node at the given index among all nodes that are immediate children of the {@code Element} node.
`setAttribute(attribute)`	`Element`	Sets the given attribute for this `Element` node.
`setAttribute(name, value)`	`Element`	Sets the attribute for this `Element` node with the given name, value, and no namespace.
`setAttribute(name, value, namespace)`	`Element`	Sets the attribute for this `Element` node with the given name, value, and namespace.
`setName(name)`	`Element`	Sets the local name of the `Element` node.
`setNamespace(namespace)`	`Element`	Sets the namespace for the `Element` node.
`setText(text)`	`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