Using XMLData

Previous Top Next

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:

Access to the names and values of all kinds of elements (e.g. elements, attributes)

Creation of new elements of all kinds.

Insertion and appending of new elements.

Erasing of existing child elements.

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>
         
         </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 "XMLSpyDocumentEditor.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 a text value associated.

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 "XMLSpyDocumentEditor.CreateChild" method to create a new XMLData object. Set name and value after you have inserted 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.

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

   Dim objParent
   Dim objChild
   Dim objNewChild

   Set objNewChild = objPlugIn.CreateChild(spyXMLDataElement)

   '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
   objNewChild.Name = "OneAndAHalf"
   Set objNewChild = Nothing

Copying of existing XMLData objects

If you want to insert existing XMLData objects at a different place in the same file you can't 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 "EraseAllChildren" and "EraseCurrentChild" for examples how to erase XML elements.

Previous Top Next

⌐ 2002 Altova