singapore - Advanced features

Info in file name

If singapore doesn't find a metadata file in a gallery it will try to extract some sensible information from the image file and directory names as follows:

Underscores (_) are converted to spaces and the file extension is discarded by removing all characters after the last . (dot) in the filename. If a filename or directory name contains the sequence '_-_' (underscore hyphen underscore) or ' - ' (space hyphen space) then the name will be split on this separator. The first half will be interpreted as the artist name and the second half will be interpreted as the gallery or image name depending on context. If a separator is not found then the file or directory name is interpreted as the image or gallery name, respectively.

For example Holiday_Snaps/Bob_Fenderson_-_Pretty_picture_of_Sunset.jpg will be translated into an image called "Pretty picture of Sunset" by "Bob Fenderson" in a gallery called "Holiday Snaps".

Overriding settings

All configuration options may be overridden on a per-gallery and/or per-template basis. This means that a particular gallery may use, for example, a different template or language to the rest of the site. Also, templates may introduce their own configuration settings if they so wish.

Gallery config options are stored in files named gallery.ini in the chosen gallery directory. Settings are not inherited by subgalleries; they affect only the current gallery and its images.

Template config options are stored in files named template.ini in the chosen template directory. Some of these settings are not present in the default config file; they are only found in the template config file.

Settings are loaded in this order: default settings (singapore.ini) > gallery settings (gallery.ini) > template settings (template.ini). This may be changed in the future to allow gallery settings to override template settings.

Note that there is no restriction on which options may be overridden. Overriding some settings may lead to unpredictable operation (e.g. changing pathto_galleries in gallery.ini).

Hiding galleries

Any gallery (except the root gallery) may be hidden from the listing view by prefixing the directory name with a dot (.). However it is still accessible by using its exact URL. For example consider the following directory structure:

galleries/
 |- my_pretty_pictures/
 |  |- trees/
 |  `- flowers/
 |- .a_hidden_gallery/
 |  |- some_embarrassing_pictures/
 |  `- .this_is_also_hidden/
 `- some_other_things/

A user browsing the root gallery (e.g. www.example.com/?gallery=.) will see my_pretty_pictures and some_other_things; .a_hidden_gallery and all its contents will be hidden from view. If, however, the user is supplied with the exact URL (e.g. www.example.com/?gallery=./.a_hidden_gallery) they will be able to see the contents as usual (in this case only some_embarrassing_pictures because .this_is_also_hidden is hidden as above).

Since a user could guess the exact URL or discover it by some other means, this feature is not to be used for concealing sensitive information.

NOTE: see the mod_rewrite section for instructions on renaming files starting with a . on Windows.

Using Apache mod_rewrite

Firstly you need to ensure that mod_rewrite is available. You must be running Apache, have mod-rewrite installed and enabled and furthermore be allowed to override Apache configuration directives on a per-directory basis with the use of .htaccess files.

If you don't know the answer to the above then probably the easiest way to find out is to try the following instructions.

First copy tools/mod_rewrite.htaccess to the singapore base directory and rename it to simply .htaccess. Note: Windows shines here as a Totally Idiotic Operating System® as it will not let you type filenames starting with a . kindly saying "You must type a filename". The only way that I know of to get around this totally pointless message is to drop into the command line and use ren to rename it. Aaaaaaaarrrrgggghhhh!

Moving swiftly on...

You now need to edit singapore.ini and turn on use_mod_rerwite. You also need to specify the base_url option. Set this to the full web absolute path to your installation (e.g. the bit after the .com, .org or whatever). For example if your gallery is accessed by typing www.example.com/singapore/ then the base_url is /singapore/.

Lastly you need to edit the .htaccess file. On each of the two lines starting RewriteRule, about half way along the line there is a /singapore/. Change this to whatever you put as the base_url above.

If it doesn't work

If you get 404 File Not Found errors then either mod_rewrite or .htaccess files are not enabled. If you get singapore Gallery not found errors then there might be a problem with the rewrite rules. If you get unstyled singapore pages with no images then then your base_path is probably wrong. If do get images but the pages are still unstyled then your template probably needs adapting to use the base_url config option. See the default template for an example. If you still can't work out what's wrong then just give up :P

Including singapore into another page

Since v0.9.10 it has been possible to include singapore into your web design using external.php. Just place this code where you want singapore to appear: <?php include("path/to/singapore/external.php");?> (supplying the correct relative or absolute path to singapore instead of '/path/to/singapore'). There are, however, a few things that need to be noted:

Opening images in a popup

Firstly I must say how much I disapprove of popups. If someone wants to open something in a new window THEY WILL DO IT THEMSELVES! Why do you think so many people have popup blockers? POPUPS ARE BAD! However I have been asked how to make singapore open images in popup windows so often that I finally yielded and wrote a little bit of JavaScript to do it neatly.

Open album.tpl.php in the directory of your current template (e.g. templates/default/album.tpl.php) and replace $sg->gallery->images[$index]->thumbnailLink() with $sg->gallery->images[$index]->thumbnailPopupLink(). But don't do it. It's bad.

Evil I tell you...

$Date: 2006/08/06 13:50:20 $