Document! X and HelpStudio 2019
Customization / Transforming Content Item Type Content
In This Topic
    Transforming Content Item Type Content
    In This Topic

    Document! X and HelpStudio 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.

    Using XSL transforms for custom content item type content is supported for XML source comments and Transact SQL comments only.

    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.

    XML
    Copy Code
    /// <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>

     

    SQL
    Copy Code
    -- ##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

    You will need to create a custom template in which you can then edit one or more of the Page Types. You can find more information on creating custom templates here: Template Fundamentals
    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 -->
    
    1. Repeat steps 5 and 6 above for any additional Page Types where you would like the Content Item Type to appear.

    Be sure to only include the section on Page Types that correspond to the Item Types you selected when you created the Custom Content Item Type in "Step 1: Create a Custom Content Item Type" above.

    The id value of the DXMETADATA element must match the name of the custom Content Item Type, in this example we are using "HistoryContent".

    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).

    You will need to close and re-open any Content Files that were open when this content item type was created.

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

    Date Name Type Description
    1/1/2011 Author 1 New Created
    1/5/2011 Author 2 Fix Edited content