Template Toolkit

[ Back to top ]

Preamble
From version 1.3.1 a toolkit of template code has been included with iStrip. This toolkit components can be found in the components/ directory and contains code for you to use when constructing your own site template files. You don't have to use the supplied code as is, in fact you are encouraged to modify and taylor it as you see fit in order to make it fit the needs of your site, and some of the supplied code will not work without modification. However, it should give you a great deal of insight into how to create your own templates. The code can be included in your own templates at design time or at compile time.

[ Back to top ]

Using toolkit components
The template toolkit code can be included in your own templates in one of two ways, at design time via cut and paste or at compile time via inclusion by Smarty. The former has speed advantages, the latter makes it easier to reuse the same template components in different places and to update the toolkit code.

The procedures listed below assume you have already read the documentation on templates and themes.

To cut and paste the code into your own templates you should follow these steps:
  1. Open the code fragment you wish to use in the text editor of your choice, along with your template file
  2. Copy the code fragment to the clipboard
  3. Paste it into your template file at the appropriate places
  4. Some of the toolkit code will require that you make changes before you can use it. Any changes you need to make are commented in the toolkit code. For example, to use the email code you will need to change "foo@bar.baz" to your own email address
  5. Save your template file
The Smarty include method is more flexible but is a little more difficult to use and will impose some extra overhead on your server when people view your site. If you intend to use the Smarty include method then you should follow these steps:
  1. Create a subdirectory in" smarty_templates/yourtheme", where yourtheme is the name of your customized theme directory. For the sake of this example I will use "smarty_templates/yourtheme/components".
  2. Copy the toolkit code you wish to use from the archive to the subdirectory you just created
  3. Edit the toolkit code as appropriate for your needs. Some of the toolkit code will require that you make changes before you can use it. Any changes you need to make are commented in the toolkit code. For example, to use the email code you will need to change "foo@bar.baz" to your own email address
  4. Open the template files in smarty_templates/yourtheme that you wish to include toolkit code in. At the point you wish to include a piece of toolbox code insert the following piece of code:

    {include file=components/toolkit_item.tpl'}

    where toolkit_item.tpl is the name of the toolkit file you wish to use. For example, to include the code that displays a banner, use components/img_banner.tpl
  5. Save your template file

[ Back to top ]

Toolkit component overview
This section documents the individual toolkit components

[ Back to top ]

img_banner.tpl
The iStrip software supports randomised banners. That is, if you choose to, you can design several advertising images for your site and place them in a subdirectory on your server. When somebody visits your site iStrip will select one of these images at random and display it where you specify on the page. The img_banner component contains the template code needed to achieve this. See the Offline website for a live demonstration

This component can be used as-is without any modifications. However, it is advisable that you specify an alt attribute for the image tag. Also, if your banners are all the same size then it is also recommended that you specify width and height attributes as well. If you intend to use just a single banner image instead of randomised banners then you should just use an <img> tag in your templates instead as this is going to be more efficient than using the random banner code with a single banner.

[ Back to top ]

img_strip.tpl
The img_strip component contains the code necessary to display the strip image that the visitor has requested to see. As visitors browse through the archive of strips on the server the strip for a given date will be displayed at the point where you place this component in your template.

This component can be used as-is without any modification. As it depends on the $strip template variable, it can only be used on the index page.

[ Back to top ]

nav_archive_flat.tpl
This component displays a <ul> formatted list of all the comics in the iStrip archive. This is very useful if you wish to have an archive page that displays a list of all comics you have posted to your site

This component can be used as-is without any modification. However, you may wish to customize the fields that are displayed to the visitor by editing it.

[ Back to top ]

nav_archive_yearnest.tpl
This component is similar to the nav_archive_flat.tpl component, except it provides a more formatted list. The strip list is subdivided into blocks that contain all the strips uploaded in a given year. This results in a more readable list. See the Offline archive page for a live demonstration.

This component can be used as-is without any modification. However, you may wish to customize the fields that are displayed to the visitor by editing it.

[ Back to top ]

nav_email_gfx.tpl
This component displays a graphical link via which visitors to your website can send you e-mail. This works better than just using a mailto: link as the component makes use of Smarty to obfuscate your email address and give you some protection from email address harvesting robots and spiders.

This component cannot be used as-is, you are required to make some modifications to it. Before you can use it, you need to specify your email address. To do this, replace the placeholder address of "foo@bar.baz" with your real email address. You will also have to specify an image file to use for the image link. To do this, replace the placeholder image filename "foo.gif" with the filename of the image you wish to use.

[ Back to top ]

nav_email_txt.tpl
This component displays a textual link via which visitors to your website can send you e-mail. This works better than just using a mailto: link as the component makes use of Smarty to obfuscate your email address and give you some protection from email address harvesting robots and spiders.

This component cannot be used as-is, you are required to make some modifications to it. Before you can use it, you need to specify your email address. To do this, replace the placeholder address of "foo@bar.baz" with your real email address. You might also wish to edit the email text link to something better suited to your site. To do this, change the text in the component that reads "Send me an e-mail" to whatever you want it to read instead.

[ Back to top ]

nav_google.tpl
This component provides an interface to the Google search engine, allowing users to search either the web or just on the domain of your comic website. This component is designed to work with the free Google web search with site search service only. For other more advanced Google services you will need to set up the appropriate account with Google and implement your own code.You also need to abide by Google's terms of service if you intend to use this feature.

NOTE: The search options require that your site has already been indexed by Google before it will function. Google will crawl for sites with a spider called Googlebot, but for new sites it can take a while before the Googlebot finds them and indexes them. You can submit your site URL to Googlebot and it will be added to the list of sites to be indexed, but it can still take anything up to a few months before your site is actually indexed.

This component cannot be used as-is, you are required to make some modifications to it. There are two form fields in the component that have been given a placeholder value of "www.foo.bar". You will need to replace these placeholders with the domain of your website. Note, you should omit the leading "http://" and that you cannot specify subdirectories or files, just the domain name. For example, "www.foo.bar" is an acceptable value for these fields, but "http://www.foo.bar/" is not, nor is "www.foo.bar/index.php". These aren't restrictions of iStrip, but of the free Google service.

[ Back to top ]

nav_links_gfx.tpl
This component provides a set of graphical links for browsing through the comic archive, with links to the first, previous, next and latest comics. As it depends on the $nav template variables it can only be used on the index page of your site.

This component cannot be used as-is, you are required to make some modifications to it. For each image you need to specify an image URL. To do this, replace the placeholders "inactive_first", "active_first", inactive_prev", etc with URLs to images on your server. You should also specify width and height attributes for all the images in question.

[ Back to top ]

nav_links_txt.tpl
This component provides a set of textual links for browsing through the comic archive, with links to the first, previous, next and latest comics, in addition to a random comic display option. As it depends on the $nav template variables it can only be used on the index page of your site.

This component can be used as is without any modification. However, you might want to change the text of the links to whatever suits your site.

[ Back to top ]

nav_pickstrip_flat_form.tpl
This component displays a drop down list of comics in the archive along with a button. A visitor can jump to any comic in the archive he wishes by picking one from the list and then clicking the button. This kind of menu is javascript-free and therefore useful for designers who wish to avoid javascript on their sites.

This component can be used as is without any modification. However, you are free to change it as you see fit, for example you can change the fields that are displayed for each strip.

[ Back to top ]

nav_pickstrip_flat_js.tpl
This component displays a drop down list of comics in the archive. A visitor can jump to any comic in the archive he wishes by picking one from the list. The requested strip will be displayed as soon as an item on the list is selected with no need for further visitor interaction as with the form version of the dropdown.

NOTE: This menu assumes that the javascript code for changing the strip has been installed on the server. It should be located in the include/javascript directory of the iStrip distribution. If this script is missing the menu will not function.

This component can be used as is without any modification. However, you are free to change it as you see fit, for example you can change the fields that are displayed for each strip.

[ Back to top ]

nav_pickstrip_yearnest_form.tpl
This component displays a drop down list of comics in the archive along with a button. A visitor can jump to any comic in the archive he wishes by picking one from the list and then clicking the button. This kind of menu is javascript-free and therefore useful for designers who wish to avoid javascript on their sites.This component differs from the flat version in that the list of strips is also subdivided by year.

This component can be used as is without any modification. However, you are free to change it as you see fit, for example you can change the fields that are displayed for each strip.

[ Back to top ]

nav_pickstrip_yearnest_js.tpl
This component displays a drop down list of comics in the archive, similar to the one generated by nav_pickstrip_flat_js.tpl. A visitor can jump to any comic in the archive he wishes by picking one from the list. The requested strip will be displayed as soon as an item on the list is selected with no need for further visitor interaction as with the form version of the dropdown. This component differs from the flat version in that the list of strips is also subdivided by year.

NOTE: This menu assumes that the javascript code for changing the strip has been installed on the server. It should be located in the include/javascript directory of the iStrip distribution. If this script is missing the menu will not function.

This component can be used as is without any modification. However, you are free to change it as you see fit, for example you can change the fields that are displayed for each strip.

[ Back to top ]

txt_date_news.tpl
This component displays the date on which the currently displayed news item was posted. It also displays a count of the number of days that have elapsed since then, or the text "Today" or "yesterday" if the number of elapsed days is 0 or 1 respectively. As this component makes use of the $news template variables, it only works on the index page.

This component can be used as is without any modification. However, you are free to modify it as you see fit to meet the needs of your site.

[ Back to top ]

txt_date_strip.tpl
This component displays the date on which the currently displayed strip was posted. It also displays a count of the number of days that have elapsed since then, or the text "Today" or "yesterday" if the number of elapsed days is 0 or 1 respectively. As this component makes use of the $strip template variables, it only works on the index page.

This component can be used as is without any modification. However, you are free to modify it as you see fit to meet the needs of your site.

[ Back to top ]

txt_newsitem.tpl
This component displays a news item, along with a title if a title has been specified. If no news items have been posted then some default text will be displayed instead. As this component makes use of the $news template variables, it only works on the index page.

This component can be used as is without any modification. However, you are free to modify it as you see fit to meet the needs of your site.

[ Back to top ]

Copyright © 2002, 2003 Gordon McVey