Theme support for jigl
Date        : 10/24/2003
jigl version: 2.0 and up
------------------------

Contents
--------
I.   Introduction to themes in jigl 2.x
II.  How themes work
III. Creating a theme
IV.  Template tags
V.   Information for older jigl installations


I. Introduction to themes in jigl 2.x
--------------------------------------
First off, it should be noted that jigl now creates a "web" directory in each
local directory to put the newly created gallery (html files, slides,
thumbnails and any optional theme files). You can still specify the current
local directory but it is no longer the default.

example:
-------
$HOME/.jigl/themes   -> location of where themes are stored.

myImages/            -> contains the gallery.dat file and all the original
                        images you want to jigl
myImages/slides      -> the slide images jigl created
myImages/thumbs      -> the thumbnail images jigl created
myImages/web/        -> the new directory containing everthing for the webpage
myImages/web/slides/ -> a copy of the slides directory
myImages/web/thumbs/ -> a copy of the thumbnail directory
myImages/web/theme/  -> the directory containing any extra files needed by this
                        theme. These are copied from the main theme directory.

Note: The web/ directory is a write-only directory. jigl does not look for
slides, thumbnails, themes or anything else in that directory. Don't try
putting things in that directory and expect jigl to find them. It won't.


II. How themes work
-------------------
Each themes is stored in its own directory under the ~/.jigl/themes/ directory.
The default theme, generated by jigl, is located in ~/.jigl/themes/default/

All themes must consists of at least these 4 files:
- theme_name.theme (ex: default.theme for the ~/.jigl/themes/default/ theme)
- index.template
- slide.template
- info.template

When jigl is run the theme_name.theme and template files are read in from
whatever theme was specified. These files are used to create the .html files
for the gallery. Template files are no longer copied into the local gallery
directory. Yay!

jigl also checks to see if files other then the 4 necessary files exist in the
"~/.jigl/themes/theme_name/" directory. If so, these extra files are assumed
to be needed by this theme for the gallery to work correctly. Thus they are
copied into the "web/theme" directory in the local gallery.

NOTE:
-----
You cannot put a full theme in the local web/theme directory and expect it to
simply work. Themes must reside in the ~/.jigl/themes/ directory. The local
"web/theme" directory is only for extra images and files needed by the theme
to work correctly after the .html files are generated.

Example: you may have images for the next, previous, index, and info links
above each slide. These images would be copied here.


III. Creating a theme
---------------------
So, you want to create a theme, eh? This should give you enough info to do so.

By far, the easiest way to create a theme is to use an existing theme and 
modify it. Copy the default theme, or someone elses theme and hack away.
There are themes available on at the jigl website:
http://xome.net/projects/jigl  -  download one and see how they work!


Okay, say you want to create a theme called "blue" and you're staring with the
default theme.

Step 1 : Copy a working theme
-----------------------------
Copy the directory, $HOME/.jigl/themes/default to $HOME/.jigl/themes/blue
In the $HOME/.jigl/themes/bule/ directory move default.theme to blue.theme

You should now have a working copy of the defalut theme called blue. Test it
by running jigl on a directory of images with the --theme blue option. Ensure
that jigl says it's using the blue theme. It'll say what theme it's using at
the start of the output and at the end.

Step 2 : Modify the theme
-------------------------
You'll notice that there are four files in your blue directory. Three template
files and a file called blue.theme. 

The three template files are used to define the general layout of the  index,
slide and info pages. They contain tags, in all capital letters, that tell 
jigl to insert specific information about that page. For instance,
NEXT-SLIDE-NAME will insert the name of the next slide in that location.

Some of the tags in the templates are internal to jigl and what jigl replaces
them with can not be changed.

Some of the tags are defined in the .theme file and parts of them can be
changed to reflect the theme you are trying to create. You may also add your
own tags in this file and use those tags in your template files as well.

Plese see the next section for exactly what tags are internal and what tags
are defined in the default.theme file.

Once you've modified your template and theme files, test it out like your did
at the end of step 1. You should see your changes in the new output.

If you come up with a cool theme, send it to me and I'll put it on the webpage
for others to enjoy.


IV. Template tags
-----------------

These are tags that can not be changed and the templates they correspond to.

index_template
--------------
INDEX-TITLEBAR
   This value is set in the gallery.dat file and is what you want the
   titlebar of the index page to say, i.e. what's between the <title></title>
   tags. This value can also be set on the command line using the -it option.
INDEX-TITLE
   This value is set in the gallery.dat file and is what you want the
   top of the index page to say.
   This value can also be set on the command line using the -it option.
TIME-STAMP
   The time stamp of when jigl was run.
INDEX-HEADER-INFO
   This value is set in the gallery.dat file and contains information that
   will be shown above the thumbnails. By default this tag is wrapped in
   the INDEX-HEADER tag defined in the .theme file.
INDEX-FOOTER-INFO
   This value is set in the gallery.dat file and contains information that
   will be shown below the thumbnails. By default this tag is wrapped in
   the INDEX-HEADER tag defined in the .theme file.
INDEX-NAVI
   The links to other index pages. This is used when more than one index
   page is created. More than one index page will be if you use the -ir
   option and the number of slides you have is more than (-ir * -iw).
   example: if you have -ir = 3 and -iw = 5 and you have 40 slides, then 
   you will have 3 index pages with 15 thumbnails in the first two and 
   10 thumbnails on the last index page.
PICTURES
   This tag is where the thumbnails will be inserted. This is sort of a
   special tag because it REQUIRES some of the tags in the .theme file to
   work correctly. The tags that must be defined in the .theme file are:

   THUMB-ROW              - a row of thumbnails. It contains two rows
   IMG-ROW                - the row of images
   SIZE-DIMENSION-ROW     - the row containing kb and XxY info
   IMG-COLUMN             - an individual thumbnail column
   SIZE-DIMENSION-COLUMN  - an individual kb and XxY column

   The default template says that these must be present and explains what each
   tag does.

slide_template
--------------
ORIG-IMAGE-NAME
   This will insert the name of the original image.
NEXT-SLIDE-NAME
   This will insert the name of the image for the next slide.
NEXT-SLIDE-HTML
   The next slides html page.
PREV-SLIDE-HTML
   The previous slides html page.
INDEX-HTML
   The index.html file name.
INFO-HTML
   The name of this slides info page.
SLIDE-IMAGE
   This slides image.
SLIDE-DESCRIPTION
   The description of this slide.
SLIDE-COUNT
   Will insert (x of n) image count.

info_template
-------------
ORIG-IMAGE-NAME
   This will insert the name of the original image.
NEXT-SLIDE-NAME
   This will insert the name of the image for the next slide.
THIS-SLIDE-HTML
   The slide html page for this info page.
PREV-SLIDE-HTML
   The previous slides html page.
PREV-INFO-HTML
   The previous slides info html page.
INDEX-HTML
   The index.html file name.
NEXT-INFO-HTML
   The next slides info html page.
NEXT-SLIDE-HTML
   The next slides html page.
INFO-IMAGE
   The slide image that has been scaled down using the html height and width
   tags. The inserted code is: <img src="imgename" width=x height=y> unless
   the link-originals option is used. Then the above line is wrapped in an
   <a href> tag.
SLIDE-DESCRIPTION
   The description of this slide.
SLIDE-COUNT
   Will insert (x of n) image count.
EXIF-NAME-COL
   A string with the names of the exif fields as returned from jhead. Each name
   has a <nobr> html tag before it and a <br> tag after it. This is meant to
   be used in a table column (between <td></td> tags).
EXIF-VAL-COL
   A string with the values of the exif fields as returned from jhead. Each
   value has a <nobr>&nbsp;:&nbsp; html tag before it and a <br> tag after it.
   This is meant to be used in a table column (between <td></td> tags).


default.theme
-------------
these are tags that portions of can be modified to help integrage better with
the theme you're trying to create.

INDEX-LINK
   HTML for the link to index.html
INFO-LINK
   HTML for the link to a slide's info page
THIS-SLIDE-LINK
   HTML for the link to the current slide. Used on info page
NEXT-SLIDE-LINK
   HTML for the link to next slide
LAST-SLIDE-NEXT-LINK
   HTML for the Next link on the last slide page
PREV-SLIDE-LINK
   HTML for the link to previous slide
FIRST-SLIDE-PREV-LINK
   HTML for the Prev link on the first slide page
NEXT-INFO-LINK
   HTML for the link to next info page
LAST-INFO-NEXT-LINK
   HTML for the Next link on the last info page
PREV-INFO-LINK
   HTML for the link to previous info page
FIRST-INFO-PREV-LINK
   HTML for the Prev link on the first info page
INDEX-HEADER
   HTML for the Header area on index page
INDEX-FOOTER
   HTML for the Footer area on index page
THUMB-ROW
   Table around each row of thumbnails
   This tag must be present and must contain the two tags:
   IMG-ROW and SIZE-DIMENSION-ROW
IMG-ROW
   Row of the actual thumbnails
   This tag must be present and must contain the IMG-COLUMN tag
SIZE-DIMENSION-ROW
   Row of size and dimension information under each slide
   This tag must be present and must contain the SIZE-DIMENSION-COLUMN tag.
IMG-COLUMN
   HTML for an individual thumbnail
   This tag must be present.
SIZE-DIMENSION-COLUMN
   HTML for the size and dimension information of an individual thumbnail
   This tag must be present.



V. Information for older jigl installations
================================================================================
Basic Theme Support for jigl
Date        :  04/17/2003
jigl version: 1.0 and 1.1
----------------------------

Basic themes are supported in jigl by the use of template files. There are
three template files that jigl uses:
   index_template
   slide_template
   info_template

The templates describe the basic layout of the page including the placement
of information generated by jigl and the foreground and background colors.

The default templates are built into the jigl program and will be generated
if none exist. If these files do exist in the directory jigl is processing
it will use those templates.

The placement of information by jigl is done by using a series of tags that
jigl reads and replaces with the appropriate information. These tags are
keywords and are in all capital letters. The following tags are available
in their respective templates.

index_template
--------------
INDEX-TITLEBAR
   This value is set in the gallery.dat file and is what you want the
   titlebar of the index page to say, i.e. what's between the <title></title>
   tags.
INDEX-TITLE
   This value is set in the gallery.dat file and is what you want the
   top of the index page to say.
TIME-STAMP
   The time stamp of when jigl was run.
INDEX-HEADER bgcolor=#rrggbb
   This value is set in the gallery.dat file and contains information that
   will be shown in it's own table above the thumbnails. The bgcolor tag
   extender is optional and is meant to change the background color of
   the table.
INDEX-FOOTER bgcolor=#rrggbb
   This value is set in the gallery.dat file and contains information that
   will be shown in it's own table below the thumbnails. The bgcolor tag
   extender is optional and is meant to change the background color of
   the table.
PICTURES bgcolor=#rrggbb
   This tag is where the pictures will be inserted. Each row of pictures
   will be it's own table and the background of the tables can be set with
   the optional bgcolor tag extender.

slide_template
--------------
ORIG-IMAGE-NAME
   This will insert the name of the original image.
NEXT-SLIDE-NAME
   This will insert the name of the image for the next slide.
PREV-SLIDE-HTML
   The previous slides html page.
INDEX-HTML
   The index.html file name.
INFO-HTML
   The name of this slides info page.
NEXT-SLIDE-HTML
   The next slides html page.
SLIDE-IMAGE
   This slides image.
SLIDE-DESCRIPTION
   The description of this slide.
SLIDE-COUNT
   Will insert (x of n) image count.

info_template
-------------
ORIG-IMAGE-NAME
   This will insert the name of the original image.
NEXT-SLIDE-NAME
   This will insert the name of the image for the next slide.
THIS-SLIDE-HTML
   The slide html page for this info page.
PREV-SLIDE-HTML
   The previous slides html page.
PREV-INFO-HTML
   The previous slides info html page.
INDEX-HTML
   The index.html file name.
NEXT-INFO-HTML
   The next slides info html page.
NEXT-SLIDE-HTML
   The next slides html page.
INFO-IMAGE
   The slide image that has been scaled down using the html height and width
   tags. The inserted code is: <img src="imgename" width=x height=y> unless
   the link-originals option is used. Then the above line is wrapped in an
   <a href> tag.
SLIDE-DESCRIPTION
   The description of this slide.
SLIDE-COUNT
   Will insert (x of n) image count.
EXIF-INFO
   A table with all of the exif info in it for this image.


Creating your own templates
---------------------------
The easiest way to create you own template files it to let jigl create the
default templates for you and modify them. This will give you a good idea
of how it all fits together.

If you come up with some interesting templates, send them to me and I'll put
them on the web site for others to use!