Koha makes extensive use of the HTML::Template Perl module to build the web pages that are presented to the Koha user. There are two good reasons for this:
the look of Koha can be changed by rewriting only the templates, changing nothing in the Perl code itself; and
there is a tool to translate templates, so it is possible to translate Koha to new languages without too much trouble.
Templates are one of the reasons why Koha is so flexible and adaptable, because they allow anyone with a basic knowledge of HTML to change the look and feel of Koha, or even add and remove information from display pages.
To find the templates that are installed with Koha, look in the directories in the path where you installed Koha (often /usr/local/koha on Linux systems) called intranet/htdocs or opac/htdocs for the librarian and OPAC templates respectively. For example, the template for the web page used to add books to a virtual bookshelf is found at /usr/local/koha/opac/htdocs/opac-tmpl/css/en/opac-addbookbybiblionumber.tmpl and looks like this:
<!-- TMPL_INCLUDE Name="popup-top.inc" -->
<div id="mainbloc">
<h1>Add book to bookshelf</h1>
<p><label>Title</label><!-- TMPL_VAR NAME="title" --></p>
<p><label>Author</label><!-- TMPL_VAR NAME="author" --></p>
<h2>Select bookshelf</h2>
<form>
<p><label>Add to virtual shelf</label><!-- TMPL_VAR NAME="CGIbookshelves" --></p>
<h2>or add to a new bookshelf</h2>
<p><input type="text" name="newbookshelf" maxlength=40 size=40>
<input type="hidden" name="biblionumber" value="<!-- TMPL_VAR NAME="biblionumber" -->">
<select name="category">
<option value="1">Private</option>
<option value="2">Public</option>
<option value="3">Free</option>
</select>
</p>
<input type="submit" value="Add to virtual shelf" class="button catalogue">
</form>
<!-- TMPL_INCLUDE Name="popup-bottom.inc" -->When this template is actually used to build a Koha web page, the resulting page source might look something like this:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>popup</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<link rel="stylesheet" type="text/css" href="/opac-tmpl/css/en/includes/opac.css" />
</head>
<body>
<!-- NO MENUS for popup-top -->
<div id="mainbloc">
<h1>Add book to bookshelf</h1>
<p><label>Title</label>The dark tower vii :</p>
<p><label>Author</label>King, Stephen.</p>
<h2>Select bookshelf</h2>
<form>
<p><label>Add to virtual shelf</label><select name="shelfnumber" size="1">
</select></p>
<h2>or add to a new bookshelf</h2>
<p><input type="text" name="newbookshelf" maxlength=40 size=40>
<input type="hidden" name="biblionumber" value="3">
<select name="category">
<option value="1">Private</option>
<option value="2">Public</option>
<option value="3">Free</option>
</select>
</p>
<input type="submit" value="Add to virtual shelf" class="button catalogue">
</form>
</body>
</html>Once you have looked at some of the Koha *.tmpl files, you should read some documentation on HTML::Template to learn how to change them. Three good web sites explaining HTML:: Template are http://www.perldoc.com/perl5.6/lib/HTML/Template.html, http://www.sitepoint.com/article/introducing-html-template, and http://html-template.sourceforge.net/article.html, and there are many other sites as well.
Note that future versions of Koha will move to using standardized prog templates, with the goal of having templates that are simple, are XHTML valid, and can be configured using cascading style sheets. This will require that new templates follow some basic rules:
Templates should always begin with
<!- - TMPL_INCLUDE NAME="doc-head-open.inc" - ->Koha - - TEMPLATE_TITLE
<!- - TMPL_INCLUDE NAME="doc-head-close.inc" - ->
<!- - TMPL_INCLUDE NAME="menus.inc" - ->
<!- - TMPL_INCLUDE NAME="menu-MODULE.inc" - ->where MODULE is one of the Koha modules (catalogue, acquisition, etc.)
Templates should always end with
<!- - TMPL_INCLUDE NAME="intranet-bottom.inc" - ->
Use
<div id="TEMPLATENAME_what_this_block_does"> </div> for each logical block. For example, if a page contains one block for borrower information, one for borrower fines, and one for borrower reserves, it is a good idea to have three different blocks. (Usually a block begins with an <h2> header.)
All action buttons inside a block are enclosed in a
<div id="action"> </div> and placed at the end of the block. Avoid having more than one action div.
Use <h1> for the page main title.
Use <h2> for the block level title.
Construct forms with
<p><label>text</label><input type="..."></p>
NOT with <table>.
Use <table> as seldom as possible (and only where tables are truly useful).
Do not use <caption> at the beginning of tables, at least not for the table title. Since most blocks are not tables, the caption does not exist everywhere. Use <h2> instead.
(Send comments and remarks to <st.hedges AT gmail DOT com>. They will be added to this section.)
Koha's templating system allows you to have a great amount of control over the interface, but it's not always easy to get started. The template files (*.tmpl, *.inc) are used by Perl's H to create the HTML files that are returned to the user.TML::Template
The template files are not straight HTML, which is why applications like Dreamweaver can't handle them. Dreamweaver wants to try to build a dynamic preview of the template file and it can't because the template file contains not only HTML markup but also <!-- TMPL --> tags which control the output.
If you want to get your hands dirty and to some template editing, the best option is to use a text editor. Someone suggested HTML-Kit, which would work fine. It doesn't do syntax-highlighting for .tmpl files by default, but you can tell it to.
To start working, pick one of the current templates to customize (default or npl in the intranet, css or npl in the OPAC), and copy all the files to a new folder. Then go into Koha's system preferences and change your template to the new one. That way you'll still have the originals to fall back on if something breaks.
One confusing thing about a lot of the templates is that one template will handle several different situations depending on what action the user has taken. So the whole structure of the template might be wrapped in conditional tags:
<!-- TMPL_IF NAME="case1" -->
[ some HTML code here ]
<!-- TMPL_ELSE -->
[ some HTML code here ]
<!-- /TMPL_IF -->Use the standard HTML markup on the page to give you clues as to what's going on and where you are in the template, comparing it to what you see on the screen running Koha.