Building templates

[ Back to top ]

Preamble
iStrip uses a template system so you can easily change the look of the pages it generates without having to rewrite any of the PHP code. The template system used is Smarty, and it allows some very powerful template design features. This document aims to cover what you need to know about creating your own templates. The Smarty template engine is fully documented on the Smarty website so if you're in need of additional information then try the online Smarty documentation.

[ Back to top ]

Template design basics
An iStrip theme consists of a directory containing one or more template files. All themes must provide at least an index.tpl file. Themes are covered in more detail in the documentation on themes.

An iStrip template is a HTML file containing some special markup that allows iStrip to insert information into the HTML at the desired point called template variables, process arrays of template variables, include other files, hide certain parts of the HTML under certain circumstances and perform other useful functions. By default the characters used to delimit this special template markup are the curly brace characters, {}. Template variables and arrays always begin with the $ symbol, while calls to Smarty functions do not. For example, {$allowed_html} is a variable, while {truncate} is a function call. Template files have a .tpl extension by default.

It is recommended that you look at the text of the supplied template files for more insight into the layout of an iStrip template. You can gain some useful information from these templates.

[ Back to top ]

Templates and Dreamweaver
As has already been stated, iStrip templates are basically HTML files with some extra embedded template markup for accessing iStrip functions. They can be opened and edited in any text editor or HTML editor. Some products, such as Dreamweaver from Macromedia can be configured to allow you to edit TPL files as if they were HTML files. This section details how to configure Dreamweaver MX to read template files and treat them as HTML. Additional information on Smarty and Dreamweaver can be found at http://smarty.incutio.com/?page=ConfiguringDreamweaver

In order to effectively use TPL files from within Dreamweaver, there are 3 main stages in configuration that should be taken:
  1. Add TPL files to Dreamweaver's document types
  2. Configure Dreamweaver to make itself the default editor for TPL files
  3. Associate TPL files from Dreamweaver
The first stage is the most complex as it requires some manual editing of Dreamweaver's MMDocumentTypes.xml file to include TPL files. To do this, use the following procedure:
  1. Locate the MMDocumentTypes file. If you have installed Dreamweaver in the default location it should be located in C:\Program Files\Macromedia\Dreamweaver MX\Configuration\DocumentTypes\MMDocumentTypes.xml
  2. Open this file with a text editor such as Notepad. DO NOT OPEN IT WITH DREAMWEAVER! By default XML files are associated with Dreamweaver, but if you use Dreamweaver to edit its own configuration files there is no telling what may happen.
  3. Locate the following line:

    <documenttype id="HTML" internaltype="HTML" winfileextension="htm,html,shtml,shtm,stm,lasso,xhtml" macfileextension="html,htm,shtml,shtm,lasso,xhtml" file="Default.html" writebyteordermark="false">

    It should be located near the top of the file.
  4. Replace this line with the following one:

    <documenttype id="HTML" internaltype="HTML" winfileextension="htm,html,shtml,shtm,stm,lasso,xhtml,tpl" macfileextension="html,htm,shtml,shtm,lasso,xhtml,tpl" file="Default.html" writebyteordermark="false">
  5. Save the changes and exit. Dreamweaver will now treat TPL files as HTML
Dreamweaver will now recognise TPL files as HTML and display them as such, but it will not yet load them. If you attempt to open one you will get an error stating that there is no editor associated with this type of file. To fix this, use the following procedure:
  1. Start Dreamweaver. From the "Edit" menu select "Preferences.."
  2. A window will open with a list of different aspects of Dreamweaver's configuration down the left and controls on the right. From the list on the left, select "File types/Editors"
  3. In this section there are 2 more lists. One labeled "Extensions" on the left and one labeled"Editor" on the right. Above each there are 2 buttons, a plus sign and a minus sign. Click the plus button over the Extensions list. A new entry will appear at the bottom of the Extensions list. Type ".tpl" into this space and press enter
  4. Select the new ".tpl" extension in the Extensions list. The Editors list should now be empty. Click the plus sign above the Editors list. A file browser will appear. Use this file browser to go to the directory where Dreamweaver is installed and select "dreamweaver.exe" as the default editor for .tpl files
  5. Click OK to save the changes to the settings.
If you want Dreamweaver to be the default application launched when you double click on a TPL files from within Windows then you need to associate TPL files with Dreamweaver from within Windows. The precise action you will need to take will vary depending on the version of Windows you are using. For this reason a detailed procedure for doing this has not been given. Consult your Windows manual/online help for details on how to associate a file type with an application.

[ Back to top ]

Template variables
In order to display the contents of a given template variable in a template, you give the name of the variable prepended with a $ symbol surrounded by curly braces. For example, ($SCRIPT_NAME) will give you the name of the PHP script that is using the template file.

Most of the variables are provided in groups. These variables are accessed by giving the group name followed by the variable name, separated by the dot character. For example ($strip.id) will return the number of the current strip, {$archive.days_ago_first} will return the number of days that have elapsed since the first strip was uploaded, etc.

For a full list of template variables and groups, see the documentation on template variables.

[ Back to top ]

Array variables
Some variable groups, such as the $striplist group, are in fact indexed arrays. Each index can contain a value, as is the case with the $themes group, or it can contain a subgroup of variables, as is the case with the $striplist group. To access index values in the case where each index is a value, you use the group name followed by the index entry you want in square braces. For example, {$themes[0]} will return the name of the first theme iStrip can find in the themes directory. In the case where each index is a subgroup of values, you use the group name, followed by the index you want in square braces, followed by the name of the member of the subgroup you want. For example, {$striplist[0].strip_title} will return the title of strip number 1.

NOTE: In the case of the $striplist group, the index value is not the strip ID. It is, in fact, the strip ID minus one. So strip 1 is index 0, strip 2 is index 1, etc. This is because Smarty expects arrays to always be zero-indexed. If the array was one-indexed with index 1 being strip 1, many of the Smarty functions used for looping through arrays would cut off the final entry off. In order to avoid confusion, each $striplist group includes an id member with the real index number. For example. {$striplist[0].id} will return 1.

Fortunately, it is not intended that you explicitly access the group index like that so the fact that strip 1 is at index 0 should normally not be an issue. Functions such as section and foreach are provided for traversing indexed groups.

Example:

{section name=row loop=$strip}
   Strip {$strip[row].id} title is: {$strip[row].strip_title}<br />
{sectionelse}
   There are no strips in the strip index
{/section}

This will generate a list of strip IDs and their respective titles. The sectionelse section will be displayed if there are no strips in the index. For more information on section and sectionelse, see the section on conditionals.

[ Back to top ]

Conditionals
The Smarty engine contains methods to allow you to display different output depending on the state of template variables. The simplest method of doing this is to use the default function. This will let you set some text to display if the template variable you specify contains no value. To use default, you give the name of a template variable you want to display and follow it with |default:'Default text to display' in the curly braces. For example, {$strip.title|default:'This strip has no title'} will either show the specified strip title, or the string supplied between the quotation marks if no title was set

Section also provides conditional functionality. If you specify an array in section that contains no values then you can use the {sectionelse} tag to provide a default string to display. You can see an example of this in the section on array variables.

Another conditional block provided by Smarty is the if block. This block takes the form {if condition}Text to display{/if} in it's most basic form. The if block also supports elseif and else to allow you to check for several different conditions.

Example:

This strip was uploaded
{if $strip.days_ago == 0}
   today
{elseif $strip.days_ago == 1}
   yesterday
{else}
   {$strip.days_ago} days ago
{/if}

This will display how many days have elapsed since the strip being viewed was uploaded unless it was uploaded 0 days ago, in which case it will display "today", or if it was uploaded 1 day ago, in which case it will display "yesterday".

Another way to use if is to check if a variable has been set. For example {if $striplist}The strip index contains entries{else}There are no strips in the strip index{/if} will display the first message if $striplist contains any value, without being concerned over what value it contains. If $striplist contains no value at all then the second message.

The if block supports many different ways of checking and comparing variables, they are detailed more fully in the Smarty documentation on if.

[ Back to top ]

Other useful template features
In order to prevent spiders harvesting your email address off your comic website, Smarty provides a mailto function that will allow you to put an email address on your page but obfuscate it in such a way as to prevent spiders from being able to read it. For example, {mailto address='foo@bar.com' text='click here to send mail' encode='javascript'} will generate a javascript link through which people can mail you. Your address will be encoded into a meaningless string that mail address harvesters cannot read. If you don't wish to use javascript encoding then there is also a hex mode provided that can by used by setting encode to 'hex'. This method also attempts to scramble your email address but doesn't depend on javascript. This method will usually defeat mail harvesters, but some will be able to decode your address.

If you wish to include other PHP scripts in your templates then you can use the include_php function. For example, {include_php file='foo.php'} will call foo.php and display it's output at the point in the template where the include_php tag was written. You can also assign the output to a variable instead of displaying it if you wish. NOTE: paths will be relative to the iStrip script that is currently in use, not the template file

Alternatively, you can include PHP code directly into your templates with the php function. For example {php}echo ('hello world');{/php}

There are many other useful functions provided by the Smarty engine but I will not go into more detail here. For more information, see the Smarty documentation.

[ Back to top ]

Using additional pages
The chances are that you will want to have pages other than just the index page available to visitors to your site. You could achieve this by using extra HTML pages to add the extra pages you want. However, iStrip offers a better solution. All themes contain an index.tpl file that describes the layout of your site's front page, but in addition to this page iStrip supports other pages as well. You can have any number of additional pages, named whatever you want, as long as they are all included in your theme directory along with index.tpl. The index.php script can be directed to load pages other than index.tpl by specifying the page to view in the URL. Any page loaded throught index.php will have access to all the features and variables that iStrip makes available. You can use this for all kinds of things, for example the archive page provided in the minimalist theme is an example of an additional iStrip template page. You could also use it to put the strip image and news item on different pages, to provide printer-friendly versions of your pages, or to use items such as banners and jumpboxes on all pages

By default the index.php script will load the index.tpl file from your theme directory, but it can also be made to load a different file by passing a parameter via the URL used to access your site. Say, for example, you create an additional page for an archive list and call it archive.tpl. If the normal address for your site is http://www.foo.bar/index.php then you can view the archive.tpl by using http://www.foo.bar/index.php?view=archive

But strip IDs are also passed to index.php this way. So what do you do if you need to pass both a page to view and a strip ID to the script? You can pass both attributes and seperate them from each other in the URL with the & character. For example, if you have a comic.tpl page and want to view the third strip on it, then you would use http://www.foo.bar/index.php?view=comic&strip_id=3 to load the comic page and display strip 3.

For a page to be viewable like this it has to meet a few requirements. Firstly, the filename must end in .tpl to be recognised. This is to prevent images, css stylesheets or subdirectories from being parsed by accident. Secondly, it must be placed in the same directory as your index.tpl file. If it is in a subdirectory or a different directory from your index template then iStrip will not be able to find it.

Versions of iStrip prior to 1.5.0 used a script called viewpage.php to allow additional pages to make use of template variables. As of iStrip 1.5.0 this functionality has been added to index.php, making the viewpage.php script obsolete.

[ Back to top ]

Admin template editing notes
The admin pages are also generated using Smarty. However, only 1 set of pages is provided and there is no easy method for switching between different page designs provided. This is intentional as you are not meant to change the admin pages. I have documented what template variables are available on the admin pages for the sake of completeness, but you are not expected to modify the admin templates in any way. In fact you are strongly discouraged from doing so as you may prevent iStrip from functioning properly if you make a mistake and you may even lose data. If you choose to edit the admin templates, you do so at your own risk!

[ Back to top ]

Template Hints and Tips
  1. It's just HTML! Don't be intimidated by the prospect of creating template files, they are really just HTML files with some extra markup included. If you know HTML then you can pick up templates very quickly. You can edit them in any text editor, and most HTML editors should either load them or can be tweaked to do so. There are instructions included on how to tweak Dreamweaver to load TPL files in this very document.
  2. Sort your layout out before worrying about the mechanics. A good way to design a template is to just create a plain HTML page first so you can sort out the design issues there, then add in the Smarty markup to get it working. For example, you can first do your design by creating a table cell to hold your strip image, sort out its colour, size and properties as you would with any other HTML document, then finally add the iStrip code to display the strip. The mechanics of the system mean that you can achieve in template code anything you can in plain HTML, so try not to worry about the mechanics until you have a layout you like.
  3. You don't have to use a given variable just because you can! In order to give you the ability to design your site as you see fit I have provided an extensive range of template variables for you to use. However, just because they're available doesn't mean you absolutely have to use them. For example, suppose you don't want to use the news posting features of iStrip. Would there be any point including the $news variable group in your index.tpl file if there's never going to be any news posted?
  4. You don't have to put template variables in any particular order. You don't have to have the strip first with the news below it if you don't want to. You could put them side by side in a table or you could put the news first with the strip afterwards. It's up to you where things go.
  5. Don't use the navigation images I included with the templates. I just picked a set of image files to demonstrate in the template code how to use the $nav variable set with images. There's nothing stopping you from creating images that match your own site better and in fact you are strongly encouraged to do so, espicially if you are going to be using a dark colour for your background. The link images I included are antialiased to work best against light backgrounds.
  6. Make use of the extra page support. The index.php script can support multiple pages and allow these pages access to iStrip's set of template variables. Take advantage of this, it will make for a much better site. For example, the dropdown that allows users to quickly jump to a strip could be included on any page of your site. You don't have to use this of course, you can make all your other pages basic HTML pages that aren't dynamic, but this wouldn't really be making the most of the features iStrip offers, so I would advise that you make good use of it.
  7. You can make a default value appear for variables that aren't set. This feature is used extensivly throughout the provided templates. You can use this for all kinds of things, for example you could get a default title to appear if you don't set a title for your strips.

[ Back to top ]

Copyright © 2002, 2003 Gordon McVey