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 |
---|---|---|
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()
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()
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()
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)
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)
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