On this page: Description, Export Formats, Available Exports, ADVANCED: Customizations
Description
Export Data converts selected TMG project data to XML and then either writes an XML file or converts the XML to HTML and writes an HTML file. The specific types of data that can be exported are listed below.
Export Formats
There are two export formats, XML and HTML.
Export Format: XML
If you set the Export Format to XML, the selected data will be exported to an XML file. When the Export Format is XML, and you use the Set stylesheet option, TMG Utility will include a stylesheet directive in the XML file and copy a selected XSLT Stylesheet to the same folder as the XML output file.
When an XML file includes a stylesheet directive, and you open the XML file in a web browser, some browsers will apply the XSLT Stylesheet and show the formatted result.
Export Format: HTML
If you set the Export Format to HTML, the selected data will be converted to XML format but TMG Utility will then apply the selected XSLT Stylesheet to transform the XML to HTML, and the output will be an HTML file. If you are happy with the formatting provided by one of the XSLT Stylesheets supplied with TMG Utility, or if you intend to modify the presentation of the data by editing the HTML, then you may opt to use the HTML Export Format.
Available Exports
The data export choices are as follows.
| Subcommand | Description |
|---|---|
| DNA Log | Exports the contents of the DNA log. TMG Utility also includes an XML data file that describes the standard tests (dna-tests.xml) and merges that XML data with the DNA Log data to produce an XML file that includes both test descriptions and your project data. The XML is designed to reduce the difficulty of making a marker grid in HTML. The Standard Stylesheet (DNA Log-Standard.xsl) included with TMG Utility made the HTML for the marker grid shown below. |
| Exhibit Log | Exports the contents of the Exhibit log, including exhibit names, captions, descriptions, file paths, etc. For exhibits attached to people, the XML includes the person's name and TMG ID. For exhibits attached to events, the XML includes the event type and date, and the list of people attached to the event including principals and witnesses. For external exhibits, the XML includes a file:// URL.For internal text exhibits, the XML includes the exhibit text. |
| Places | Exports places from the Master Place List.
Example XML file
The stylesheet includes an option to add mapping links. If the place data includes latitude and longitude, a "Map" link is added using that information. Otherwise, the name of the place is used as a search term for the mapping service. When the name of a place is used for the map link, there is no guarantee that the mapping service will produce the correct map. The link starts a search, and the search may fail for a variety of reasons, including limitations of the mapping services, incorrect place names, and more. |
| Sentences | Exports sentences from tags in the Master Tag Type List.
Example XML file
You can not use the XML file produced by Export Data with the Import Sentences feature. That feature requires an output file created by the Export Sentences feature. |
| Sources | Exports sources from the Master Source List. |
| Styles | Exports styles from the Master Style List. |
Customization
The remaining 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 | Name | Description |
|---|---|---|
| DNA Log-Standard.xsl | Standard | The default stylesheet for converting the DNA XML file to HTML. |
| DNA Log-Standard.xml | Standard | 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).
