Template files give you some control of the layout of output pages. Colors are also handled by the template files (see later 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.
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 later in this document.
If you don't know anything about HTML you can try checking out http://www.htmlhelp.com/ or looking for some other online help sites by using a search engine such as Yahoo.
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.
If the file mentioned by #include
is a CGI file then it will be executed, and its output will be placed there
instead. NOTE: CGI can only be used if you are using an Apache server (and
not even every installation of Apache will do this correctly). Sorry, it's
a limitation in PHP that I can't work around.
If you are including a CGI make sure it prints appropriate HTTP headers before anything else (just like any other situation where you use CGI).
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. As of version 1.2.5 you can include PHP files as well as other types of files. The one difference is that for PHP files you have to make sure the filename has an extension of either ``.php'' or ``.php3''
Look at either image.html or folder.html for an example (#include
is used to embed the CSS style sheet file style.css
).
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.
If you are running MiG in PHP-Nuke Compatible mode (see docs/phpNuke.txt) then these three files are not used. In their place you will instead find:
templates/mig_folder.php - Used for folder/thumbnail views
templates/mig_image.php - Used for ``single image'' views
(The CSS style sheet is not used in PHP-Nuke mode because PHP-Nuke uses its own CSS style system and MiG aims not to interfere with that.)
The following is 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 (or mig_folder.php in phpNuke mode):
%%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 (or mig_image.php in phpNuke mode):
%%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.
If desired, one can define a per-folder template file. This can be done
with the FolderTemplate
entity, as discussed in docs/mig_cf.txt.
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.
(Note that if you are using ``PHP-Nuke Compatible'' mode, CSS is ignored because PHP-Nuke uses its own CSS styles. See docs/phpNuke.txt.)
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.
To change color of HREF links from #0000FF
(blue) to #00FF00
(green):
Before: A:link { color: #0000FF } After: A:link { color: #00FF00 }
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.