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.

 

If you are already familiar with the XMLData interface because you used it in the XMLSpy API, please note that special considerations must be made if new elements are created and inserted into the XML file, or existing elements are renamed. Please take a look at "Creation and Insertion of new XMLData objects" and "Name and value of elements" below.

 

Structure of XMLData

Before you can use the XMLData interface, you have to know how an existing XML file is mapped into a XMLData structure. One major thing you must be aware of is, that XMLData has no seperate branch of objects for attributes.

 

The attributes of an element are also children of the element. The XMLData.Kind property, gives you the opportunity to distinguish between the different types of children of an element.

 

Example:

 

This 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 of 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 to 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 the Authentic View. The name has an important impact how the Authentic View displays the content of the element. Please refer to the StyleVision documentation for detailed information.

 

 

Creation and insertion of new XMLData objects

The creation of a new XML language entity requires the following steps:

 

1.Create the new XMLData object:

Use the Authentic.CreateChild method to create a new XMLData object. Set name and value before you insert the new XML entity (see point 3).

 

2.Find the correct location for the new XMLData object:

To insert a new XMLData object you have to get a reference to the parent first. If the new child is to become the last child of the parent, use the XMLData.AppendChild method to insert the XMLData object.

If the new child should be located elsewhere in the sequence of child objects, use the XMLData.GetFirstChild and XMLData.GetNextChild to move the iterator to the child before which the new child should be inserted.

 

3.        Insert the new child with XMLData.InsertChild. The new child will be inserted immediately before the current child. In the Authentic View it can happen that together with the created element additional child nodes will be added to the XML file. This depends on the node settings you can modify using the StyleVision.

 

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

 

 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

 

Child elements should be inserted in a special order. Please avoid to insert attributes into the sequence after any other child elements. That means attributes must not have preceding elements of any other type and any other element must not have a succeeding element of type attribute.

 

Authentic View requires a special handling of displaying the text value of an XML element except for attributes. Any text (or content) must be part of an extra child node of type text. You can create such an element using Authentic.CreateChild with the parameter value 6. Instead of setting the text value of the element directly please set the text value of the child node.

 

 

Copying of 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 of using InsertChild or AppendChild, you have 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;

 }

 

 

Erasing of XMLData objects

XMLData provides two methods for the deletion of child objects, XMLData.EraseAllChildren and XMLData.EraseCurrentChild.

 

To erase XMLData objects you need access to 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.


© 2018 Altova GmbH