General Notes About Templates and Themes
- Link to templating info: http://koha.org/contribute/templating/
- Back to ThemeHowTo
From: Finlay on 08 Oct 2002
So what to do about the templating?
I think that we already have pretty much a consensus on what the plan is.
The information on Roger's Wiki at http://www.saas.nsw.edu.au/wiki/index.php?page=ThemeHowTo
is all pretty much how I see it. Just to paraphrase:
1) all templates should live in koha-tmpl, along with there associated includes and images (style sheets, javascripts, etc)
2) this cvs branch will eventually replace the koha-html tree all together.
3) under koha-tmpl there are two subtrees: intranet-tmpl/ and opac-tmpl/ corresponding to what should go into the <serverroot>/intranet/htdocs/ and <serverroot>/opac/htdocs/ directories on the live sites.
4) under each of these are /<theme>/<lang>/ directories. Each theme can have different language settings. At present I have been working only on the /default/en/ templates.
5) Theme, language selection: In the scripts there should be the lines:
use C4::Output; my $template = gettemplate(“opac-search.tmpl”, “opac”);
The gettemplate subroutine looks for the theme and language settings, looks for a template, loads the template and sets the <themelang> tag for use in all the includes etc. I.e.
src=”<TMPL_VAR NAME='themelang'>/images/search-button.gif”
This is the concessus right now. There are some other issues however:
Issue 1) Should we have a totally seperated html/website tree under each /<theme>/<lang>/ directory ?
I think so. most, if not all of the includes and images are theme and language specific. Anything that is not language specifc can go in the /<theme>/<all>/ directory. I dont think there will be anything not theme specific.
Issue 2) The “gettemplate” and “pathtotemplate” subroutines in Output.pm ? why two and which to use?
There are two routines here because Dorian and I solved the same problem
at the same time 
The key design difference is that gettemplate
actually loads the template and returns the template object. Whereas
pathtotemplate returns a path that can be use to load the template.
I think it is better to pass the template because it simplifies the script code: getting the template involves only one line. If there are extra options and settings that you want to pass to the HTML::Template→new() call, they can be passed through a new improoved gettemplate sub. (not hard to change.) however I cant image when you would want to do this, and if so it would not be commen.
what do people think?
Issue 3) What to do about systempreferences etc. ? How does koha select the theme and language?
There has been some disscussion on this which I will try and paraphrase.
Luckly the gettemplate routine doesnt really need to change at all so
changing our minds about this issue is easy
At present there are two places for settings: the koha.conf file and the systempreferences table in the database. Gettemplate gets the 'opachtdocs' or 'intranethtdocs' settings in from the koha.conf file (through C4::Context whis is really cool btw) and then looks into the systempreferences table for the 'opaclanguages' and 'opacthemes' settings. These can be space seperated lists in order of preference. the subroutine then goes and looks in the directory for the specified files until it finds one.
One option is to put everything in the database? another option is to have new database tables “themes” and “languages” with IP and userid fields so that settings can be kept between sessions and individual computers can have different settings? I think this is desirable.
Issue 4) CSS ?
Roger has suggested using a template variable 'type' to switch between the intranet and the opac. This, in my opinion, is a bad idea. I have been trying to remove all the 'type = opac || intra' code from koha. The opac and the intranet should use completely seperate code. all apart from the modules (thus the “opac” in gettemplate(”<tmplatename>.tmpl”, “opac”) )
However, there is no reason we can have heaps of CSS in the templated koha. It just goes into files that are read in through <TMPL_INCLUDE NAME=“stylesheet”> tags.
Well thats about all for now.
I hope that is helping
Finlay
ps. other issues?
Finlay wrote: Hi Chris, Roger and everyone else,
I have been thinking about this issue as well.
As part of the get-everything-templated program it has become necessary to rationalise the file system structure in koha.
Roger Buck wrote:
Are the 'opac' and 'intranet' designed to be installed as 'stand-alone' on physically separate servers?If designed to support optional 'stand-alone', then I don't think the existing installation would support that. The OPAC relies on stuff stored in the 'intranet' folders.
Finlay wrote:
At present the opac-intranet divide has certainly become blury! however with respect to what chris has said: So the aim is to make it possible/easy for big libraries to use koha while not making it hard for small ones.
Spreading server loads and allowing for a little more security, I think we should attempt to reinforce the opac / intranet divide.
As I reorganise the opac I am attempting to make it as stand alone as possible. The only thing they should share is the database.
To this end I propose the following structure for the opac servers file system…
<server root>/cgi-bin/<opac only scripts>
Roger buck wrote:
How about a subdir of cgi-bin:
<serverroot>/cgi-bin/opac/<opac only scripts>
I just have “a thing” about placing files in cgi-bin root :)
<server root>/htdocs/<theme>/<lang>/<theme specific templates>
<server root>/htdocs/<theme>/<lang>/images/<theme specific images>
<server root>/htdocs/<theme>/<lang>/includes/<theme specific includes>
I dont see the problem with having multiple copies of some of the images and includes if they are the same accross different theme/lang settings.
If you were really worried we could put some sym-links in?
“I agree - I think the duplication is justified - sym-links not required (Rog)”
Note that all this stuff is only intended for the opac. I.e. non of these files will have settings like “$type = 'opac' | 'intra' ”
That just leads to too much complication, and ties the opac and the intranet together, which is what we want to avoid.
agreed (Rog)
I will also attemp to rename all the scripts and template files so that they have the same name just different suffix:
opac-search.pl goes with opac-search.tmpl and if there is a search.pl in the intranet and a search.pl in the opac
I think they should be renamed opac-search.pl and intra-search.pl.
It doesnt matter if these two files do almost the same thing, we want them to be seperate.
With regards themes and language settings. I think we should expect that the themes in the intranet and in the opac might be quite different. For example there might be a “junior” theme for the opac, set up in the childrens section of the library. And there might be a “frontdesk” theme in the intranet for the front desk only.
So in cvs I think we will need to keep these seperate. We can follow Dorian's lead and have:
:koha-tmpl/intranet-tmpl/<theme>/<lang>/
:koha-tmpl/opac-tmpl/<theme>/<lang>/
for all the templates.
sounds good to me (Rog)
In the main branch we have all the cgi-bin stuff mixed together. I think this is a little confusing. We can put the opac stuff in the koha/opac/ directory?
At the moment I have put the template-only opac scripts into a koha/tmpl/ directory, that I will move into koha/opac/ when its ready (which it basically is).
All the C4 modules can be shared byt the opac and intranet. Dont see any reaon to keep them seperate?
also sounds good (Rog) ''
Systempreferences:
We need to get a standard list of system preferences.
I will write another email about that as this one has gotten quite long enough
Finlay
On Wed, 2002-10-02 at 20:35, paul POULAIN wrote:
Finlay Thompson wrote:
>i Everyone,
>
>It seems that everyone had a email conversation about the way templating
>is being done in koha. I have been working on templating the opac. Let
>me explain what I have done, which is not to say that it is the right
>way
>
>Firstly I should point out that I have been developing on the rel-1-2
>branch, but will probably merge this into the 1.3 release.
>
Did you commit it ? I'm not sure, i see almost nothing. If you've
commited, let me know how many (and which) files are in the CVS.
>If you want to go and check it out go to http://opacdev.katipo.co.nz
>you can login using user:pword = frank:frank or finlay:finlay
>
>CVS: All the templates are going into the koha-tmpl tree of cvs.
>under this root we have two sub-branches intranet-tmpl/ and opac-tmpl/
>eveything onder there should be installed in koha/intra/htdocs/ and
>koha/opac/htdocs/ respectivly.
>
OK, that's clear. Hope everybody reads this.
>And then we have the structure: <theme>/<lang>/<scriptname>.tmpl
>I suggest that we try hard to keep the templates and scripts with the
>same names…..
>
not try very hard, but MUST…
>includes and images go under the <theme>/<lang>/ directory…..
>
>An example:
>The opac-search.pl script presents the search form in the opac.
>see: http://opacdev.katipo.co.nz/cgi-bin/koha/opac-search.pl
>
>it calls the opac-search.tmpl template which in this instance is found
>in the default/en/ theme and language.
>
>There is an include at the top: cat-top.inc and this is found in
>default/en/includes/cat-top.inc all the images in the templates are
>prefixed by the HTML::Template tag: <TMPL_VAR NAME=“themelang”>
>eg. src=”<TMPL_VAR NAME='themelang'>/images/search-button.gif”
>This template variable is automatically passed to includes and is
>automatically loaded into the template by the template loading
>subroutine…..
>
Nice, fast and clear. Great.
>Template loading:
>The relevant code in opac-search.pl is:
>
> use C$::Output;
> my $template = gettemplate(“opac-search.tmpl”, “opac”);
>
So, the picktempate sub can be dropped (in Output.pm from both 1.2 and
main branch) ?
and most templated scripts must be touched (1-2 line modify)
>I will update the reading material on:
>http://koha.org/contribute/templating/
>
>Finlay
>
Looking at your code (v1.2) show :
* we must add 2 rows in systempref table :
→ opaclanguages
→ opacthemes
(note : why having opac and not intranet ?)
* we must add 2 lines in the config file :
→ opachtdocs
→ intrahtdocs
Am I right ? If yes, then, you're the templating coordinator, so I
agree, and will soon move already templated scripts to the good
directory structure.
But i'll wait for your confirmation (am i right ? is there scripts that
you still haven't commit ?)
–
Paul
Roger Buck schrieb:
Please see first draft of the documentation on wiki (OK Nick?):
http://www.saas.nsw.edu.au/wiki/index.php?page=ThemeHowTo
All are invited to add/delete/modify as they see fit.
cool, a few comments:
- It's nice to have the themelang-variable, but you don't need it
necessarily.
If you template is in /children/es you images will be there too
(assuming a setup with your dirs as below)
- I'd prefer intranet-serverroot and opac-serverroot than
koha/intra/htdocs/ and koha/opac/htdocs/.
- The includes via ssi are getting replaced by includes via
HTML::Template <TMPL_INCLUDE NAME=…>
Important to standardise file structure ASAP (my usual hobby-horse!)
agree
> In my opinion storing the templates together with images, css and so on
> is not a big problem but it increases the html-like-aproach to designin
> a theme (some tags in the html get replaced automatically by the
> scripts). I think this is what html::template was made for.
I still am not convinced about the last paragraph. From my trials , use
of .css seems to offer some major advantages. I also see advantage to
storing templates along with everything else in a single tree structure
in the webspace? - see wiki for example code simplification when using
.css combined with HTML::Template.
Right, maybe my english is too bad, but this is what I thought.
Your css-example to deal with intranet/opac is a little bit early. .css are nice, but we have to improve the designing-process step by step. For now all I want to do is to templatify all the koha-scripts.
As I NOW see it, the web space file system might look like:
<serverroot>/<theme><lang>/
./images
./includes
./styles
./jscripts
./help
./catalogue
./members
./whatever…
This means that each theme is effectively almost a virtual server in
terms of file structure (I think I have this right Dorian?). This would
require a change in current CVS thinking.
Exactly as I see it.
I'd love to hear Finlay's ok for this.
I am still hoping to get some feedback on the following:
Roger Buck wrote:
> 1. I am using Steve's RC14 as the base distribution - is that OK?
Sorry, don't know, since i'm working with the latest cvs-files for quite a while now.
>
> 2. I need to know how the theme variable is set. Do I need to create a
> new table… do I need to creata a new entry in ssytempreferences (if
> so, then what syntax)… do I need to make an entry in koha conf (if so
> then what syntax) or should I make a temporary entry in Output.pm… or
> should I do something else?
At the moment you have to set a vaiable in the systempreferences. Name=opacthemes Value=theme1 theme2 theme3 … you have to specify at least one theme The name OPACthemes is a little confusing as it is even for the intranet
dorian
