/
templates.readme
190 lines (128 loc) · 6.62 KB
/
templates.readme
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
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