Copyright (C) 2000-2001 Dan Lowe (dan@tangledhelix.com)
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.
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 Solaris, 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 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 mig.cfg.default. If you want to make any changes, make them and then copy the file to mig.cfg. The reason to do this is simple: future installations / upgrades will copy over mig.cfg.default with whatever is packaged with that version of MiG. The mig.cfg file will never be automatically over-written by the install script.
vim mig.cfg.default [ or if you are a heathen, use some other text editor :-) ] [ make desired changes ] cp mig.cfg.default mig.cfg
Or, if you are upgrading, it's a good idea to review mig.cfg.default to see if there is anything new that you will want to add to your mig.cfg.
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, mig.cfg.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 basically seen by MiG as anything that matches the basic
pattern filename_th.EXT
... so myhouse_th.gif
will be viewed as a thumbnail. The basic rule of thumb is, try not to use
the string _th
in your filenames.
Note, as of 0.90 this behavior changed. This is still true of the default settings, but you now have the ability to control the format of thumbnail filenames. See docs/Utilities.txt and mig.cfg.default.
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.
Also, thumbnails can live in a subdirectory rather than in the main folder - see below under ``Optional Customization''.
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 the filenames match the pattern shown above. So...
myHouse.jpg = myHouse_th.jpg Livingroom.JPG = Livingroom_th.JPG
Case does matter for the _th
- it must be lowercase!
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.
Note that not all thumbnails have to use _th as their "unique" part anymore. See docs/Utilities.txt. You can make them anything you want, and can even "prefix" them to the filename instead of suffixing them.
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 thumbnail subdirectory rather than having your thumbnails co-exist in the same folder with the images they represent. See below under ``Optional customization'' for more info.
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 mig.cfg. 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.
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.
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 mig.cfg).
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 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 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 mig.cfg.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 subdirectories
Some users don't like having their thumbnails littering up their folders
alongside their images. For those users, the $useThumbSubdir
option exists.
Basically to use this, one would create a subdirectory in each folder (perhaps called thumbs). Thumbnails in that subdirectory would have the exact same name as their full-size counterparts in the main folder. This is different than the old behavior where you were forced to use two different filenames.
See docs/Utilities.txt for information about this option and
mkGallery. Also see mig.cfg.default for the $useThumbSubdir
and
$thumbSubdir
parameters. By default, thumbnail subdirectories are not used (for
historical reasons).
12. Thumbnail suppression
Some people don't want to have thumbnails whatsoever. For those people the
$noThumbs
switch exists in the mig.cfg 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.
13. 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 mig.cfg 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!
14. 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 mig.cfg.default for more information - MiG now supports English, French, German, Norwegian, Portugese, Finnish, Romanian, Russian Windows-1251, Russian KOI8-R, Turkish, Swedish and Danish)
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 mig-bugs@tangledhelix.com
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 mig-wishlist@tangledhelix.com
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