Mig - A general purpose photo gallery management system.

Copyright 2000-2002 Daniel M. Lowe (dan@tangledhelix.com)

LICENSE INFORMATION

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

A copy of the GPL can be found at http://www.gnu.org/copyleft/gpl.html or in the file docs/LICENSE.

REQUIREMENTS

This package requires a web server which supports PHP - http://www.php.net/ . Any recent version of PHP3 or any version of PHP4 should work. The development platform is Apple OSX, so this code tends to assume a Unix-like environment. As such it may or may not work (and has not been tested) on non-unix-like platforms.

(Windows users, please see the file docs/Windows.txt for more information.)

(PHP-Nuke users, plase see the file docs/phpNuke.txt for more information.)

The mkGallery utility (used to generate thumbnail images) requires Perl - http://www.perl.org and ImageMagick - http://www.imagemagick.org/ . You can use Mig without Perl or ImageMagick - but in that case you may have to create your own thumbnails and not use mkGallery. See the file docs/Utilities.txt. Since thumbnails are optional, you don't even need to generate them if you don't want to or it's not convenient for you.

The jhead utility which is called by mkGallery for EXIF header parsing is a C source code file - you will need to compile it before using it. See the file docs/Utilities.txt for more information. Since jhead is also optional you don't need to worry about this if you don't plan to extract embedded comment information from your JPEG files.

INSTALLATION AND BASICS

Installation is fairly straightforward.

NOTE: the following directions presume you have a unix shell on your server. If you have only FTP access, please refer to docs/FTPinstall.txt.

1. Unpack this archive and enter the resulting directory.

    gzip -dc mig-VERSION.tar.gz | tar xf -
    cd mig-VERSION

Where ``VERSION'' is the version of that archive (i.e. ``1.1'').

2. Run the install script install.sh and follow the directions.

    ./install.sh

(Windows users will not be able to use this shell script - see docs/Windows.txt for more information)

3. Enter the installation directory (which you specified during the installation).

    cd /usr/apache/htdocs/mig

4. Review the file config.php.default. If you want to make any changes, make them and then copy the file to config.php. The reason to do this is simple: future installations / upgrades will copy over config.php.default with whatever is packaged with that version of Mig. The config.php file will never be automatically over-written by the install script.

    vim config.php.default
        [ or if you are a heathen, use some other text editor :-) ]
        [ make desired changes ]
    cp config.php.default config.php

Or, if you are upgrading, it's a good idea to review config.php.default to see if there is anything new that you will want to add to your config.php.

(note to pre-1.3.1 users - the old ``mig.cfg'' file is now called ``config.php''. Rename your file - ``mig.cfg'' is now ignored.)

5. Enter the albums directory.

    cd albums

6. Create any folders and subfolders you want for your own albums, and copy your images into them.

    mkdir Trips
    mkdir Trips/Alberta,_Canada
    mkdir Trips/Lake_Tahoe,_California
    mkdir House
    mkdir House/Living\ Room
    mkdir House/Dining\ Room

You can of course, also do this with FTP, scp, or your favorite file handling method.

A note about spaces in gallery names: If there is a space embedded in the directory name, it is left as a space. If there's an underscore (_) in a directory name, it is displayed to the viewer as a space. So you can use whichever you like in your galleries and both will appear to be a space as far as the browser is concerned.

A note about files: Basically, any PNG, JPG or GIF file will be shown. That is, any file with an extension of .gif .jpg .jpe .jpeg or .gif. Note that case is irrelevant so ``.GIF'' is the same as ``.gif'' or ``.Gif''.

A note about file permissions: Mig makes no attempt to modify or check the file permissions in your album subdirectory. It is left to you to make sure the web server has the ability to read these files. On most systems this means making sure the directories are at least 0755 (which is drwxr-xr-x) and files are at least 0644 (-rw-r--r--). However, many people run their systems in such a way that those modes are considered dangerous to them, and I don't make any assumptions. Please validate the permissions on your albums to make sure the web server has access to read them.

Mig does set file permissions on the files it actually installs (the PHP files themselves, config.php.default, the templates, etc). If these are unsatisfactory to you (they should be perfectly fine for everyone as far as I can see), please let me know, and of course you can reset their permissions as you see fit on your system.

Thumbnails are the same filename as the images they represent, but they live in a subdirectory called ``thumbs'' (this name can be changed by editing config.php).

You can use spaces (or, as above, underscores) in filenames just like you can do with directory names. Underscores in filenames will be shown as-is though, they are not re-mapped to be displayed as a space.

7. You probably want to create thumbnails. You can use the mkGallery script found in the util subdirectory. Note that it requires Perl and the ImageMagick suite (see the file docs/Utilities.txt).

You don't have to use mkGallery - you can make your own thumbnails if you want. Just have them located in the ``thumbs'' subdirectory (or wherever you pointed that directory with $thumbSubdir).

To create thumbnails, in a nutshell:

    cd /usr/local/apache/htdocs/gallery/Trips/Lake_Tahoe,_California
    ../../util/mkGallery -a -t

See the file docs/Utilities.txt for more about mkGallery. You can get a listing of available options by invoking mkGallery with the -h flag.

The author finds mkGallery -rant to be the most useful mode for general purposes. Again, see docs/Utilities.txt for more information.

For mkGallery to create thumbnails, convert from the ImageMagick suite must be in your $PATH.

If you elect not to use thumbnails, a generic image icon will be used in place of a thumbnail image, so creating thumbnails is not mandatory (it just makes for a nicer presentation for people viewing your album).

mkGallery will only bother with the PNG, GIF or JPEG files it finds in the current directory (.gif .jpg .jpe .jpeg and .png).

As of version 1.1, you can use a global thumbnail extension for all thumbnails. For example if you want all thumbnails to be GIFs even if the real images they represent are something other than GIF, you can do this. See the -E option to mkGallery, and the $thumbExt option in config.php. Also see docs/Utilities.txt.

8. Go to http://www.yourserver.com/mig/ (or wherever you happened to install it) to view your gallery with your web browser.

You may have to tell your web server that index.php (or index.php3) is a valid default page. Apache users may need to add the filename to the DirectoryIndex directive (adding to the end of the line in your httpd.conf and running apachectl graceful as root is probably the way to do that). Other changes to Apache might be required to support PHP. How to get PHP to work in general is left as an exercise to the reader, but http://www.php.net/ and http://www.apache.org/ should have the necessary information.

OPTIONAL CUSTOMIZATION

1. HTML templates (and colors)

You may optionally edit the HTML templates found in the templates subdirectory. See the file docs/Templates.txt for more information. You can also use a custom per-folder template file in each folder if desired - see docs/mig_cf.txt for more information.

2. Hidden folders and hidden files

If you have some reason to hide particular files or folders from general view (i.e. it can be viewed but only with an exact URL, you don't want people wandering in there from the general public) you can list those items in a file called mig.cf in the relevant folder. As an example, look at albums/Example_Gallery/mig.cf (if you installed the Example Gallery).

To add hidden items, just add a <Hidden> element, like this:

    <Hidden>
    hidden_folder
    another_hidden_folder
    </Hidden>

Users of Apache will find this configuration format pretty familiar. Tag elements like <Hidden> must be at the beginning of a line!

See the file docs/mig_cf.txt for information about the format of mig.cf.

(Note for users upgrading from Mig 0.83 or earlier - the format has changed, as you'd have noticed already. If you need to convert to the new format, use the convert-metafiles script which is in the contrib section on the Mig home page).

Note that Hidden is not considered secure. If you need to make sure your gallery is secure, please take advantage of the password protection in your web server (if it has such a feature). You can also take advantage of Mig's built in password features (see docs/Passwords.txt). Mig's password protection isn't exactly secure either, but it's somewhat better than the Hidden mode.

3. Comments

You can optionally add comments for any image you wish. You don't have to add comments at all. The comments are stored in mig.cf in the same directory as the image in question.

Comments are shown in a box below the image in image views. In thumbnail views, they are shown as the ALT tag text. (You can suppress ALT tags by setting $suppressAltTags to TRUE in config.php).

As an example, let's say you had files house.jpg, car.gif and dog.jpg. Let's say you wanted a comment on the house and the dog, but nothing in particular to say about the car. You would add markup like this to mig.cf:

    <Comment "house.jpg">
    This is my house, which I bought in the fall of 1998.
    </Comment>
    <Comment "dog.jpg">
    This is the dog we had when I was growing up.  She was a lot of
    fun!  Sadly, she died when I was 12 years old (she had cancer).
    We had other dogs afterward, but none of them were as much fun.
    </Comment>

(If you want to save yourself some typing you can use the -c option to util/mkGallery to create a blank comments template. You can also use the -i option to enter comments interactively. See docs/Utilities.txt for more information.)

You can have as many lines as you want for the description. The key is that the description must be enclosed inside the <Comment>...</Comment> structure. The tags such as <Comment> and </Comment> MUST be at the start of a new line.


There are examples in F<albums/Example_Gallery/mig.cf> (if you installed
the example gallery).

See the file docs/mig_cf.txt for information about the format of mig.cf.

(Note for users upgrading from Mig 0.83 or earlier - the format has changed, as you'd have noticed already. The install script probably already updated your metafiles such as .comments.txt but if not, you can do so by hand by running convert-metafiles which is in the contrib directory on the Mig homepage).

4. EXIF header information

You can build EXIF comment files (exif.inf) using mkGallery and the -e option. See the file docs/Utilities.txt. Note that you must compile the (included) jhead utility from Matthias Wandel before the -e option will function. Compiling jhead is probably as easy as this on a typical Unix or Linux system:

    cd util/jhead ; make clean ; make

Since only JPEG files support EXIF headers, mkGallery will only look at JPEG files when building the EXIF files. Much more than the comments themselves are stored in these exif.inf files, and future versions of Mig may parse more information from these files than it currently does. Right now all Mig knows how to extract from the exif.inf file is embedded comments.

NOTE that most graphic editors destroy EXIF blocks! They don't know how to write them so when they save images, they are simply not written back into the file. You can get around this by building the EXIF data using your raw images, and then editing them afterward. This may not be an option for everybody, but there's nothing I can do about it.

(Note for users upgrading from Mig 0.83 or earlier - the filename has changed, as you'd have noticed already. The install script probably already updated your metafiles such as .exif_comments.txt but if not, you can do so by hand by running convert-metafiles which is in the contrib directory on the Mig home page. The only change for EXIF files is the filename, just rename to exif.inf).

5. Style sheets

You can modify the file templates/style.css if you want to change the text/css style (which is what determines link coloring). If you don't want to use the style.css file, remove the #include directive from the HTML templates which includes it in the template. For more information see docs/Templates.txt.

6. Item sorting

You can define your own sort order (rather than relying on alphabetical sorting) - see docs/mig_cf.txt.

7. Symlinks

You can create virtual collections and cross-linking among your albums by simply using symbolic links. For instance you can do stuff like:

    cd albums
    mkdir People ; cd People
    mkdir Katie ; cd Katie
    ln -s ../../Birthdays/Katie_2000 .

And you end up with the ``Birthdays : Katie 2000'' folder as a virtual folder under the ``People : Katie'' folder. In this way you can have a folder in more than one place at the same time without having a need for more than one copy of the photo on the disk.

I have only tested that under Apache with PHP3. And of course it probably won't work in Windows because as far as I know, FAT32 and NTFS do not support symbolic links in the first place. I do not know if Windows shortcuts (.LNK files) will work instead.

8. Thumbnail image information

Some people may not like to have the ``540KB, 640x480'' type stuff to be displayed below each thumbnail. If you don't want it there, see the $suppressImageInfo option in config.php.default. Setting that to TRUE has the effect of showing thumbnails as images only - no other information is shown about each image.

9. For Apache users only

If you are using the popular Apache web server, see docs/Apache.txt for some useful Apache-specific tips and tricks.

10. Password protected folders

Mig can password-protect folders, or collections of folders. See docs/Passwords.txt for more information. Note that Mig's password protection isn't absolutely secure, so don't use it if you require really tight security on your images.

11. Thumbnail suppression

Some people don't want to have thumbnails whatsoever. For those people the $noThumbs switch exists in the config.php file. Setting $noThumbs to TRUE has the effect of not using thumbnail images at all in your albums. $noThumbs is set to FALSE by default.

12. Forcing a thumbnail type

Some people expressed a desire to have all thumbnails be a certain type no matter what their normal images were. For example, main images might be JPG or GIF but all thumbnails would be GIF, regardless.

By default, if an image is a JPG, Mig will also look for a JPG thumbnail. A GIF image will have a GIF thumbnail.

If you wish to use all the same type for thumbnails even if the real image is a different type (or varying types), set the value of $thumbExt in config.php to the extension you are using. Note that case does matter, so setting it to gif and uploading foo.GIF will result in an error!

13. Languages other than English

Mig has support for other languages - however, it only supports those languages someone has supplied translations for. As I write this, that means English and French. If you want to translate it to another language, please get in touch with me and I'll be glad to add your translations to the available list of languages.

(see config.php.default for more information - Mig now supports English, French, German, Norwegian, Portugese, Finnish, Romanian, Russian Windows-1251, Russian KOI8-R, Turkish, Swedish, Danish, Italian, Spanish, Slovak, Dutch and Polish).

14. Pop-up windows

If you want to use Pop-up windows for your images, see the $imagePopup and $imagePopType variables in config.php.

BUG REPORTING

You can report bugs in one of two ways. The first way is to submit a bug report on the Mig project page at

    http://sourceforge.net/projects/mig/

The second is to send an email to dan@tangledhelix.com.

WISH LIST

You can submit items to the wish list in one of two ways. The first way is to submit a Feature Request on the Mig project page at

    http://sourceforge.net/projects/mig/

The second is to send an email to dan@tangledhelix.com.

EMAIL LISTS

There are two mailing lists related to Mig. Visit the URLs below if you wish to subscribe. Both lists are currently fairly low-traffic.

mig-announce is an announcements-only list. New versions and so forth are announced on this list.

    http://lists.sourceforge.net/lists/listinfo/mig-announce

mig-users is a general discussion list. Any mig-related topic can be discussed on this list. Note also that I typically send announcements here, so if you subscribe to mig-users you don't necessarily have to subscribe to mig-announce as well (but you can if you want to).

    http://lists.sourceforge.net/lists/listinfo/mig-users