Examples

A DOMElement is a single element in an Adobe Campaign XML variable: it is what 📕 queryDef ExecuteQuery() returns, what SOAP methods take and hand back, and what a web app reads through request.data.

Parsing XML text and constructing documents live on the XML overview — this page covers what you do with a node once you hold one: read it, find children, and serialize it.

Use these DOM methods, never E4X (<node/> literals, for each, .@attr). E4X cannot be linted or formatted and is deprecated — see the development best practices.

Read a query result

Read an attribute with the getAttribute(name) method, or the shorter .$attr accessor.

var query = NLWS.xtkQueryDef.create({
  queryDef: {
    schema: "nms:recipient",
    operation: "get",
    select: { node: [{ expr: "@email" }, { expr: "@lastName" }] },
  },
});
var recipient = query.ExecuteQuery(); // DOMElement: <recipient email="" lastName=""/>

logInfo(recipient.getAttribute("email")); // DOM method -> string
logInfo(recipient.$email); // .$attr shorthand, same value

Attribute names are passed without the @ prefix: getAttribute("email"), not getAttribute("@email"). getAttribute always returns a string.

Find child elements

To list all children, use getElements() and iterate it with forEach.

When you need a specific branch rather than every child, use the helpers:

  • getFirstElement(tag) returns the first matching child or null; pass an attribute and value to match on it.
  • Guard an optional branch with hasElement(tag).
var query = NLWS.xtkQueryDef.create({
  queryDef: {
    schema: "nms:recipient",
    operation: "select",
    select: { node: [{ expr: "@email" }, { expr: "@lastName" }] },
  },
});
var recipients = query.ExecuteQuery(); // DOMElement: <recipient-collection><recipient email="" lastName=""/></recipient-collection>

// All children
logInfo("count: " + recipients.getElements().length); // 2
recipients.getElements().forEach(function (recipient) {
  logInfo(recipient.$email);
});

// First child with a given tag, or null when absent
var first = recipients.getFirstElement("recipient");
if (first) {
  logInfo(first.$email); // [email protected]
}

// Guard before reading a branch that may be missing
if (recipients.hasElement("recipient")) {
  logInfo("at least one recipient");
}

// Find a child by attribute value: getFirstElement(tag, attribute, value)
var bob = recipients.getFirstElement("recipient", "email", "[email protected]");
logInfo(bob.$lastName); // Smith

// Every child with a tag, as an array-like (.length, [i])
var all = recipients.getElementsByTagName("recipient");
logInfo("count: " + all.length); // 2

firstChild / nextSibling exist for raw traversal, but getElements() and getFirstElement() skip text nodes and read clearer.

Going further

You meet a DOMElement every time a 📕 queryDef runs or a SOAP method returns. To build a node from scratch or parse inbound XML, see 📕 DOMDocument; for the big picture, the XML overview.

Unit tests

Tested with acc by running acc instance exec -f test/integration/DOMElement.spec.js in a sandbox: 

loadLibrary("/nl/core/shared/nl.js"); // import NL.assert

const xmlDoc = DOMDocument.fromJXON({ tagHere: { tag: [{ a: 12 }, { a: 34 }] } });
context.test0 = NL.assert(xmlDoc instanceof DOMDocument);
const root = xmlDoc.root;
context.test1 = NL.assert(typeof root === "object");
context.test2 = NL.assert(root.tagName === "tagHere");
context.test3 = NL.assert(root.hasElement("tag"));
context.test4 = NL.assert(!root.hasElement("unknownTag"));
try {
  context.test8 = NL.assert(root instanceof DOMElement); // should not reach here
} catch (e) {
  context.test9 = NL.assert(e.toString() === "TypeError: invalid 'instanceof' operand DOMElement");
}
context.test10 = NL.assert(root.toXMLString() === '<tagHere><tag a="12"/><tag a="34"/></tagHere>');

context.test20 = NL.assert(root.getElements().length === 2);
context.test21 = NL.assert(root.getElements("tag").length === 2);
context.test22 = NL.assert(root.getElementsByTagName("tag").length === 2);
context.test23 = NL.assert(root.getElements("tag")[0].tagName === "tag");
context.test24 = NL.assert(root.getElements("tag")[0].hasAttribute("a"));
context.test25 = NL.assert(root.getElements("tag")[0].getAttribute("a") === "12");
context.test26 = NL.assert(root.getElements("tag")[0].$a === "12");

See also

  • 📕 DOMDocument - Adobe Campaign's XML document: create a tree from scratch, from an object, or by parsing text. Its root is a DOMElement.
  • 📕 queryDef - Helper to run a SQL SELECT query with JSON and returns an XML element.
  • 📕 getOption - Helper to read an instance-specific setting from the xtk:option schema, useful for environment variable.
  • 📕 NL.XTK.parse - Adobe Campaign's parsing helpers to safe cast XML values.