[Koha-cvs] CVS: koha/koha-tmpl templates.readme,1.1.1.1,1.2
Ambrose Li
acli at users.sourceforge.net
Mon Jan 20 04:53:34 CET 2003
Update of /cvsroot/koha/koha/koha-tmpl
In directory sc8-pr-cvs1:/tmp/cvs-serv30466
Modified Files:
templates.readme
Log Message:
Reformatted with "par 72" command
Index: templates.readme
===================================================================
RCS file: /cvsroot/koha/koha/koha-tmpl/templates.readme,v
retrieving revision 1.1.1.1
retrieving revision 1.2
diff -C2 -r1.1.1.1 -r1.2
*** templates.readme 16 Sep 2002 09:10:26 -0000 1.1.1.1
--- templates.readme 20 Jan 2003 03:53:32 -0000 1.2
***************
*** 1,76 ****
! 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.
!
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
!
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).
!
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 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.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
!
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
-'opac': /somedirs/opac-tmpl/theme/language/template.tmpl
-'interanet': /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 at gmx.de
! Dorian
\ No newline at end of file
--- 1,178 ----
! 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.
!
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
!
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).
!
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 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.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
!
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
!
-'opac': /somedirs/opac-tmpl/theme/language/template.tmpl
+
-'interanet': /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 at gmx.de Dorian
More information about the Koha-cvs
mailing list