CDA API Guide

These functions are used to add, set or find XML elements:


node.text() [top]

Usage: node.text(<TARGET: PARENT XML ELEMENT>)

Finds and returns the first XML TEXT element. This works with a simple text element, or a “complex element” (one with sub-elements). If a text element does not exist it is appended to the parent element, then returned. Notice that we use rounded brackets instead of curly braces.

Returns: The first XML TEXT element

Required Parameters:

  • target: Parent element that contains the TEXT element

Example:

Note: In this example the first XML TEXT contains the string “Good Health Clinic Consultation Note”

CD.title:text()

Example Result:

<title>Good Health Clinic Consultation Note</title>

Note: In this example there is no XML TEXT element, so an empty one is created and returned

GP.name:text()

Example Result:

<name>
    <given>Ralph</given>
    <family>Jones</family>
    -- an empty text element is appended and returned
</name>

node.setText() [top]

Usage: node.setText(<TARGET: PARENT XML ELEMENT>, <VALUE: TEXT STRING>)

Sets the text in an XML TEXT element. This works with a simple text element, or a “complex element” (one with sub-elements). If a text element does not exist it is appended to the parent element. Notice that we use rounded brackets instead of curly braces.

Returns: Nothing

Required Parameters:

  • target: Element to set the text for
  • value: Text string value for the element

Example:

Note: A variable “setText” is used as a shorthand, to make the call more concise (this is created at the start of each module)

local setText = node.setText -- create shortcut

setText(CD.title, 'Good Health Clinic Consultation Note')

Example Result:

<title>Good Health Clinic Consultation Note</title>

Note: In this example we append a text element to a complex element

local setText = node.setText -- create shortcut
setText(GP.name, 'Append a text element')

Example Result:

<name>
    <given>Ralph</given>
    <family>Jones</family>
    Append a text element  -- appended text element
</name>

node.setAttr() [top]

Usage: node.setAttr(<TARGET: PARENT XML ELEMENT>, <ATTRIBUTE>, <VALUE: TEXT STRING>)

Sets the named attribute to a specified value. If a the specified attribute does not exist it is appended to the parent element. Notice that we use rounded brackets instead of curly braces.

Returns:

  • The updated parent element

Required Parameters:

  • target: The parent element
  • attribute: The name of the attribute to set
  • value: Text string value for the attribute

Example:

Note: A variable “setAttr” is used as a shorthand, to make the call more concise (this is created at the start of each module)

local setAttr = node.setText -- create shortcut

setAttr(PE, 'classCode', 'PLC')

Example Result:

<playingEntity classCode="PLC">              -- appended attribute
   <name>Community Urgent Care Center</name>
</playingEntity>

Note: In this example we append a second attribute to the “playingEntity”

local setAttr = node.setText -- create shortcut
setAttr(PE, 'another', 'attribute')

Example Result:

<playingEntity classCode="PLC" another="attribute"> -- another appended attribute
   <name>Community Urgent Care Center</name>
</playingEntity>

node.addElement() [top]

Usage: node.addElement(<TARGET: PARENT XML ELEMENT>, <ELEMENT: ELEMENT NAME>)

Appends an empty named element to the parent element. Notice that we use rounded brackets instead of curly braces.

Returns:

  • The appended element

Required Parameters:

  • target: The parent element
  • element: The name of the element to append

Example:

Note: A variable “addElement” is used as a shorthand, to make the call more concise (this is created at the start of each module)

local addElement = node.setAttr -- create shortcut

local P = addElement(birthplace, 'place')

Example Result:

<birthplace>
   <place>
   </place>
</birthplace>

xml.findElement() [top]

Usage: xml.findElement(<TARGET: XML ELEMENT>, <ELEMENT: ELEMENT NAME>)

Find the first element of the specified name in the target. If the target is a tree, it will do a depth-first search of tree. Notice that we use rounded brackets instead of curly braces.

Note: If there are multiple elements with the same name this function will only find the first one.

Returns:

  • The first element found that matches the name specified

Required Parameters:

  • target: Element to search within
  • element: The name of the element to search for

Example:
xml.findElement(G,'guardianPerson')