-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.
-
+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 webdesign.
- On the other hand templating stands in contradiction on scripting the procedural way, it forces obect-oriented programming.
- With templates Koha can be made fully skinnable, we speak of themes, and can support different languages.
-
+
+ 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 ca obtain it from http://www.perldoc.com/cpan/HTML/Template.html
-
+
+ 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.
- There is a CVS-module for the design-files: 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 2letter-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 webtree, if you want to use a image you have to put this in your webtree, which is organized the same way as the templatetree (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).
-
+
+ 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'.
-
+
+ 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 absolut 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.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 meaningfull 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
-
+
+ - 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
- 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
+
+
+# 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
- -'interanet': /somedirs/intranet-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
+
+ -'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
+
+ -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
-
+
+ - $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
\ No newline at end of file
+
+ The HTML::Template documentation:
+ http://www.perldoc.com/cpan/HTML/Template.html
+
+
+Comments to dnmeid@gmx.de Dorian
projects / koha.git / blobdiff