This document aims to explain how mig.cf works and what it is.
Each folder under the album subdirectory can optionally have a mig.cf file in it. This file contains things like image comments, a list of hidden items (if any) and so on.
The format is borrowed from the config file format of Apache, and is sort of similar to HTML. Hopefully this means that it will be simple for most people to figure out and use.
An example mig.cf might look like this:
# Beginning of example mig.cf
#
<Bulletin>
We spent four days in Rome. Even with four whole days to tour
the area, we found we couldn't cover everything. The Vatican
alone took most of the second day, and we only saw half of it.
</Bulletin>
<Comment "AUT_2323.JPG">
Massive mosaic found in the Basilica of Saint Peter in the Vatican.
</Comment>
<Comment "AUT_2406.JPG">
The Colloseum of Rome.
</Comment>
#
# End of example mig.cf
An element is opened by a tag (such as <Bulletin>), and closed by the associated close-tag (the tag with its name preceded by a slash) such as </Bulletin>.
An element can have an argument, as in <Comment "AUT_2406.JPG">.
These tags must be at the beginning of a line. Case in the tag name is not important, so <Comment> is the same as <comment> or <CoMMenT>.
(If you installed the example gallery, look inside for mig.cf files for some useful examples.)
Any line starting with # is considered a remark and is ignored by Mig.
Blank lines are also ignored. Neither are ignored inside an element block
such as <comment>, so it's best if they don't appear inside blocks.
If you are editing mig.cf files using a Windows text editor, you may want to leave one or more blank lines at the end of the file. Some Windows text editors apparently don't add end-of-line characters to the end of the last line in the file, and this confuses Mig.
<Bulletin>
[some text]
</Bulletin>
A bulletin is just like a comment, only it's attached to the folder rather than a single image. An example is shown near the top of this document.
<Comment "image_file">
[some text]
</Comment>
A comment is attached to an image. When viewing that image, the comment text associated with it will be displayed in a box below the image. An example can be found near the top of this file.
The argument to Comment must be enclosed in quotes so Mig can properly
recognize files with spaces in their names.
As of 0.90, comments are loaded into the ALT tag of thumbnail images, so you can hover over an image and view its description. (As of 1.3.0 they're also loaded into the TITLE modifier for better cross-browser compatibility).
Certain HTML elements don't mix well with ALT and TITLE, and should be
avoided, notably things like <A HREF>. You can turn ALT/TITLE
tags off if you wish, by setting $suppressAltTags to TRUE in
config.php.
<Short "image_file">
[some text]
</Short>
Sometimes you want a long comment on the image itself, but a shorter one used in the ALT and TITLE tags on the thumbnail page (for hovering over links). You can use the <Short> tag in mig.cf files for that. This element works just like <Comment> except that it is used only in the hover-over tags on thumbnail pages.
If there is a <Comment> block but no <Short> block for an image, the <Comment> block will be used for the hover-over.
FolderIcon folder_name icon_file.gif
It is sometimes desirable to use a custom icon for a given folder.
This can be done using the FolderIcon entity. Given a folder
Trips/Rome, and an icon colloseum.gif, the following can be
defined in Trips/mig.cf:
FolderIcon Rome colloseum.gif
The colloseum.gif file should be placed in Mig's images folder, located in the root directory of your Mig installation.
If you are using $randomFolderThumbs, note that FolderIcon overrides
that setting.
If you want to use a specific thumbnail for a given directory as its
folder icon, you instead want to look at the UseThumb directive.
UseThumb folder_name image_name
To pick a specific image to use as a thumbnail for your folder, use the
UseThumb directive. The thumbnail file associated with that image will
be displayed as the folder's icon.
UseThumb Rome IMG_4935.JPG
In that case, the image IMG_4935.JPG, which should be located in the Rome folder, will be used as the folder's icon.
FolderTemplate /path/to/file.tmpl
FolderTemplate file.tmpl
It is sometimes desirable to use a custom template for a given folder
rather than using the site-wide template. This can be defined with the
FolderTemplate entity.
If the FolderTemplate entity is followed by a filename, the file is
assumed to be in the folder in question.
If the FolderTemplate entity is followed by a full file path, beginning
with a / character, that full path is instead used.
PageTitle This is my Page Title for this Folder
A folder-specific page title can be defined with the PageTitle entity,
as shown above. This will override the site-wide page title on a
folder-by-folder basis.
MaintAddr joe@mama.com
A folder-specific maintainer email address can be specified using the
MaintAddr entity. This will override the site-wide value $maintAddr.
This is handy in the case where different folders site are really owned by different people.
MaxFolderColumns 2
MaxThumbColumns 4
MaxFolderColumns overrides the site-wide value $maxFolderColumns in a
given folder.
MaxThumbColumns overrides the site-wide value $maxThumbColumns in a
given folder.
<Hidden>
[item]
[item]
</Hidden>
Hidden elements are lists of items which are invisible to the browser.
This is useful for things that should not be publicly viewable, or for
album directories that exist but are not yet complete. Each line between
the start and end tags is either a file or a directory (Mig can sort out
which is which on its own).
<Hidden>
New folder
England
</Hidden>
Hidden is not considered a security feature. It's not difficult for
someone to get around this if they know the name of the folder or image
being hidden. This is security through obscurity (which is only one step
above no security).
<Sort>
[item]
[item]
</Sort>
By default, items are sorted by their ASCII value (for the purpose of this discussion, this is close to being alphabetically). However, it can be desirable to control the order in which items (either images or folders) appear.
For example, this is what the contents of a directory might look like:
Ceremony/ Cut the Cake/ Home/ Reception/ Cigars/
AUT_3706.JPG AUT_3712.JPG AUT_3714.JPG AUT_3716.JPG
AUT_3707.JPG AUT_3713.JPG AUT_3715.JPG AUT_3717.JPG
Note that the first five are directories, and the other eight are files. This will display by default as a list of folders, then a list of images, each list in alphabetical (ASCII) order.
Let's say that Home should move to the top of the list and Cigars to just above Reception.
<Sort>
Home
Ceremony
Cutting the Cake
Cigars
Reception
</Sort>
Now let's move images 3716 and 3717 to the third and fourth position in the list of images.
<Sort>
AUT_3706.JPG
AUT_3707.JPG
AUT_3716.JPG
AUT_3717.JPG
</Sort>
Attentive readers will have noticed that there are four images that aren't even mentioned here. What happens to them? They're sorted alphabetically independently of the pre-sorted list, and tacked on afterward. The final list would be:
AUT_3706.JPG
AUT_3707.JPG
AUT_3716.JPG
AUT_3717.JPG
AUT_3712.JPG
AUT_3713.JPG
AUT_3714.JPG
AUT_3715.JPG
If everything goes into one <sort> block, Mig can figure it out (which are files, which are directories). This is arguably sloppy from the point of view of a human though. It's easier to define multiple sort blocks in those situations; one for files, one for directories. Mig can detect and use multiple sort blocks.
See the apache document if you are running Apache and would like to prevent people from browsing your mig.cf and/or exif.inf files.