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 web design.
  12
  13   On the other hand, templating stands in contradiction on scripting the
  14   procedural way; it forces object-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 can 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.  In
  36   the CVS module "koha", there is a subdirectory for the design files:
  37   koha-tmpl.  This subdirectory can be checked out from CVS as if it
  38   were a CVS module "koha-tmpl".
  39
  40   It contains two directories for the OPAC and the intranet templates:
  41   opac-tmpl and intranet-tmpl.
  42
  43   Each of this directories reflects the available themes and their
  44   languages.  The default theme is "default" and the default language is
  45   "en" (we use the 2-letter abbreviations, en => English, fr => French,
  46   de => German and so on).
  47
  48   If you, for example, want to write a template for the OPAC
  49   part of the "custommade" theme in Polish, it has to go in
  50   koha-tmpl/opac-tmpl/custommade/pl/template.tmpl.
  51
  52   The template files will not reside in your web tree. If
  53   you want to use an image, you have to put this in your web
  54   tree, which is organized the same way as the template tree
  55   (koha-html/opac-html/custommade/pl/images/image.gif).
  56
  57   If you have files (either templates or files in the webspace)
  58   which are the same for all themes or languages use the
  59   "all" directory. For example the "background.jpg" image, which
  60   is the same for all languages within a theme should go in
  61   koha-html/(intranet|opac)-html/custommade/all/images/background.jpg).
  62
  63 4. How to use it
  64
  65   Simply add an entry to the systempreferences: name=theme,
  66   value=nameoftheme.
  67
  68   If you want your users be able to override your theme settings enter
  69   name=allowthemeoverride value=customtheme1,customtheme2,... (names of
  70   themes you want to be allowed) to the preferences.
  71
  72   For the language you normally don't have to enter anything, the
  73   preferences of the user's browser will be used.
  74
  75   If anything is wrong you can specify a languageorder with the
  76   following entry: name=languageorder value=en,fr,de,es (or whatever
  77   comma-separated languages you want)
  78
  79   If you want to specify a directory for the templates you can do so in
  80   koha.conf with 'templatedirectory=younameit'.
  81
  82 5. Rules and hints
  83
  84  5.1 For the templates
  85
  86   - Use absolute paths; relative paths in HTML tags would be relative to
  87     the script's position and relative paths in <TMPL_INCLUDE> would be
  88     relative to the template.
  89
  90   - You don't have to make templates for everything in your custom theme
  91     or language. If you omit a template in a language, the template of
  92     next available language is used. (Languages are tried in the order of
  93     the user's browser settings.)
  94
  95     If there is no template in the specified language in a theme, a
  96     different language will be chosen and NOT a different theme.
  97
  98     If you omit a template in all languages, the template of the default
  99     theme will be used.
 100
 101   - Include comments with useful information such as the template's
 102     location; this simplifies debugging
 103
 104   - Use the same name for the template and the script (with different
 105     extensions of course)
 106
 107  5.2 for the scripts
 108
 109   - Use meaningful English (abbreviations) as parameter names
 110
 111   - If you fetch a list of data, pass it completely and let the designer
 112     decide which data to use.
 113
 114   - Working with arrays and loops is always better, even if you have
 115     only three similar rows.
 116
 117   - Don't let the script generate html and pass the output to the
 118     template
 119
 120 6. Templating stuff in Koha
 121
 122
 123 # FIXME
 124 # pathtotemplate() call has been replaced with get_template_and_user() call
 125 #
 126 # This section should be rewritten to describe the new interface.
 127 #
 128 # In the meantime, look at an example script like member.pl or search.pl
 129 #
 130 #
 131
 132   This section is to describe scripts, modules and functions within them
 133   to handle with themes, languages and other templating stuff.
 134
 135   If you write something which matches this, please add a brief
 136   description here (e.g. function calls and return values).
 137
 138   - function %path = pathtotemplate(%hash) in C4::Output
 139
 140     Takes a hash with the following keys:
 141
 142     -template: the name of the template file (e.g. 'mytemplate.tmpl')
 143
 144     -type: 'opac', 'intranet', 'none' or something you specify, decides
 145     which directory to lookup; defaults to intranet
 146
 147       -'opac': /somedirs/opac-tmpl/theme/language/template.tmpl
 148
 149       -'intranet': /somedirs/intranet-tmpl/theme/language/template.tmpl
 150
 151       -'none': /somedirs/theme/language/template.tmpl
 152
 153       -'my own words': /somedirs/my own
 154       words/theme/language/template.tmpl
 155
 156       somedirs is 1. the path-parameter if specified 2. the
 157       templatedirectory in koha.conf, 3. the includes + '/templates', 4.
 158       the includes
 159
 160     -theme: you can manually set a theme (e.g. 'customtheme') only if
 161     'allowthemeoverride' in systempreferences is set
 162
 163     -language: you can manually set a language (e.g. 'es')
 164
 165     -path: you can manually set the path to search for templates (e.g.
 166     '/usr/koha/sometesttemplates')
 167
 168     You only need to pass the last three parameters if you want to
 169     override the preferences for some reasons
 170
 171    Returns:
 172
 173     - $path{'path'}: the complete+absolute path of the template (e.g.
 174     '/somedirs.../opac-tmpl/customtheme/es/mytemplate.tmpl')
 175
 176     - $path{'fondlanguage'}: '1' if the requested template was available
 177     in the requested language
 178
 179     - $path{'fondtheme'}: '1' if the requested template was available in
 180     the requested theme
 181
 182 7. Links
 183
 184   Do you have good links for the templater?
 185
 186   The HTML::Template documentation:
 187   http://www.perldoc.com/cpan/HTML/Template.html
 188
 189
 190 Comments to dnmeid@gmx.de Dorian