A step-wise guide to creating web themes for Koha.
See ThemeNotes for a range of stuff that will be included here later.
Templates are a means of separating presentation and style from the data. This simplifies the data processing code whilst providing enhanced opportunities to customise the look and feel of the interface. Koha uses HTML::Template to export information from the underlying perl scripts. This information is combined with code contained in the template themselves. This results in the display of an apparently normal web page.
Template files are composed of mostly standard HTML code which is viewed by the end user via a standard Web browser. The template file also contain some special HTML-like tags which allow information passd from the perl scrips to appear as if they were embedded in the HTML template document itself. This is a similar principle (but not the same) employed by Koha Server Side Includes (SSI - includes).
To configure themes (currently) you have to set a variable
At present there are two places for settings:
Gettemplate gets the 'opachtdocs' or 'intranethtdocs' settings in from the koha.conf file (through C4::Context whis is really cool btw) and then looks into the systempreferences table for the 'opaclanguages' and 'opacthemes' settings. These can be space seperated lists in order of preference. the subroutine then goes and looks in the directory for the specified files until it finds one.
In the systempreferences table.
:Name=opacthemes
:Value=theme1 theme2 theme3 …
You have to specify at least one theme.
The name OPACthemes is a little confusing as it a global theme setting (both for opac and for intranet)
In the scripts there should be the lines: :use C4::Output; :my $template = gettemplate(“opac-search.tmpl”, “opac”); The gettemplate subroutine looks for the theme and language settings, looks for a template, loads the template and sets the <themelang> tag for use in all the includes etc. For example: :src=”<TMPL_VAR NAME='themelang'>/images/search-button.gif”
To be continued (more text + links etc)…. Also need to mention advantages/limitations of using .inc file extension compared with .html
NB The includes via ssi are getting replaced by includes via HTML::Template <TMPL_INCLUDE NAME=…>
Cascading Style Sheets (CSS) are the stadards compliant way of separating content from style; In the same way that templates allow data to be separated from web design, CSS' allows web design style to be separated from content!
When combined with Koha templates, Cascading Style Sheets provide significant improvements in performance and standardisation and web design customisation.
To be continued (more text + links etc)…
==== Koha Template File System ====
* CVS FILE SYSTEM - All templates should be found in the koha-tmpl tree of cvs. There are two sub-branches intranet-tmpl and opac-tmpl. Eveything under there should be installed in koha_intra_htdocs and koha_opac_htdocs respectivly.
* WEBSERVER FILE SYTEM - the structure is: <theme>/<lang>/<scriptname>.tmpl
The templates and scripts must have identical names - except all templates should have the tmpl filename extension. Similarly, all variables must be kept globally consistent (both in the perl code and in the templates). NB this is a work in progress - there are currently inconsistencies - both in names of variables and files.
The inncludes and images folders should be placed under the <theme>/<lang>/ directory…..
—-
==== Putting It All Together ====
Say we have a theme called default written in the English en language. When a web visitor enters a search term, the results are processed by the opac-search.pl script.
This script passes the search results to the search-results.tmpl template (see: http://opacdev.katipo.co.nz/cgi-bin/koha/opac-search.pl ).
:The search-results.tmpl template is (in this instance) found in the {{default/en/} theme and language. The full path to this template would then be default_en_search-results.tmpl
:The template file may itself pull contents from other sources - Say that the template calls an include file named cat-top.inc. The path to this file is then:
::default_en_includes_cat-top.inc
:All the images in the templates are prefixed by the HTML::Template tag: <TMPL_VAR NAME=“themelang”>. For example
::src=”<TMPL_VAR NAME='themelang'>/images/search-button.gif”
:This template variable is automatically passed to includes and is automatically loaded into the template by the template loading subroutine…..
The relevant template loading code in opac-search.pl is:
::use C4::Output;
::my $template = gettemplate(“opac-search.tmpl”, “opac”);
The latest information on this should be found at:
::http://koha.org/contribute/templating/
Significant code simplification may be possible though use of Cascading Style Sheets (.css)
For example, when the template is called from a script written something like this:
type_eq_opac
When using .css to supplement templates, I think the following code:
tr_tmpl_if_name_opac_bgcolor
… reduces to….
tr_class_tmpl_var_name_type
… where valid content for the 'type' variable could be 'opac', 'intra', or any other (including boolean… or nothing at all) (NB There is some current inconsistency in use of variables for seach.pl - such as boolean 'opac' compared with string 'type' )
Roger has suggested using a template variable 'type' to switch between the intranet and the opac. This, in my opinion, is a bad idea. I have been trying to remove all the 'type = opac || intra' code from koha. The opac and the intranet should use completely seperate code. all apart from the modules (thus the “opac” in gettemplate(”<tmplatename>.tmpl”, “opac”) ) (Finlay)
Thus, .css significantly reduces template complexity, improves template performance performance (significant file size reduction) and offers all the normal benefits of .css.
Paul Poulain wrote:
“About css, we've decided, a few months ago to separate Templating and CSS'ing koha. 1st we “template”, then it could be possible to rewritte the “default” theme with css and full html4 compliance.” ''
CSS can be included in the templated koha. It just goes into files that are read in through tmpl_include_name_stylesheet tags.
To be continued (last updated 08 Oct 02)