View | Details | Raw Unified | Return to bug 14129
Collapse All | Expand All

(-)a/koha-tmpl/templates.readme (-191 lines)
Lines 1-190 Link Here
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
191
- 

Return to bug 14129