Creating a Template
Getting Started
The Pedias include a good number of templates by default and taking a look at their format will give you an idea of what a template can look like.There are two kinds of templates: 'export templates', used during an export to create an external text representation of the data and 'info view templates' that must be HTML and are used by the info view inside the program to display the information for one entry.
On the most basic level the template system works like this: it starts by reading the specified template and looking for keywords it replaces those with the information from the entry to achieve the final version. All the possible keywords can be found on the tags page.
Info view templates have extra tags that only apply to them but otherwise everything that applies to an export template also applies to an info view template so let's build a sample export template to give you an idea of the process.
Installing an Export Template
To begin our export template from scratch we open one of the existing HTML templates for editing. To do this, use the Export feature in your DVDpedia, choose the HTML tab, select the template you want and press the Edit button. DVDpedia will automatically copy the template into the Templates folder (by default located in ~/Library/Application Support/DVDpedia/Templates) and prefix it with 'My' so that you will know it's a template you edited. For example, if you choose to edit the Silver template, the program will automatically create a template named 'MySilver' for you and show it in the Finder.(Although this sample will use DVDpedia, the template created here will be generic enough that it can be used in any program; wherever you see DVDpedia you can substitute another Pedia's name.)
- For this exercise, we will rename the 'MySilver.html' template to 'MyRating.html' since the finished template won't have much in common with Silver.html.
- Open MyRating.html in your preferred text editor.
- Delete everything from but not including <meta http-equiv="content-type" content="text/html; charset=iso-8859-1"> to </body>
- Add the closing </head> tag and the opening <body> tag after content="text/html; charset=iso-8859-1">
<html>
<head>
<title>[global:collectionName]</title>
<meta http-equiv="content-type" content="text/html; charset=iso-8859-1">
</head>
<body>
</body>
</html>
<head>
<title>[global:collectionName]</title>
<meta http-equiv="content-type" content="text/html; charset=iso-8859-1">
</head>
<body>
</body>
</html>
Our First Keyword
Looking at the above HTML source you will notice we already have our first keyword [global:collectionName] as the title of the HTML page. There are two types of keywords: those that are global to the collection and those that belong only to an entry. The global tags are the following and can be added anywhere in the text.
- [global:collectionName] - The name of the collection.
- [global:sortedBy] - The name of the column the collection is sorted by.
- [global:totalEntries] - Total number of entries in the collection.
- [global:totalNumberOfPages] - Number of pages that will be created by the export.
- [global:dateUpdated] - The current date at the moment of export.
- [global:myEmail] - The "me" addressbook entry email.
- [global:sortedEntry] - Current page separated by a letter or an entire word, depending on the type of export.
- [global:pageNumber] - Current page number.
- [global:previousPageURL] - A URL linking to the next page in the export.
- [global:nextPageURL] - A URL linking to the previous page in the export.
The repeat tags are not optional in an export template.
Info view templates only have one entry, therefore the repeat tag is optional and can be ommited.
Adding the repeat loop tags to the main body of our HTML as well as the keyword for the title ([key:title]) of the entry we have the following template:
Info view templates only have one entry, therefore the repeat tag is optional and can be ommited.
<html>
<head>
<title>[global:collectionName]</title>
<meta http-equiv="content-type" content="text/html; charset=iso-8859-1">
</head>
<body>
<!--BeginRepeat-->
[key:title]<br />
<!--EndRepeat-->
</body>
</html>
Sample Title
<head>
<title>[global:collectionName]</title>
<meta http-equiv="content-type" content="text/html; charset=iso-8859-1">
</head>
<body>
<!--BeginRepeat-->
[key:title]<br />
<!--EndRepeat-->
</body>
</html>
What About a Thousand Words
Adding images to be used by your template is done by referencing them as if they where inside a folder called "Images". Let's add a little red man image after every title on our list. To do so, we add an image tag with a source reference to our image named redman.png, located in the Images folder.
<html>
<head>
<title>[global:collectionName]</title>
<meta http-equiv="content-type" content="text/html; charset=iso-8859-1">
</head>
<body>
<!--BeginRepeat-->
[key:title] <img src="images/redman.png" /> <br />
<!--EndRepeat-->
</body>
</html>
Sample Image
<head>
<title>[global:collectionName]</title>
<meta http-equiv="content-type" content="text/html; charset=iso-8859-1">
</head>
<body>
<!--BeginRepeat-->
[key:title] <img src="images/redman.png" /> <br />
<!--EndRepeat-->
</body>
</html>
- Navigate to the Images folder in ~/Library/Application Support/DVDpedia/Templates/Images.
- Our template is called MyRating.html so we create a new folder and name it "MyRatingImages".
- We copy redman.png into MyRatingImages.
The special tag [key:starRatingURL] points to images you must create and place in the images folder with names star0.gif, star1.gif, star2.gif, star3.gif, star4.gif and star5.gif
The Magic Disappearing Act
All key tags have a corresponding "if" statement that can be used to remove sections of HTML souce code. The format is: <!--IFFieldName to ENDFieldName-->. In our case we are going to use the fact that when the 'Borrowed By' field is filled, it means someone has borrowed the entry and we want to display the little red man followed by the name of the borrower. Adding the if statement to bracket the img tag and adding [key:borrowedBy] does the trick and we have the following template:
<html>
<head>
<title>[global:collectionName]</title>
<meta http-equiv="content-type" content="text/html; charset=iso-8859-1">
</head>
<body>
<!--BeginRepeat-->
[key:title] <!--IFborrowedBy <img src="images/redman.png" /> [key:borrowedBy] ENDborrowedBy--> <br />
<!--EndRepeat-->
</body>
</html>
Sample If Statement
<head>
<title>[global:collectionName]</title>
<meta http-equiv="content-type" content="text/html; charset=iso-8859-1">
</head>
<body>
<!--BeginRepeat-->
[key:title] <!--IFborrowedBy <img src="images/redman.png" /> [key:borrowedBy] ENDborrowedBy--> <br />
<!--EndRepeat-->
</body>
</html>
A Link to the Past
We need to create a link to previous and next pages when an export has more than one page. This is done by creating a regular link and using the global tags [global:nextPageURL] and [global:previousPageURL] inside the href attribute. We add this to the top of the page, outside of the repeat tags as we only want one link per page and not one per entry. The first page should not have a previous link and the last page should not have a next link so we also add the corresponding if comments.
<html>
<head>
<title>[global:collectionName]</title>
<meta http-equiv="content-type" content="text/html; charset=iso-8859-1">
</head>
<body>
<!--IF_PREVIOUS_PAGE <a href="[global:previousPageURL]">Previous</a> END_PREVIOUS_PAGE-->
<!--IF_NEXT_PAGE <a href="[global:nextPageURL]">Next</a> END_NEXT_PAGE--> <br /><br />
<!--BeginRepeat-->
[key:title] <!--IFborrowedBy <img src="images/redman.png" /> [key:borrowedBy] ENDborrowedBy--> <br />
<!--EndRepeat-->
</body>
</html>
Sample Previous
<head>
<title>[global:collectionName]</title>
<meta http-equiv="content-type" content="text/html; charset=iso-8859-1">
</head>
<body>
<!--IF_PREVIOUS_PAGE <a href="[global:previousPageURL]">Previous</a> END_PREVIOUS_PAGE-->
<!--IF_NEXT_PAGE <a href="[global:nextPageURL]">Next</a> END_NEXT_PAGE--> <br /><br />
<!--BeginRepeat-->
[key:title] <!--IFborrowedBy <img src="images/redman.png" /> [key:borrowedBy] ENDborrowedBy--> <br />
<!--EndRepeat-->
</body>
</html>
Is That an Index or Are You Just Happy to See Me?
One of the settings the users can set for an export is to separate the pages alphabetically by first letter of the column the entries are sorted by or separate the pages by entire words. This is useful with genre and other fields that have similar values. Separating by entire word is even useful on the title field as the index will consist of a list of all the movie titles.To add an index to a template select a location in your template and add the following: <!--IFIndex[Divider: | ]ENDIndex-->. The value given to the [Divider:] tag is what will be added between each generated index value, in this case we used |. There is no limitation to the value, it can even be an image.
<html>
<head>
<title>[global:collectionName]</title> <br />
<meta http-equiv="content-type" content="text/html; charset=iso-8859-1">
</head>
<body>
<!--IFIndex[Divider: | ]ENDIndex-->
<!--IF_PREVIOUS_PAGE <a href="[global:previousPageURL]">Previous</a> END_PREVIOUS_PAGE-->
<!--IF_NEXT_PAGE <a href="[global:nextPageURL]">Next</a> END_NEXT_PAGE--> <br /><br />
<!--BeginRepeat-->
[key:title] <!--IFborrowedBy <img src="images/redman.png" /> [key:borrowedBy] ENDborrowedBy--> <br />
<!--EndRepeat-->
</body>
</html>
Sample Index
<head>
<title>[global:collectionName]</title> <br />
<meta http-equiv="content-type" content="text/html; charset=iso-8859-1">
</head>
<body>
<!--IFIndex[Divider: | ]ENDIndex-->
<!--IF_PREVIOUS_PAGE <a href="[global:previousPageURL]">Previous</a> END_PREVIOUS_PAGE-->
<!--IF_NEXT_PAGE <a href="[global:nextPageURL]">Next</a> END_NEXT_PAGE--> <br /><br />
<!--BeginRepeat-->
[key:title] <!--IFborrowedBy <img src="images/redman.png" /> [key:borrowedBy] ENDborrowedBy--> <br />
<!--EndRepeat-->
</body>
</html>
Taking Control
A user has several options when doing an export. Although it is best to leave the options up to the user, there are times when you might want to override them in your template, for example when adding a details page template or certain settings simply make your template look better. To override the set option you have to add meta tags to the header of your HTML template. The possible tags are:
- <meta name="PageSplit" content="SortLetter" />
- <meta name="PageSplit" content="SortName" />
- <meta name="PageSplit" content="[integer]" />
- <meta name="PageBreakAfterEvery" content="[integer]" />
- <meta name="image-export" content="yes" />
- <meta name="image-export" content="no" />
- <meta name="image-width" content="[float]" />
- <meta name="image-height" content="[float]" />
- <meta name="image-compression" content="[float]" />
- <meta name="image-rotation" content="90 or 270 " />
- <meta name="statistics" content="statistics" />
- <meta name="details" content="aTemplate.html" />
- <meta name="includeLocalLinks" content="yes" />
- <meta name="PrintLandscape" content="yes" />
If using the statistics meta tag the statistics page will be called statistics.html so be sure to include a link to this page in your template.
The first three tags define if the page is to be separated alphabetically, by word or by a certain number of entries. To make one single large page, make PageSplit a very large number such as <meta name="PageSplit" content="50000" />. Statistics exports a page with statistical information about the collection. The details command will automatically run a second export with the mentioned template and place it in the details folder. The rest control cover image properties; image-compression takes a float between 0.0 being full compression and 1.0 being no compression.
The details command is normally set for a template that forces one entry per page, so that you can then link to the entries by using the [key:incrementalNumber] in the original template as a link: <a href="details/page[key:incrementalNumber].html">more info</a>
The includeLocalLinks command creates a folder named "Files" and makes a copy of locally linked files to that folder so they can be referenced from the exported template. (Remember that when you use this template you need to include the links part of the template so the links
are shown, something along the lines of:<!--IFlinks
<div class="links">
<ul>
[linksBegin]<li><a href="[link:url]">[link:name]</a></li>
[linksEnd]
</ul>
</div>
ENDlinks-->
For our example template lets add the fact that we don't want cover images exported as we are not using them and they take up space and slow down the export.
<html>
<head>
<title>[global:collectionName]</title> <br />
<meta http-equiv="content-type" content="text/html; charset=iso-8859-1">
<meta name="image-export" content="no" />
</head>
<body>
<!--IFIndex[Divider: | ]ENDIndex-->
<!--IF_PREVIOUS_PAGE <a href="[global:previousPageURL]">Previous</a> END_PREVIOUS_PAGE-->
<!--IF_NEXT_PAGE <a href="[global:nextPageURL]">Next</a> END_NEXT_PAGE--> <br /><br />
<!--BeginRepeat-->
[key:title] <!--IFborrowedBy <img src="images/redman.png" /> [key:borrowedBy] ENDborrowedBy--> <br />
<!--EndRepeat-->
</body>
</html>
<head>
<title>[global:collectionName]</title> <br />
<meta http-equiv="content-type" content="text/html; charset=iso-8859-1">
<meta name="image-export" content="no" />
</head>
<body>
<!--IFIndex[Divider: | ]ENDIndex-->
<!--IF_PREVIOUS_PAGE <a href="[global:previousPageURL]">Previous</a> END_PREVIOUS_PAGE-->
<!--IF_NEXT_PAGE <a href="[global:nextPageURL]">Next</a> END_NEXT_PAGE--> <br /><br />
<!--BeginRepeat-->
[key:title] <!--IFborrowedBy <img src="images/redman.png" /> [key:borrowedBy] ENDborrowedBy--> <br />
<!--EndRepeat-->
</body>
</html>
It's a Small World After All
When adding labels to fields you will be displaying, it is possible to have them translated automatically by the program. Most of the keyword tags for an entry have a corresponding translated keyword that looks like this: [translate:title].
Title: [key:title]
Director: [key:director]
Director: [key:director]
[translate:title]: [key:title]
[translate:director]: [key:director]
[translate:director]: [key:director]
So let's add my rating to our template but not as an image of stars but a number with a label of my rating that is automatically translated.
<html>
<head>
<title>[global:collectionName]</title> <br />
<meta http-equiv="content-type" content="text/html; charset=iso-8859-1">
<meta name="image-export" content="no" />
</head>
<body>
<!--IFIndex[Divider: | ]ENDIndex-->
<!--IF_PREVIOUS_PAGE <a href="[global:previousPageURL]">Previous</a> END_PREVIOUS_PAGE-->
<!--IF_NEXT_PAGE <a href="[global:nextPageURL]">Next</a> END_NEXT_PAGE--> <br /><br />
<!--BeginRepeat-->
[key:title] <!--IFborrowedBy <img src="images/redman.png" /> [key:borrowedBy] ENDborrowedBy-->
- [translate:myRating]: [key:myRating] <br />
<!--EndRepeat-->
</body>
</html>
Sample My Rating
<head>
<title>[global:collectionName]</title> <br />
<meta http-equiv="content-type" content="text/html; charset=iso-8859-1">
<meta name="image-export" content="no" />
</head>
<body>
<!--IFIndex[Divider: | ]ENDIndex-->
<!--IF_PREVIOUS_PAGE <a href="[global:previousPageURL]">Previous</a> END_PREVIOUS_PAGE-->
<!--IF_NEXT_PAGE <a href="[global:nextPageURL]">Next</a> END_NEXT_PAGE--> <br /><br />
<!--BeginRepeat-->
[key:title] <!--IFborrowedBy <img src="images/redman.png" /> [key:borrowedBy] ENDborrowedBy-->
- [translate:myRating]: [key:myRating] <br />
<!--EndRepeat-->
</body>
</html>
Repetition and Alliteration
There are fields that are repetitive. These fields are handled like regular fields but they have their own begin and end repeat tags and the beginning of the keyword is unique. The fields that can repeat are 'Links', 'Similar products', DVDpedia's 'Credits' and CDpedia's 'Tracks'. We'll add 'Similar products' to our template as an example. After every title we will insert a new indented line and add the similar products for that title.After 'My rating' we'll add a similair products loop and separate each similar product with the HTML list tag <li> </li>. We'll add not only the title of the similar product but a link to that product on Amazon as well. Finally we'll add the <!--IFSP tags for the similar products so that if there are no similar products the list tags will not create an empty line. Notice how the <ul> </ul> are outside of the repeat tags but the list item tags are repeated for each similar product.
<html>
<head>
<title>[global:collectionName]</title> <br />
<meta http-equiv="content-type" content="text/html; charset=iso-8859-1">
<meta name="image-export" content="no" />
</head>
<body>
<!--IFIndex[Divider: | ]ENDIndex-->
<!--IF_PREVIOUS_PAGE <a href="[global:previousPageURL]">Previous</a> END_PREVIOUS_PAGE-->
<!--IF_NEXT_PAGE <a href="[global:nextPageURL]">Next</a> END_NEXT_PAGE-->
<br /><br />
<!--BeginRepeat-->
[key:title] <!--IFborrowedBy <img src="images/redman.png" /> [key:borrowedBy] ENDborrowedBy-->
- [translate:myRating]: [key:myRating]
<!--IFSP
<ul>
[similarProductsBegin]<li><a href="[similarProduct:url]">[similarProduct:name]</a></li>[similarProductsEnd]
</ul>
ENDSP-->
<br />
<!--EndRepeat-->
</body>
</html>
We haven't used any CSS in order to keep things simple and concentrate on the functions of the template system; however, we encourage you to use it in your own templates.
What about the info view templates?
The info view templates work the same way as the export templates. They have one extra feature though because they respond to certain links as commands within the program. For example a link to pedia://bruji.com/nextEntry will tell the program to select the next entry and display it in the info view.
- pedia://bruji.com/loadLink= - Loads a link to an external web page.
- pedia://bruji.com/previousEntry - Selects the previous entry.
- pedia://bruji.com/nextEntry - Selects the next entry.
- pedia://bruji.com/setTabView=1 - Sets the main view to cover view.
- pedia://bruji.com/setTabView=0 - Sets the main view to table view.
- pedia://bruji.com/findEntry= - Adds an entry via the search panel.
- pedia://bruji.com/findTitle= - Looks for an entry by title and selects it.
- pedia://bruji.com/perform=returnedClicked - Marks a movie as returned.
- pedia://bruji.com/perform=showLinks - Shows any links connected to the entry.
- pedia://bruji.com/perform=editEntry - Brings up the edit panel.
- pedia://bruji.com/perform=searchForListmania - Searches for possible listmanias the entry belongs to.
- pedia://bruji.com/perform=exportCollection - Brings up the export panel.
- pedia://bruji.com/perform=exportToMac - Brings up the .Mac export panel.
- pedia://bruji.com/perform=exportToIpod - Bring up the iPod export panel.
- pedia://bruji.com/perform=buyAtAmazon - Opens Amazon page to add entry to shopping cart.
- pedia://bruji.com/perform=openAmazon - Opens Amazon entry details page.
- pedia://bruji.com/perform=removeCoverImage - Removes the cover image of the entry.
- pedia://bruji.com/openMovieExternally - Opens any linked movie files.
- pedia://bruji.com/menuPlugin= - Executes any menu plugin by name.
To use an info view, place your template inside the applications resource folder at Contents/Resources/WebViewFiles/en. You can also edit your template directly from this location.
Any images for your template go into the shared image folder Contents/Resources/WebViewFiles/images. To reload your template in the program ctrl-click on the info view and select the template from under the style menu.
If we were to change our example template into an info view, we could replace the URL link of the similar products to Amazon with a command to look them up in the program.
Any images for your template go into the shared image folder Contents/Resources/WebViewFiles/images. To reload your template in the program ctrl-click on the info view and select the template from under the style menu.
<html>
<head>
<title>[global:collectionName]</title> <br />
<meta http-equiv="content-type" content="text/html; charset=iso-8859-1">
<meta name="image-export" content="no" />
</head>
<body>
<!--IFIndex[Divider: | ]ENDIndex-->
<!--IF_PREVIOUS_PAGE <a href="[global:previousPageURL]">Previous</a> END_PREVIOUS_PAGE-->
<!--IF_NEXT_PAGE <a href="[global:nextPageURL]">Next</a> END_NEXT_PAGE-->
<br /><br />
<!--BeginRepeat-->
[key:title] <!--IFborrowedBy <img src="images/redman.png" /> [key:borrowedBy] ENDborrowedBy-->
- [translate:myRating]: [key:myRating]
<!--IFSP
<ul>
[similarProductsBegin]<li><a href="pedia://bruji.com/findEntry=[SP:ASIN]">[similarProduct:name]</a></li>[similarProductsEnd]
</ul>
ENDSP-->
<br />
<!--EndRepeat-->
</body>
</html>
Samples
Since the best way to learn is by example don't forget to take a look at the included templates. Here are a couple of exports done with templates that are already available for the programs.
Included with the program:
- Basic- Simple white template, all entries on one page.
- Covers - Just the covers.
- KuzDVDCSS - A CSS template indexed by director.
- SingleEntryPlus - Indexed by theatrical release.
- SortedIndexWithStats - Indexed by title, with statistics.
- StandardsBased - Very clean template, no index but separated alphabetically.
- KuzDVDCovers - A template with a details page. Download & Install
- ChiaScuDVDCovers - Also covers linking to a details page. Download & Install
Wrapping it up
If you have any questions or suggestions on improving this How-To, don't hesitate to send us an email.
If you would like to work with the MyRating.html template you can download the final version here. Download and install the example MyRating.html template in:
A Mac's best friend.