Main Koha release repository
https://koha-community.org
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
190 lines
6.6 KiB
190 lines
6.6 KiB
This is a README file for all interested in the templating system used
|
|
by Koha. It contains guidelines ans descriptions, please feel free to
|
|
make comments and contributions to this file.
|
|
|
|
1. Introduction
|
|
|
|
The advantage of a templating system is the separation of code and
|
|
design. It is much easier to read the HTML and get an imagination of
|
|
what it will look like without having it shattered by declarations and
|
|
functions. And it is also nicer being able to alter some functions
|
|
without worrying about the web design.
|
|
|
|
On the other hand, templating stands in contradiction on scripting the
|
|
procedural way; it forces object-oriented programming.
|
|
|
|
With templates Koha can be made fully skinnable: we speak of themes,
|
|
and can support different languages.
|
|
|
|
2. How does it work
|
|
|
|
The short version: Instead of printing HTML from your script, you only
|
|
define some template parameters.
|
|
|
|
You design your HTML page without code in it, and where you need to
|
|
insert data generated by the script. You can pass this data from the
|
|
template parameters via special tags.
|
|
|
|
Indeed, there is a little more to know.
|
|
|
|
I recomend reading the documentation to the HTML::Template module.
|
|
You can obtain it from http://www.perldoc.com/cpan/HTML/Template.html
|
|
|
|
3. How is it implemented in Koha
|
|
|
|
Koha uses templates to handle different themes and languages. In
|
|
the CVS module "koha", there is a subdirectory for the design files:
|
|
koha-tmpl. This subdirectory can be checked out from CVS as if it
|
|
were a CVS module "koha-tmpl".
|
|
|
|
It contains two directories for the OPAC and the intranet templates:
|
|
opac-tmpl and intranet-tmpl.
|
|
|
|
Each of this directories reflects the available themes and their
|
|
languages. The default theme is "default" and the default language is
|
|
"en" (we use the 2-letter abbreviations, en => English, fr => French,
|
|
de => German and so on).
|
|
|
|
If you, for example, want to write a template for the OPAC
|
|
part of the "custommade" theme in Polish, it has to go in
|
|
koha-tmpl/opac-tmpl/custommade/pl/template.tmpl.
|
|
|
|
The template files will not reside in your web tree. If
|
|
you want to use an image, you have to put this in your web
|
|
tree, which is organized the same way as the template tree
|
|
(koha-html/opac-html/custommade/pl/images/image.gif).
|
|
|
|
If you have files (either templates or files in the webspace)
|
|
which are the same for all themes or languages use the
|
|
"all" directory. For example the "background.jpg" image, which
|
|
is the same for all languages within a theme should go in
|
|
koha-html/(intranet|opac)-html/custommade/all/images/background.jpg).
|
|
|
|
4. How to use it
|
|
|
|
Simply add an entry to the systempreferences: name=theme,
|
|
value=nameoftheme.
|
|
|
|
If you want your users be able to override your theme settings enter
|
|
name=allowthemeoverride value=customtheme1,customtheme2,... (names of
|
|
themes you want to be allowed) to the preferences.
|
|
|
|
For the language you normally don't have to enter anything, the
|
|
preferences of the user's browser will be used.
|
|
|
|
If anything is wrong you can specify a languageorder with the
|
|
following entry: name=languageorder value=en,fr,de,es (or whatever
|
|
comma-separated languages you want)
|
|
|
|
If you want to specify a directory for the templates you can do so in
|
|
koha.conf with 'templatedirectory=younameit'.
|
|
|
|
5. Rules and hints
|
|
|
|
5.1 For the templates
|
|
|
|
- Use absolute paths; relative paths in HTML tags would be relative to
|
|
the script's position and relative paths in <TMPL_INCLUDE> would be
|
|
relative to the template.
|
|
|
|
- You don't have to make templates for everything in your custom theme
|
|
or language. If you omit a template in a language, the template of
|
|
next available language is used. (Languages are tried in the order of
|
|
the user's browser settings.)
|
|
|
|
If there is no template in the specified language in a theme, a
|
|
different language will be chosen and NOT a different theme.
|
|
|
|
If you omit a template in all languages, the template of the default
|
|
theme will be used.
|
|
|
|
- Include comments with useful information such as the template's
|
|
location; this simplifies debugging
|
|
|
|
- Use the same name for the template and the script (with different
|
|
extensions of course)
|
|
|
|
5.2 for the scripts
|
|
|
|
- Use meaningful English (abbreviations) as parameter names
|
|
|
|
- If you fetch a list of data, pass it completely and let the designer
|
|
decide which data to use.
|
|
|
|
- Working with arrays and loops is always better, even if you have
|
|
only three similar rows.
|
|
|
|
- Don't let the script generate html and pass the output to the
|
|
template
|
|
|
|
6. Templating stuff in Koha
|
|
|
|
|
|
# FIXME
|
|
# pathtotemplate() call has been replaced with get_template_and_user() call
|
|
#
|
|
# This section should be rewritten to describe the new interface.
|
|
#
|
|
# In the meantime, look at an example script like member.pl or search.pl
|
|
#
|
|
#
|
|
|
|
This section is to describe scripts, modules and functions within them
|
|
to handle with themes, languages and other templating stuff.
|
|
|
|
If you write something which matches this, please add a brief
|
|
description here (e.g. function calls and return values).
|
|
|
|
- function %path = pathtotemplate(%hash) in C4::Output
|
|
|
|
Takes a hash with the following keys:
|
|
|
|
-template: the name of the template file (e.g. 'mytemplate.tmpl')
|
|
|
|
-type: 'opac', 'intranet', 'none' or something you specify, decides
|
|
which directory to lookup; defaults to intranet
|
|
|
|
-'opac': /somedirs/opac-tmpl/theme/language/template.tmpl
|
|
|
|
-'intranet': /somedirs/intranet-tmpl/theme/language/template.tmpl
|
|
|
|
-'none': /somedirs/theme/language/template.tmpl
|
|
|
|
-'my own words': /somedirs/my own
|
|
words/theme/language/template.tmpl
|
|
|
|
somedirs is 1. the path-parameter if specified 2. the
|
|
templatedirectory in koha.conf, 3. the includes + '/templates', 4.
|
|
the includes
|
|
|
|
-theme: you can manually set a theme (e.g. 'customtheme') only if
|
|
'allowthemeoverride' in systempreferences is set
|
|
|
|
-language: you can manually set a language (e.g. 'es')
|
|
|
|
-path: you can manually set the path to search for templates (e.g.
|
|
'/usr/koha/sometesttemplates')
|
|
|
|
You only need to pass the last three parameters if you want to
|
|
override the preferences for some reasons
|
|
|
|
Returns:
|
|
|
|
- $path{'path'}: the complete+absolute path of the template (e.g.
|
|
'/somedirs.../opac-tmpl/customtheme/es/mytemplate.tmpl')
|
|
|
|
- $path{'fondlanguage'}: '1' if the requested template was available
|
|
in the requested language
|
|
|
|
- $path{'fondtheme'}: '1' if the requested template was available in
|
|
the requested theme
|
|
|
|
7. Links
|
|
|
|
Do you have good links for the templater?
|
|
|
|
The HTML::Template documentation:
|
|
http://www.perldoc.com/cpan/HTML/Template.html
|
|
|
|
|
|
Comments to dnmeid@gmx.de Dorian
|
|
|