Document! X supports transforming structured XML content to HTML using XSLT. Using XSLT to transform XML / SQL comments allows you to further customize the output generated from a given set of content. It also allows you to enter more complicated and structured XML / SQL source comments, the output of which can be customized without making changes to the comment itself.

Worked Example: Using an XSL Transform to show a History List

Below is an example of an XML source comment and an equivalent Transact SQL comment that we would like to appear in table form in the generated output.

/// <HistoryContent>
/// <History>
/// <HistoryEntry Date="1/1/2011" Name="Author 1" type="New" Description="Created"/>
/// <HistoryEntry Date="1/5/2011" Name="Author 2" type="Fix" Description="Edited" />
/// </History>
/// </HistoryContent>

-- ##HISTORYCONTENT <History><HistoryEntry Date="1/1/2011" Name="Author 1" type="New" Description="Created"/><HistoryEntry Date="1/5/2011" Name="Author 2" type="Fix" Description="Edited content" /></History>

Step 1: Create a Custom Content Item Type

1. From the Tools ribbon tab click the Options ribbon button.
2. In the Options window select the Content Item Types page.
3. Click the New  toolbar button.
4. Populate the fields for the new Content Item Type, giving it an Identifier of HISTORYCONTENT and an Xml Tag Name of HistoryContent (so that Document! X can match this Content Item Type to the name of the grouping XML source comment / SQL comment).
5. Tick the Item Types for which you will be using this content in your source comments and therefore you want the content to appear in the generated documentation.
6. Copy the following XSLT XML from the example below (into a text editor) and save it to a local .xsl file.

   XSLT

   Copy Code

   <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"> <xsl:output method="html"/> <xsl:template match="/"> <xsl:apply-templates /> </xsl:template> <xsl:template match="History"> <table> <tr> <th>Date</th> <th>Name</th> <th>Type</th> <th>Description</th> </tr> <xsl:apply-templates /> </table> </xsl:template> <xsl:template match="HistoryEntry"> <tr> <td> <xsl:value-of select="@Date"/> </td> <td> <xsl:value-of select="@Name"/> </td> <td> <xsl:value-of select="@type"/> </td> <td> <xsl:value-of select="@Description"/> </td> </tr> </xsl:template> </xsl:stylesheet>

7. For the Xsl Transform field, click the Browser button and select the transform file.
8. Check the relevant associations for this Content Item Type in the Associations tree.

Step 2: Add the Custom Content Item Type to one or more Page Types in a Template

1. On the Tools Ribbon tab click the Options button.
2. In the Options editor click on the Custom Templates Page Menu Item.
3. Select the New Topics Template (e.g. the name you gave your custom Template) from the template list and click the Edit  toolbar button.
4. Select the Page Type Page Menu Item.
   
5. Select the Page Type that you want to add the custom Content Item Type to and click the Edit  toolbar button.
6. Insert the following DXMETADATA tag in the Page Type HTML where you would like your Custom Content Item type to appear in the output:

<!--DXMETADATA start type="TaggedComment" source="Item" id="HistoryContent" 
format="%%scrap:name=_COLLAPSIBLE_HEADER,idprefix=historycontent,caption=History%%%%comment%%</div>" -->History<!--DXMETADATA end -->

7. Repeat steps 5 and 6 above for any additional Page Types where you would like the Content Item Type to appear.

Step 3: Select the Custom Template in your Project

Open the Build Profile Editor and on the Templates page choose the custom Template you created above.

Step 4: View Custom Content Item Type Content

Now the custom content item type has been created and a custom Template created and selected in the Build Profile Editor the custom Content Item Type content can be viewed in the Content File editor in the same way as the built in content item types (summary, remarks etc).

The transformed output from this example will look like the following table: