Creating a Template
Contents
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 'details view templates' that must be HTML and are used by the details 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.
Details view templates have extra tags that only apply to them but otherwise everything that applies to an export template also applies to a details 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 Pedia program, we'll use DVDpedia for the example, choose the HTML tab, select the template you want and press the Edit button. DVDpedia will automatically copy the template into the external 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 create a template named 'MySilver' for you and select it in the Finder.- 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. Here's a full list of global tags. They can be added anywhere in the template.
Now let's add some keywords specific to an entry. Because a single page can contain more than one entry there needs to be an indication of what part of the template to repeat for each entry. The tags to indicate what section to repeat are <!--BeginRepeat--> and <!--EndRepeat-->. These tags are HTML comments and will not affect an HTML source but because an export doesn't need to be HTML, these tags are removed during the export and won't appear in the final output.
The repeat tags are mandatory in any export template.
Details view templates only have one entry, therefore the repeat tags are optional and may be ommited.
Details view templates only have one entry, therefore the repeat tags are optional and may 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:
<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>
This template will give us a list of all the titles in the collection. The possible keywords for an entry are listed in the tags page. They can also be found in the Help file that is included with each program.
What About a Thousand Words
Let's add an image after every title on our list now to show how images are added to templates. We start with an image tag with a source reference to our image named redman.png, located in the Images folder.
Image Preview: 
<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 create a new folder and name it "MyRatingImages".
- Copy redman.png into MyRatingImages.
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
Users have 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 that simply make your templates look better. To override the set options you have to add meta tags to the header of your HTML template. For our sample 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]
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]
<!--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]
<!--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. Fields that can repeat are 'Links', DVDpedia's 'Credits' and CDpedia's 'Tracks'. We'll add 'Links' 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 links loop and separate each link with the HTML list tag <li> </li>. We'll add not only the title of the link but the URL for the link as well. Finally we'll add the <!--IFlinks tags for the links so that if there are no links 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 link.
<html>
<head>
<title>[global:collectionName]</title>
<meta http-equiv="content-type" content="text/html; charset=iso-8859-1">
<meta name="image-export" content="no" />
<meta name="includeLocalLinks" content="yes" />
</head>
<body>
<!--IFIndex[Divider: | ]ENDIndex-->
<!--IF_PREVIOUS_PAGE <a href="">Previous</a> END_PREVIOUS_PAGE-->
<!--IF_NEXT_PAGE <a href="">Next</a> END_NEXT_PAGE-->
<!--BeginRepeat-->
[key:title] <!--IFborrowedBy <img src="images/redman.png" /> [key:borrowedBy] ENDborrowedBy-->
- [translate:myRating]: [key:myRating]
<!--IFlinks
[linksBegin]<a href="[link:url]">[link:name]</a>[linksEnd]
ENDlinks-->
<!--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 details view templates?
The details view templates work the same way as the export templates. They have one extra feature 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 details 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 grid view.
- pedia://bruji.com/setTabView=0 - Sets the main view to list 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 an entry 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=exportCollection - Brings up the export panel.
- pedia://bruji.com/perform=exportToMac - Brings up the MobileMe export panel.
- pedia://bruji.com/perform=exportToIpod - Bring up the iPod export panel.
- 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 customize any of the included details view templates, ctrl-click (right-click) the Pedia program's icon and navigate to 'Show package contents/Contents/Resources/InfoTemplates/en. You can also edit your template directly from this location.
Any images for your template go into the shared image folder Contents/Resources/InfoTemplates/Images. To reload your template in the program, ctrl-click the details view and select the template from the Style menu.
Any images for your template go into the shared image folder Contents/Resources/InfoTemplates/Images. To reload your template in the program, ctrl-click the details view and select the template from the Style menu.
Samples
The best way to learn is by example so take a look at the templates included in the programs as well as those listed on the Extras page written by other Pedia users.
Wrapping it up
If you have any questions or suggestions on improving this How-To, don't hesitate to send us an email.