
TABLE OF CONTENTS
-----------------

  1. Overview
  2. About Tags
  3. Including Files
  4. Special Files
  5. Defined Tags
  6. Managing Colors


1. OVERVIEW
-----------

Template files give you some control of the layout of output pages.  They
also keep the main body of code much cleaner than it would otherwise be.

Colors are also handled by the template files (see section 6 in this file).

Note that if you like the way the layout of pages are already, you do not
need to touch the template files at all.  You should only modify a template
file if you have something in the page layout you wish to change or if you
have a need to change the colorization of different elements of MiG.


2. ABOUT TAGS
-------------

Template files are simply HTML files with some special tags embedded in
them, which are expanded by MiG at runtime.

Tags are surrounded by %% marks, such as this example:

   <br>
   Contact <a href="mailto:%%maintAddr%%">%%maintAddr%%</a> with any
      comments or problems.
   <br>

In this case, %%maintAddr%% is the relevant tag name.

You can control how the page layout looks by modifying and/or moving HTML
elements and/or MiG tag elements in the template file.  It is assumed you
have an understanding of HTML - modify the templates at your own risk, and
always make a backup copy beforehand in case your changes don't work out
the way you wanted them to.

There is a glossary of tags in section 5 of this document.


3. INCLUDING FILES
------------------

An "include" function is also provided.  To include a file, place a
directive like this one, on a line by itself:

  #include "filename";

Such as:

  #include "custom.html";

The contents of the file you specify will be inserted in place of the
"#include" placeholder.

Please note some things about #include:

  1. All files you wish to include must live in the templates/ subdirectory
     of your MiG installation.

  2. However, if you really don't want to do that (because it means you
     have to maintain two copies of the same file in different locations,
     etc), a symbolic link will also work.  For example:

       ln -s /www/htdocs/includes/custom.html /www/htdocs/mig/templates

     In this case you would have /www/htdocs/includes/custom.html which
     is the real file, and a symbolic link called "custom.html" in
     /www/htdocs/mig/templates which would point to the real file,
     leaving you with only one copy to maintain.

  3. The #include directive must be on a line by itself.  It will not
     function if anything else is on that line.  Also, the filename
     must be in quotation marks, and the command must be terminated with
     a semicolon.  Here are some examples:

       #include "custom.html";                # RIGHT
       #include "custom.html"                 # WRONG - no semicolon
       #include custom.html;                  # WRONG - no quotes
       <p>#include "custom.html";</p>         # WRONG - not alone on line

  4. By the time the #include is parsed, it's probably too late to include
     any dynamic content in your template unless the web server is going
     to re-evaluate the output before it is sent to the browser.  So
     I can't guarantee that things like SSI markup, embedded PHP code
     and the like will work inside an included file.  The only way you
     can determine if that sort of thing will work is to try it out.
     I make no guarantee that anything like that can or will work.

Look at either image.html or folder.html for an example (#include is used
to embed the CSS style sheet file "style.css").


4. SPECIAL FILES
----------------

There are three special files that MiG uses for its own purposes.

   templates/folder.html - used for any view where folders and/or
	thumbnail images are shown.

   templates/image.html - used for any view where an image is shown
	by itself.

   templates/style.css - Contains text/css markup.


5. DEFINED TAGS
---------------

A glossary of recognized MiG template tags, and what they are expanded to.

1. Tags for use in any template:

%%baseURL%%		Base URL to call this script (MiG) again.
%%maintAddr%%		Email address of album maintainer (as defined
			in mig.cfg).
%%version%%		Current version number of this MiG installation.
%%backLink%%		This is the "up one level" link on each page.
%%currDir%%		Current directory, in URL-encoded format.
%%newCurrDir%%		Same as %%currDir%% with leading "./" removed.
%%pageTitle%%		<TITLE> tag for this page.
%%youAreHere%%		This is the "you are here" path at the top of
			each page.
%%distURL%%		URL of MiG home page (value is hard-coded into
			index.php).
%%description%%		Description of the image, taken from the comments
			file(s).  For folders, this is <Bulletin>.

2. Tags used only in folder.html:

%%folderList%%		Expands to a section of <TABLE> code which
			displays a list of folders in the current folder.
%%imageList%%		Expands to a section of <TABLE> code which
			displays a list of images in the current folder.

3. Tags used only in image.html:

%%image%%		The current image being shown.
%%albumURLroot%%	Root URL of the actual album where images live
			(used in <IMG SRC="..."> HTML tags).
%%nextLink%%		A link to the "next" item in the sequence.
%%prevLink%%		A link to the "previous" item in the sequence.
%%currPos%%		Current position in the list (i.e. #5 of 7)
%%encodedImageURL%%	Image filename run through rawurlencode() in case
			there's a space embedded in it or something.
%%imageSize%%		HTML that gives WIDTH=nnn and HEIGHT=nnn tags
			for the image being displayed.


6. MANAGING COLORS
------------------

MiG uses a Cascading Style Sheet (CSS) file to manage all of its element
colorization.  Things like the page background, background colors for table
cells, all are managed by the CSS file templates/style.css.

I don't have the inclination or time to give a tutorial on how CSS works,
so please see http://www.htmlhelp.com/reference/css/ or whatever else you
come across to figure out how CSS works.  There are some books on this
topic available as well (try searching for "CSS" at Amazon.com).

A basic example or two follow, though.

  A. To change color of HREF links from #0000FF (blue) to #00FF00 (green):

          Before:      A:link    { color: #0000FF }
          After:       A:link    { color: #00FF00 }

  B. To change background color of description tables from #CCCCFF (grey) to
     #FF0000 (red):

	Before:
			TD.desc {
				color: #000000;
				background: #CCCCFF;
				text-align: justify;
			}

	After:
			TD.desc {
				color: #000000;
				background: #FF0000;
				text-align: justify;
			}

The "BODY" element controls the main background / text color for the pages
overall.  However, Netscape seems to have forgotten the BODY element when
implementing their CSS engine, so Netscape doesn't handle this correctly.
For that reason, a default coloration of white background / black text is
hard-coded into the HTML templates in the BODY element.  If you want to use
another colorization for BODY, feel free to do so, but be aware you'll need
to update both templates/style.css and templates/*.html to do it correctly.

