koha-tmpl/templates.readme

   1 This is a README-file for all interested in the templating system used
   2 by Koha.  It contains guidelines ans descriptions, please feel free to
   3 make comments and contributions to this file.
   4
   5 1. Introduction
   6
   7   The advantage of a templating-system is the separation of code and
   8   design.  It is much easier to read the html and get an imagination of
   9   what it will look like without having it shattered by declarations and
  10   functions.  And it is also nicer being able to alter some functions
  11   without worrying about the webdesign.
  12
  13   On the other hand templating stands in contradiction on scripting the
  14   procedural way, it forces obect-oriented programming.
  15
  16   With templates Koha can be made fully skinnable, we speak of themes,
  17   and can support different languages.
  18
  19 2. How does it work
  20
  21   The short version: Instead of printing html from your script you only
  22   define some template-parameters.
  23
  24   You design your html-page without code in it and where you need to
  25   insert data generated by the script you can pass this data from the
  26   template-parameters via special tags.
  27
  28   Indeed there is a little more to know.
  29
  30   I recomend reading the documentation to the HTML::Template-module.
  31   You ca obtain it from http://www.perldoc.com/cpan/HTML/Template.html
  32
  33 3. How is it implemented in Koha
  34
  35   Koha uses templates to handle different themes and languages.  There
  36   is a CVS-module for the design-files: koha-tmpl.
  37
  38   It contains two directories for the opac- and the intranet-templates:
  39   opac-tmpl and intranet-tmpl.
  40
  41   Each of this directories reflects the available themes and their
  42   languages.  The default theme is "default" and the default language is
  43   "en" (we use the 2letter-abbreviations, en => english, fr => french,
  44   de => german and so on).
  45
  46   If you for example want to write a template for the opac
  47   part of the "custommade"-theme in polish it has to go in
  48   koha-tmpl/opac-tmpl/custommade/pl/template.tmpl.
  49
  50   The template-files will not reside in your webtree, if
  51   you want to use a image you have to put this in your
  52   webtree, which is organized the same way as the templatetree
  53   (koha-html/opac-html/custommade/pl/images/image.gif).
  54
  55   If you have files (either templates or files in the webspace)
  56   which are the same for all themes or languages use the
  57   "all"-directory. For example the "background.jpg"-image, which
  58   is the same for all languages within a theme should go in
  59   koha-html/(intranet|opac)-html/custommade/all/images/background.jpg).
  60
  61 4. How to use it
  62
  63   Simply add an entry to the systempreferences: name=theme,
  64   value=nameoftheme.
  65
  66   If you want your users be able to override your theme-settings enter
  67   name=allowthemeoverride value=customtheme1,customtheme2,... (names of
  68   themes you want to be allowed) to the preferences.
  69
  70   For the language you normally don't have to enter anything, the
  71   preferences of the user's browser will be used.
  72
  73   If anything is wrong you can specify a languageorder with the
  74   following entry: name=languageorder value=en,fr,de,es (or whatever
  75   comma-separated languages you want)
  76
  77   If you want to specify a directory for the templates you can do so in
  78   koha.conf with 'templatedirectory=younameit'.
  79
  80 5. Rules and hints
  81
  82  5.1 for the templates
  83
  84   -use absolut paths, relative paths in html-tags would be relative to
  85   the script's position and relative paths in <TMPL_INCLUDE> would be
  86   relative to the template.
  87
  88   -you don't have to make templates for everything in your custom-theme
  89   or language. if you omit a template in a language the template of next
  90   available language is used (languages are tried in the order of the
  91   user's browser-settings).
  92
  93    if there is no template in the specified language in a theme a
  94    different language will be chosen and NOT a different theme.
  95
  96    if you omit a template in all languages the template of the
  97    default-theme will be used.
  98
  99   -include comments with useful information such as the template's
 100   location, this simplifies debugging
 101
 102   -use the same name for the template and the script (with different
 103   extensions of course)
 104
 105  5.2 for the scripts
 106
 107   -use meaningfull english (abbreviations) as parameter-names
 108
 109   -if you fetch a list of data, pass it completely and let the designer
 110   decide which data to use.
 111
 112   -working with arrays and loops is always better, even if you have only
 113   three similar rows.
 114
 115   -don't let the script generate html and pass the output to the
 116   template
 117
 118 6. Templating stuff in Koha
 119
 120   This section is to describe scripts, modules and functions within them
 121   to handle with themes, languages and other templating stuff.
 122
 123   If you write something which matches this, please add a brief
 124   description here (e.g. function calls and return values).
 125
 126   -function %path = pathtotemplate(%hash) in C4::Output
 127
 128    Takes a hash with the following keys:
 129
 130     -template: the name of the template-file (e.g. 'mytemplate.tmpl')
 131
 132     -type: 'opac', 'intranet', 'none' or something you specify, decides
 133     which directory to lookup, defaults to intranet
 134
 135       -'opac': /somedirs/opac-tmpl/theme/language/template.tmpl
 136
 137       -'interanet': /somedirs/intranet-tmpl/theme/language/template.tmpl
 138
 139       -'none': /somedirs/theme/language/template.tmpl
 140
 141       -'my own words': /somedirs/my own
 142       words/theme/language/template.tmpl
 143
 144       somedirs is 1. the path-parameter if specified 2. the
 145       templatedirectory in koha.conf, 3. the includes + '/templates', 4.
 146       the includes
 147
 148     -theme: you can manually set a theme (e.g. 'customtheme') only if
 149     'allowthemeoverride' in systempreferences is set
 150
 151     -language: you can manually set a language (e.g. 'es')
 152
 153     -path: you can manually set the path to search for templates (e.g.
 154     '/usr/koha/sometesttemplates')
 155
 156     You only need to pass the last three parameters if you want to
 157     override the preferences for some reasons
 158
 159    Returns:
 160
 161     - $path{'path'}: the complete+absolute path of the template (e.g.
 162     '/somedirs.../opac-tmpl/customtheme/es/mytemplate.tmpl')
 163
 164     - $path{'fondlanguage'}: '1' if the requested template was available
 165     in the requested language
 166
 167     - $path{'fondtheme'}: '1' if the requested template was available in
 168     the requested theme
 169
 170 7. Links
 171
 172   Do you have good links for the templater?
 173
 174   The HTML::Template documentation:
 175   http://www.perldoc.com/cpan/HTML/Template.html
 176
 177
 178 Comments to dnmeid@gmx.de Dorian