TEMPLATE README

    ~/tmp/<interfaceFolder>


There are four things that make up an interface:

	1) a set of HTML templates
	2) a set of images
	3) a style sheet
	4) a language-based 'messages_<language code>.txt'

You can create all or any one of the first three, and mix and match them to
create a new interfaces.

The language message files are not interface-specific (there's only one per 
language, not one per set of templates), and thus live in the "root" template
directory,  calliope/tmpl.

However, the help files *are* template specific - that is, one set of help 
files per language, per templates.  See Language and Internationalzation below
for more details.




TEMPLATES

To create a set of HTML templates, simply copy one of the existing folders
in this folder to a new folder within this (tmpl/) directory.  For example:

  cd /usr/local/calliope/tmpl
  cp -r calliope newtemplates

This new folder will automatically be detected when clicking on the 'preferences'
button in the navbar, and show up as an option under the 'gui' pull down menu.

Now, rearrange the HTML as you see fit.  Obviously, maintaining the template
variables is key to getting a new interface to function, as that's the
data that will get passed to a given template.  In other words, you don't 
have to provide all the available functionality, but that data *will* get 
passed to the templates.

Moreover, you should not expect nor need any codebase changes to create a 
new interface, unless 1) there's a bug; or 2) there's general agreement on 
the development team that such code changes will benefit all the interfaces.



IMAGES

To create a new set of images, copy one of the subfolders of images
in (www/images/) to a new folder in that same images directory.  
You can edit the images themselves, or replace them entirely, but you
shouldn't alter the names, as this will cause the images to display improperly
(or not at all) in an interfaces.

Further, the image folder name should correspond to the stylesheet name:
   images     = calliope
   stylesheet = calliope.css



STYLESHEETS

Styles can be found in the www/ folder as <intefacename>.css.  Copy to a new .css
file, and edit the color values for the style references.  Again, don't alter
the names of the style references, as this will mess up how a style sheet works
for another interface.




LANGUAGE AND INTERNATIONALIZATION

There is one message file per language.  Use ~/tmpl/messages_eng.txt as a 
guideline.  Set the language in the conf file.  Any new language files should
be named according to iso639-2 standards:

    http://www.loc.gov/standards/iso639-2/php/code_list.php

Basically, you would copy the english file, and translate all the messages
into any language you like.  If you create new language files, please 
send them back to the dev team at sourceforge.  Don't alter the message
codes, of course.

The language message files are not interface-specific (there's only one per 
language, not one per set of templates), and thus live in the "root" template
directory,  calliope/tmpl.

However, it's important to note that for the purposes of internationalization,
each set of templates (currently, calliope only has one by default) will contain
a minimum of one language-based folder, containing all the help files, which
naturally contain a lot of text.  Thus, all the help files are in 
calliope/tmpl/calliope/_eng/*, and all are named as help<type>_<lang>.tmpl 
(e.g. helpicons_eng.tmpl).  

To create additional language-specific help files, copy the english folder to
a new language folder.  The name should use the standard above, and correspond to
a messages file.

For example, to create spanish language files:

    cd /usr/local/calliope/tmpl
    cp messages_eng.txt  messages_spa.txt
    cp -r calliope/_eng calliope/_spa

And then of course, edit the resulting language files.