+++ /dev/null
-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
projects / koha.git / commitdiff