The information on this page is intended for users who want to create an XSLT Stylesheet or modify one of the XSLT Stylesheets supplied with TMG Utility. You do not have to read or understand this information in order to use the Export Data feature.
If you set Export Format to XML, you can process the output file using any tool that modifies XML files. XSLT, mentioned above, is a general-purpose tool for transforming XML from one format to another, and is often used to convert XML to HTML. If you set Export Format to HTML, TMG Utility will transform the XML using the selected XSLT Stylesheet.
When used with TMG Utility's Export Data feature, you might consider XSLT as a general-purpose report writer and data manipulation tool.
If you are familiar with XSLT, you can create an XSLT Stylesheet to suit your specific requirements. The easiest way to get started is to copy and rename one of the XSLT Stylesheets supplied with TMG Utility. Those .xsl files are stored in the XML subfolder of the TMG Utility program folder. If there is a matching .xml file stored in the same folder, you should also copy that and rename it.
XSLT Stylesheet Parameters
The XSLT Stylesheets that are provided with TMG Utility have parameters that can be set by the user when TMG Utility exports the data. After the XML data is created, but before the HTML is created, TMG Utility displays a parameter dialog window where the values can be reviewed and modified.
In order to make the XSLT Stylesheets supplied with TMG Utility more flexible, they include parameters that you can modify to change the format and/or content of the generated page. The <xsl:param> element is part of the XSLT Stylesheet specification and when used as a child of the <xsl:stylesheet> element, parameter values can be set by the program that invokes the stylesheet.
When HTML output is requested, or when XML output is requested and the Set stylesheet option is selected, TMG Utility will load the selected XSLT Stylesheet after creating the XML data. TMG Utility will search the source folder where the XSLT Stylesheet resides, looking for an XML document with the same filename as the XSLT Stylesheet. If such a file is found, TMG Utility loads the XML file and attempts to find parameter definitions in the XML file. Parameter definitions describe the parameters, including prompt text, choices for multiple choice-type parameters, etc. Those parameter properties are not included in the actual stylesheet.
Example XSL and XML Files
| Filename | Description |
|---|---|
| DNA Log-Standard.xsl | The default stylesheet for converting the DNA XML file to HTML. |
| DNA Log-Standard.xml | Optional parameter definitions for DNA Log-Standard.xsl. |
TMG Utility uses the parameter properties to customize the Set Parameter Values dialog window. When the user clicks the [OK] button to close the dialog window, TMG Utility modifies the XSLT Stylesheet according to the values set by the user.
If the XSLT Stylesheet is being used to create an HTML file, the modified version of the stylesheet is used to transform the XML data.
If the modified XSLT Stylesheet is being written to the same output folder as the XML file, the default parameter values in that version of the stylesheet will be set to the values chosen by the user. Any subsequent use of the XSLT Stylesheet, such as opening the XML data in a browser that transforms the XML data using the stylesheet, will use the modified parameter values as part of that processing.
Parameter Properties
TMG Utility supports a small set of parameter properties. An XSLT Stylesheet author sets the following properties.
| Property | Description |
|---|---|
| Name | The parameter name. The name parameter must be a valid XSLT Stylesheet QName, and it must match the parameter name used in the XSLT Stylesheet, or the parameter will be ignored. |
| Type | The parameter type. TMG Utility supports type="choice" and type="text" parameters. choice parameters are used for multiple choice parameters. text parameters are used when the user should input a text value. |
| FullName | The FullName element defines a friendly name for the parameter. The full name is used for the label of the dialog window control associated with the parameter. The fullname can use spaces and other characters that are not valid in the Name attribute. |
| Option | Option elements are used to set the options for multiple choice parameters. |
| Default | A default element is an optional element that sets the default value of a text parameter. |
Example Parameter File
The following XML is the contents of the DNA Log-Standard.xml file at the time this help page was written.
<document>
<parameter type="choice" name="show-person">
<fullname>Show Person</fullname>
<option value="0">Show ID only</option>
<option value="1">Show surname and ID</option>
<option value="2">Show full name and ID</option>
</parameter>
<parameter type="choice" name="show-haplogroup">
<fullname>Show Haplogroup</fullname>
<option value="0">Ignore</option>
<option value="1">Show on left</option>
<option value="2">Show on right</option>
</parameter>
<parameter type="choice" name="show-comments">
<fullname>Show Comments</fullname>
<option value="0">Ignore</option>
<option value="1">Show on left</option>
<option value="2">Show on right</option>
</parameter>
</document>
There are three choice parameters, "show-person", "show-haplogroup", and "show-comments". There are three choices for each. The value attribute determines the value that will be passed to the XSLT Stylesheet if the user selects the pull-down menu entry with the corresponding text. For example, the XSLT parameter will be set to "2" if the users chooses "Show on right" for the "show-comments" parameter.
The corresponding xsl:param elements from the XSLT Stylesheet are as follows.
<xsl:param name="show-person">0</xsl:param> <xsl:param name="show-haplogroup">1</xsl:param> <xsl:param name="show-comments">2</xsl:param>
Note that the values defined in the XSLT Stylesheet (0, 1, and 2, respectively) are default values. Those values are reset via the Set Parameter Values dialog window. Also, please note that the parameter facility in TMG Utility only works with xsl:param elements where the value is specified between the start and end tag, as shown above. You can not use the xsl:param variation with a select="..." attribute.
At time of this writing, none of the XSLT Stylesheets supplied with TMG Utility use a text parameter. The following XML is a made-up example.
<document>
<parameter type="text" name="page-title">
<fullname>Page Title</fullname>
<default>My Export Page</default>
</parameter>
</document>
The corresponding xsl:param element would be as follows.
<xsl:param name="page-title">The Export Page</xsl:param>
"The Export Page" will be replaced by the value of the <default> element of the parameter definition or the value keyed by the user. For this reason, the <default> element value usually matches the stylesheet's <xsl:param> value.
If there is an error in a parameter definition, TMG Utility will ignore the parameter and proceed. If a parameter is missing from the dialog window, double-check the parameter definition(s).