Using XMLData

www.altova.com Print this Topic Previous Page Up One Level Next page

Home >  User Reference > Mechanisms >

Using XMLData

XMLData gives you access to the elements of the currently displayed XML file. It enables you to perform all necessary modifications to the elements of the XML structure. The main functionality of XMLData is:

 

1.Access to the names and values of all kinds of elements (e.g. elements, attributes)
2.Creation of new elements of all kinds
3.Insertion and appending of new elements
4.Erasing of existing child elements

 

The XMLData interface works differently in the Authentic API from the way it works in the XMLSpy API, specifically if new elements are inserted into the XML file or existing elements are renamed. See the sections below named Creation and Insertion of New XMLData objects and Name and Value of Elements.

 

Structure of XMLData

In order to use the XMLData interface, you must know how an existing XML file is mapped to an XMLData structure. One important point is this: XMLData has no separate objects for attributes; the attributes of an element are children of the element. An element can have other types of children (such as child elements and text content). The XMLData.Kind property gives you the opportunity to distinguish between the different types of children of an element. Given below is an example:

 

The following XML code,

 

<ParentElement>

 <FirstChild attr1="Red" attr2="Black">

                 This is the value of FirstChild

         </FirstChild>

         <SecondChild>

           <!--Your Comment-->

                  </DeepChild>

         </SecondChild>

         This is Text

</ParentElement>

 

is mapped to the following XMLData object structure:

 

 api_XMLData

 

The parent of all XML elements inside a file is the property Authentic.XMLRoot. Use this XMLData object to get references to all other XML elements in the structure.

 

Name and value of elements

To get and modify the name and value of all types of XML elements, use the XMLData.Name and XMLData.TextValue properties. It is possible that several kinds of XMLData objects and empty elements do not have an associated text value. It is not recommended to change the name of an existing XML element in Authentic View because the name has a bearing on how Authentic View displays the content of the element. See the StyleVision documentation for information.

 

Creation and insertion of new XMLData objects

Create a new XMLData object (such as an element, attribute or text node) as follows:

 

1.Use the Authentic.CreateChild method to create a new XMLData object. Set the name and value of the new object before you insert it.
2.Insert the new object at the correct location with reference to its parent: (i) If the new child is to become the last child of the parent, use the XMLData.AppendChild method. (ii) To insert the new child elsewhere in the sequence of child objects, use either the XMLData.GetFirstChild or XMLData.GetNextChild method to locate the child before which the new child should be inserted; then insert the new child with XMLData.InsertChild. The new child will be inserted immediately before the current child.

 

Note:In Authentic View, a new element can be created together with its substructure because the element's structure is defined in the XML Schema. However, whether the substructure is created or not can be set in the node settings of the SPS. See the StyleVision documentation for information.

 

The following example adds a third child between the <FirstChild> and <SecondChild> elements:

 

 Dim objParent

 Dim objChild

 Dim objNewChild

 

 Set objNewChild = objPlugIn.CreateChild(spyXMLDataElement)

 objNewChild.Name = "OneAndAHalf"

 

 'objParent is set to <ParentElement>

 'GetFirstChild(-1) gets all children of the parent element

 'and move to <SecondChild>

 Set objChild = objParent.GetFirstChild(-1)

 Set objChild = objParent.GetNextChild

 

 objParent.InsertChild objNewChild

 Set objNewChild = Nothing

 

An element's child nodes must be inserted in a specific order: insert the element's attributes first, then the element's child elements. Text content of an element must be added as a child node of type text; use Authentic.CreateChild with the parameter value 6. An element's text content is entered as the text value of the child node.

 

Copying existing XMLData objects

If you want to insert existing XMLData objects at a different place in the same file, you cannot use the XMLData.InsertChild and XMLData.AppendChild methods. These methods only work for new XMLData objects. Instead, you need to copy the object hierarchy manually. The following function written in JavaScript is an example for recursively copying XMLData:

 

 

 // this function returns a complete copy of the XMLData object

 function GetCopy(objXMLData)

 {

         var objNew;

         objNew = objPlugIn.CreateChild(objXMLData.Kind);

 

         objNew.Name = objXMLData.Name;

         objNew.TextValue = objXMLData.TextValue;

 

         if(objXMLData.HasChildren)        {

                 var objChild;

                 objChild = objXMLData.GetFirstChild(-1);

         

                 while(objChild)        {

                         try {

                                 objNew.AppendChild(GetCopy(objChild));

                                 objChild = objXMLData.GetNextChild();

                         }

                         catch(e) {

                                 objChild = null;

                         }

                 }

         }

 

         return objNew;

 }

 

 

Removing XMLData objects

XMLData provides two methods for removing child objects: XMLData.EraseAllChildren and XMLData.EraseCurrentChild. To remove XMLData objects, first access the parent of the elements you want to remove. Use XMLData.GetFirstChild" and XMLData.GetNextChild to get a reference to the parent XMLData object. See the method descriptions of XMLData.EraseAllChildren and XMLData.EraseCurrentChild for examples how to erase XML elements.

 


© 2019 Altova GmbH