The manipulation of a document in xCommerce is not limited solely to the visual drag and drop actions in the xCommerce Action Model.  All the properties and methods defined by the DOM specification are available in xCommerce and can be used within the Action Model.  These include methods to create nodes of various types, such as ELEMENT or ATTRIBUTE nodes, and insert them into the document. 

xCommerce provides a "Comment..." action which adds a comment to the action model.  But how would a user of xCommerce add a node representing a comment to an XML Document, say the Output document?  This article will show how this can be accomplished by using DOM methods, along with the xCommerce actions required to perform this type of processing.  The example will concentrate on adding a COMMENT node (as described by the W3C) to the Output DOM, but any type of DOM Node can added to the DOM in a similar fashion.  For a list of Node types please refer to the Document Object Model Pages at http://www.w3.org/DOM.

 As Figure 1 shows, only two xCommerce actions are required to add a comment node to the DOM tree.  Let me briefly explain the xCommerce actions and why they are used.

Figure 1

 1.  The first function call uses an xCommerce extension method, createXPath, to create two nodes in a tree, the ROOT_NODE and a child node named CHILD_NODE.  This function call is used to create an XML document with a parent and child node.  The comment node will be added to the child node.  Note: xCommerce extension methods are methods, added by SilverStream, that extend the Document Object Model.  They are not part of the DOM specification but were found to be very useful.

 2.  The second function call will use a DOM method named createComment to create a comment and assign it to an ECMAScript variable named commentnode.  A look at Figure 2 shows that the DOM methods are available (in the Functions/Methods section under the Document category.  If you hover over the method, createComment, you can see a small micro-help box appear that gives us some basic information about this method. The createComment method is applied to the Output document, but it is not added to the document.  It is an "unattached" node in the Output document.

Figure 2

3.  The third function call will take the unattached commentnode and add it to the Output document by using the appendChild DOM method.  A glance at Figure 3 shows the component after completion, however we don't see the comment node in the Tree View of the Output document.  That is because not all node types are shown in the Tree View.  Figure 4 shows the Text View of the Output Document and the comment is clearly shown in the Output document.  Toggling between Text and Tree view is available from the View menu item or by using the right mouse button while positioned anywhere in the document view.

Figure 3

Figure 4

 Adding a comment using one xCommerce action.

 By using a Custom Script Function it is possible to reduce the two-step process of adding a comment to a single xCommerce action.  The custom script function will be described first:

function attachComment(parentNode, commentData)

{

            document = parentNode.ownerDocument;

            var cnode = document.createComment(commentData);

            parentNode.appendChild(cnode);

            return(0);                     

}

1. The function takes two parameters: the node which will receive the comment and the comment text itself.
2. The first statement in the function  retrieves the name of the document that the receiving  node belongs to. In our example it is the Output document.
3. The next line creates an "unattached" comment node on the Output document.
4. The next line adds it to the receiving node
5. Finally, we exit the function.

 As Figure 5 shows we use the xCommerce Function action to call the Custom Script Function.  In this case we pass in the parent node name as well as the comment data.  All it takes is one step. 

Figure 5

 xCommerce allows you to easily manipulate XML documents by using xCommerce Actions, DOM methods and xCommerce extension methods to the Document Object Model.  Included in the xCommerce installation is a sample project named Expressions which includes examples of how to use all the DOM properties and methods in xCommerce.  It can be found in the [xCommerce_Install_directory]/Samples directory.