Chapter 8 Working with XML Documents

Creating XML documents

In PowerDynamo, an XML document is any string that contains a valid XML document. Once you have created an XML document, you can send it to a browser, or parse it and process it using the DynaScript DOM objects.

You can create XML documents in PowerDynamo from a variety of sources:

DynaScript query object From a query object, using the ResultsToXMLString method.
Dynamo SQL and FORMATTING tags From a query, using the FORMATTING tag with the FORMAT_AS attribute set to XML.
DynaScript objects From any DynaScript object, using the toXMLString function.
Sybase Central From the Add Template wizard, which provides XML output options.
DynaScript By writing scripts to output XML documents in a custom fashion, adding tags as required.
Import By importing an XML file into your Web site.

The built-in methods for producing XML documents are discussed in this section.

Creating XML documents from the query object

If you use the DynaScript query object to execute a SQL query against your database, you can use the ResultsToXMLString method to wrap the results in XML tags.

For an alternative approach using tags, see "Creating XML documents from queries using the FORMATTING tag".

Example

The following script illustrates how to use ResultsToXMLString :

myConn = site.GetConnection( "myConn" );         //1
myQuery = myConn.CreateQuery(
  "SELECT id, name, unit_price FROM product" );  //2
xmlString = myQuery.ResultsToXMLString(
           "Products", 
           "Product", 
           "ID Name Price" );                    //3
document.writeln( xmlString );                   //4

Line 1 Create a connection object from the current connection.
Line 2 Create a query object from the connection object and executes the query. The query retrieves some columns from the product table in the demo database.
Line 3 Format the query results into an XML string.
ResultsToXMLString takes between zero and four parameters. For details, see "ResultsToXMLString method" in PowerDynamo Reference.
Line 4 Write out the XML string. The string contains tags around the individual results rather than providing a DTD. The output string has no white space. Here it is, with white space added for readability:
```
<Products>
  <Product>
    <ID>600</ID>
    <Name>Sweatshirt</Name>
    <Price>24.00</Price>
  </Product>
  <Product>
    <ID>601</ID>
    <Name>Sweatshirt</Name>
    <Price>24.00</Price>
  </Product>
</Products>
```
The entire result set constitutes a Products element. Each row is a Product element, and contains ID, Name, and Price elements.

Notes

There are several points of interest in the above example.

Error checking The example script does not include any error checking. In a real application, you should verify that each individual step succeeds. Check the method return values or use the GetErrorCode method of the object carrying out the step. Many methods return null when they fail.
White space White space outside tags, including new line and carriage return characters, is significant in XML. It is added in the sample above for readability, but in fact changes the document. You must be careful about extraneous white space in your XML documents.
XML header For the example script to be a complete XML document, you must add a proper XML header, such as the following:
```
<?xml version='1.0' encoding='ISO-8859-1'?>
```
Default tags The default result set tag is SYBRESULTSET. The default row tag is SYBROW. If you do not supply any tags in the arguments to ResultsToXMLString , the name of the column is used as the tag for each tag. If you supply a single tag, it is used for all columns. If you supply more than one tag, but not as many as there are columns, then the remaining columns tags default to the column labels.
Validation The XML output string is not validated. To validate the XML, you must do so independently of Dynamo.
Applying attributes The ResultsToXMLString method provides a convenient way of supplying simple XML. To specify attributes for XML tags in your output, see "Creating custom XML documents from query result sets".

Creating custom XML documents from query result sets

You can customize the XML you obtain from the result set of a query object by building an XML string explicitly, instead of using ResultsToXMLString .

For example:

xmlString = "<Products>";
while ( myQuery.MoveNext() ){
  xmlString += "<Product>";
  xmlString += "<ID>" + myQuery.GetValue(1) + "</ID>" ;
  xmlString += "<Name>" + myQuery.GetValue(2) + "</Name>";
  xmlString += '<Price units="DOLLARS">' + myQuery.GetValue(3) + "</Price>";
  xmlString += "</Product>";
}
xmlString += "</Products>";

Creating XML documents from queries using the FORMATTING tag

The FORMATTING tag provides a way of writing out the results of queries as XML.

The following template illustrates how to use the FORMATTING tag with XML output. You must enter the FORMATTING tag, like any tag, all on one line in a Dynamo template:

<!--SQL
SELECT description, color
FROM product
WHERE unit_price  > 15
 -->
<!--FORMATTING FORMAT_AS="XML" RESULTSET_TAG="Products" ROW_TAG="Product" COLUMN_TAG="Description Color"-->
<!--/FORMATTING-->

The output of this template is the following. Line wrapping occurs in the printed document but is not present in the actual output string:

<Products>
  <Product>
    <Description>Hooded Sweatshirt</Description>
    <Color>Green</Color>
  </Product>
  <Product>
    <Description>Zipped Sweatshirt</Description>
    <Color>Blue</Color>
  </Product>
</Products>

Notes

Attributes The attributes of the FORMATTING tag are as follows:
- FORMAT_AS attribute Can have values of HTML or XML. HTML is the default.
- RESULTSET_TAG attribute Provides the element name for the tag that surrounds the entire result set. In the example, Products.
- ROW_TAG attribute Provides the element name for the tag that surrounds each row. In the example, Product.
- COLUMN_TAG attribute If no COLUMN_TAG attribute is provided, the column's label is used. Multiple column tags can be specified in a space-delimited string. If a single column tag is provided, this tag is used to mark all columns. If multiple column tags are provided, but not as many as there are columns, then the remaining columns tags will default to the column labels.
Only applies to default formatting The attributes apply only if there is nothing between the FORMATTING tag and its end tag. If you add  tags, then the attributes do not apply.
Validation The XML output string is not validated. To validate the XML, you must do so independently of Dynamo.
Applying attributes The FORMATTING tag provides a convenient way of supplying simple XML. To specify attributes for any of the XML tags in your output, see "Creating custom XML documents from query result sets".

Creating XML from DynaScript objects

You can create XML from any DynaScript object using the toXMLString function.

This function accepts 1, 2, or 3 arguments:

Argument 1 is the DynaScript object for which an XML representation is requested.
Argument 2 (optional) specifies whether to build a CDATA section to escape special XML characters. The default value is false.
Argument 3 (optional) specifies a set of tags to use when unnamed members of the object are encountered. The toXMLString function returns null if a non-object argument is passed as the first argument, or if the object passed has no enumerable members. Otherwise it returns a string.

Examples

The following set of scripts illustrate how to use toXMLString :

Create a simple object and write it out as an XML string. The property names are used as tags.
```

```
The output for the script is as follows:
```
<a>2</a><b>3</b>
```

Create a nested object and write it out as an XML string. The structure of the document reflects the structure of the object.

<!--SCRIPT
//Create a nested object
myObj = null; 
myObj.a = 2; 
myObj.b.b1 = 3; 
myObj.b.b2 = 4; 
x = toXMLString( myObj ); 
document.writeln(x); 
-->