Skip to content

Build XML

Info

This how-to assumes you are familiar with setting up a project either manually or via VoltScript Dependency Management. If you are not, follow the Intro to VoltScript Tutorials.

Introduction

Although the most efficient way of modifying and improving your XML is through parsing, XMLVSE is also designed to allow developers to construct an XML tree from scratch. In this guide, the focus is on writing XML.

VoltScript dependencies

Incorporating XMLVSE is straightforward. You just need to add the following JSON object to the vsesDependencies element in your atlas.json.

        "XmlVSE": {
            "library": "25893",
            "version": "1.0.0",
            "module": "25892/20856",
            "repository": "volt-mx-marketplace"
        }

You'll need to add to your repositories object in the atlas.json of your project:

        {
            "id": "volt-mx-marketplace",
            "type": "marketplace",
            "url": "https://community.demo-hclvoltmx.com/marketplace/asset"
        }

To use the extension in your script, enter UseVSE "*XMLVSE".

XMLObject class

The XMLObject class is used to hold the whole XML tree.

Construct XML Objects

To construct an XML from scratch, you need to know the key components that XML is composed of:

  • Root: the primary and topmost element of an XML
  • Attribute: defines the properties of a specific XML element
  • Child - elements contained inside a specific XML element.

XML elements that have a child or children are called Parent XML elements.

To populate your XML from scratch, add a root element using the AddRootTag(). The first parameter is the tag and the second parameter is the value.

Note

Element values are optional depending on how you want your expected XML to look. You can set it as empty if you want to add another element on your root instead of a string value. In you used AddRootTag() to an XML object that already has a root element, a 404 error occurs. The error message is Current Object needs to be Empty to be able to add a new tag.

Once your XMLObject has a root, you can now add Attributes into your XML Object if you want using addAttribute(). The first parameter is the tag and the second parameter is the value.

Function buildXML() as XMLObject

    Dim xmlObj as New XMLObject

    Call xmlObj.addRootTag("Test", "Hello World")
    Call xmlObj.addAttribute("version", "1")

    Return xmlObj
End Function

Add Child Elements

There are two ways to add Child Elements to your XML. The first way is to use string inputs AddChild() with the first parameter being the tag and the second parameter being the value. The second way is to use another XML Object AddChildObject() with the parameter needing to be an XMLObject.

Note

For addChild(), element values are optional depending on how you want your expected XML to look. You can set it as empty if you want to add another element on your child element instead of a string value. For AddChildObject(), if the passed parameter isn't an XML object, error 53291 occurs. The error message is Type mismatch on: followed by the supplied input. In case the passed XML Object isn't a valid XML, error 404 occurs. The error message is Child Object is Empty.

Function buildXMLWithChildren() as XMLObject

    Dim xmlObj as New XMLObject

    Call xmlObj.addRootTag("Test", "")
    Call xmlObj.addChild("Hello", "World")

    Dim ChildObj as New XMLObject
    Call ChildObj.addRootTag("Foo", "Bar")

    Call xmlObj.addChildObject(ChildObj)

    Return xmlObj
End Function

Remove Elements

Removing XML Elements is also part of modifying your XML tree. XMLVSE also has methods that you can use to remove certain elements from your XML tree.

  • To remove attributes, use RemoveAttribute(). The parameter is the attribute tag.
  • To remove a child element, use RemoveChild(). The parameter is the child tag. You can also use RemoveChildObject()to remove a child using an object parameter.
Function removeXMLElements(xmlObj as XMLObject) as XMLObject

    Call xmlObj.removeAttribute("version")
    Call xmlObj.removeChild("Hello")

    Dim ChildObj as New XMLObject
    Set ChildObj = xmlObj.getChild("Foo")
    Call xmlObj.removeChildObject(ChildObj)

    Return xmlObj
End Function

Return XML

For both XMLParser and XMLObject, you can use ToString() to return the full XML object as a string. If the passed argument is True, a prettified or indented XML is printed. If the passed argument is False, a compact XML is printed.

The complete implementations of the code snippets are available on GitHub.