Template Tutorial: how to create your own Templates?
Introduction
XSL is a scripting language that can be used to generate HTML from data in XML form. The Collectorz.com programs use XSL templates to show, export and print items. To do this, the programs first create temporary XML documents containing the data for the selected item(s), then use XSL scripts to generate the HTML page(s).
When the program starts it scans the Templates subfolder for available *.CTI files (Collectorz.com Template Info files). These CTI files contain information about the templates (description, template type, item type, etc..). After that the templates show up in the appropriate template selection lists in the program, depending on the template and item types defined in the CTI files. See below for more info about the CTI file format.
Creating your own XSL templates
If you want to create your own XSL template, we recommend you start by creating a copy of one of the included templates created by us. Even if you only want to make a small change to one of the included templates, ALWAYS create a copy first, using a different filename (if you reinstall or update the program the included templates are overwritten by the installer!!). Make sure you create copies of all related files (CTI, XSL and CSS files), also remember to update the filename field in the CTI file accordingly (see below for more info about the CTI file format).
Collectorz.com XML format
The XML format used by the Collectorz.com programs consists of two sections, the meta data and the collection data.
The metadata part contains information about the field names used in the program. This information can be used to make your template show the user's own field names automatically. Take a look at the included templates to see how this is done.
The collection data in the XML reflects the database structure of the program. Here's a good way to get an idea of the XML schema that is used:
- Take one item in your collection and fill in ALL fields
- Select that item in the main screen
- Right click the Details View and select "Save As XML"
- Now open the resulting .xml file in your browser
CTI format
A CTI file is a Collectorz.com Template Info file. It contains meta information about an XSL template. It is in XML format and contains the following fields:
- product: Product that can use this template. Possible values: Music, Movie, MP3, Book, Comic
- description: Template description, this text shows up in the template selection lists.
- filename: Filename of the template file. Note that a possible CSS file should have the same name.
- template_type: This determines how this template can be used and in which places in the program it will show up. Possible values:
- view: template for Details View in main screen
- print: template that defines a report for Printing
- exportindex: template for HTML index page (list page)
- exportdetails: template for HTML details page
- item_type: This determines the item type for which the template can be used (e.g. Album or Track). This only applies to export and print templates. The item_type values makes sure track templates only show up when printing/exporting track lists. Possible values:
- 2: Main item list (= Music Album, Movie, MP3 Track, Book or Comic book)
- 3: Track list (for Music Collector), MP3 File list (for MP3 Collector)
- 5: MP3 Playlist (for MP3 Collector only)
- supports_thumnails: Indicates if the template uses the thumbnails that the program creates. For export templates only. Possible values: "yes", "no"
- supports_images: Indicates if the template uses the large cover images. For export templates only. Possible values: "yes", "no"
Using CSS files (Cascaded Style Sheets)
All included XSL templates use CSS files for a number of classes that are used to define the look of several elements in the HTML pages, e.g. font styles, font sizes, font colors, background colors, etc...
This system makes it easy to adapt the look of an existing template without having to edit the .XSL file. Editing .CSS files is much easier, especially if you use a tool like TopStyle (http://www.bradsoft.com/).
If you create your own templates, we recommend you use CSS style sheets too.
Hints and Tips
Row shading in lists
Row shading can be done by using an alternative style for each second row in a table:
First, include a "shading" style in your CSS file, like this:
.shading { background-color: #F4F4F4; }
(the included print_item_list.css file already contains this style)
Then, in your XSL template, make all "even" rows use this style, by setting the class attribute of the TR tag, like this:
<xsl:if test="position() mod 2 = 0"><xsl:attribute name="class">shading</xsl:attribute></xsl:if>
(the included print_item_list.xls file (or print_item_listpop.xls) already contains this line)
Hiding repeating values in lists
Hiding repeating values is done by using XSL code to compare a data value with the value of the preceding item in the list. So, before outputting a value, include code like in the following example (which hides a repeating Artist value in Music Collector):
<xsl:if test="artists != preceding-sibling::music[1]/artists">
Of course, after outputting the field value, close the xsl if statement with:
</xsl:if>
Take a look at the print_item_list.xls (or print_item_listpop.xls) file for an example of this.
Important: Hiding repeating values in specific fields is only meaningful if you are hiding fields AND sorting "from left to right", e.g. sorting on the first and second column AND hiding repeating values in the first and second column. Hiding repeating values in unsorted fields is meaningless.
Hiding/Showing the table border
To show or hide a border in tables, simply replace the <table> tag in the main part of the template by <table border="1"> (show border) or <table border="0"> (hide border).
Clickable images (Details View only)
To make images other than the front- and back cover clickable so they open full-size in a separate window, add <a href="image.html">...</a> around the <img> tag. This only has an effect for view templates, not for print or export templates.