<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>singapore - Advanced features</title>
<link rel="stylesheet" type="text/css" href="docstyle.css" />
</head>

<body>


<h1>singapore - Advanced features</h1>

<ul>
  <li><a href="#iifn">Info in filename</a></li>
  <li><a href="#override">Overriding settings</a></li>
  <li><a href="#hiding">Hiding galleries</a></li>
  <li><a href="#modrewrite">Using Apache mod_rewrite</a></li>
  <li><a href="#including">Including singapore into another page</a></li>
  <li><a href="#popup">Opening images in a popup</a></li>
  <li><a href="Readme.html">General readme</a></li>
  <li><a href="Development.html">Developer documentation</a></li>
  <li><a href="Translation.html">Translating singapore</a></li>
</ul>

<h2><a name="iifn">Info in file name</a></h2>

<p>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:</p>

<p>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 '<code>_-_</code>' (underscore hyphen underscore) 
or '<code> - </code>' (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.</p>

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


<h2><a name="override">Overriding settings</a></h2>

<p>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.</p>

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

<p>Template config options are stored in files named <code>template.ini</code> 
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.</p>

<p>Settings are loaded in this order: default settings (<code>singapore.ini</code>)
&gt; gallery settings (<code>gallery.ini</code>) &gt; template settings 
(<code>template.ini</code>). This may be changed in the future to allow gallery 
settings to override template settings.</p>

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


<h2><a name="hiding">Hiding galleries</a></h2>

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

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

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

<p>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.</p>

<p>NOTE: see the <a href="#modrewrite">mod_rewrite</a> section for instructions 
on renaming files starting with a . on Windows.</a></p>


<h2><a name="modrewrite">Using Apache mod_rewrite</a></h2>

<p>Firstly you need to ensure that mod_rewrite is available. You must be running
<a href="http://httpd.apache.org/">Apache</a>, 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.</p>

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

<p>First copy <code>tools/mod_rewrite.htaccess</code> to the singapore base 
directory and rename it to simply <code>.htaccess</code>. Note: Windows shines
here as a Totally Idiotic Operating System&reg; 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 <code>ren</code> to rename it. Aaaaaaaarrrrgggghhhh!</p>

<p>Moving swiftly on...</p>

<p>You now need to edit singapore.ini and turn on <code>use_mod_rerwite</code>. 
You also need to specify the <code>base_url</code> 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 <code>base_url</code> is 
<code>/singapore/</code>.</p>

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

<h3>If it doesn't work</h3>

<p>If you get <em>404 File Not Found</em> errors then either mod_rewrite or .htaccess 
files are not enabled. If you get singapore <em>Gallery not found</em> 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</p>

<h2><a name="including">Including singapore into another page</a></h2>

<p>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: 
<code>&lt;?php include("path/to/singapore/external.php");?&gt;</code> (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:</p>

<ul>
  <li>You will almost certainly need to edit your chosen template in order that
  the HTML generated is still valid. For example you do not want two &lt;html&gt; 
  start tags, two &lt;head&gt; sections etc. Alternatively you can use the 
  <em>external</em> template (available to download from the website) which is 
  the default template with the unnecessary (X)HTML removed.</li>
  <li>If the file into which you are including singapore is named something 
  other than index.php or it requires additional GET variables (such as page etc.)
  then you will need to change index_file_url to reflect this. For example if 
  the page you are including singapore into is <code>site.php?page=gallery</code>
  you will need to change index_file_url to <code>site.php?page=gallery&amp;amp;</code></li>
  <li>If you want to keep both the included singapore installation and the 
  original simultaneously functional then you can place a file named 
  <code>singapore.local.ini</code> in the same directory as the including file. 
  If found, this file will be loaded after singapore.ini but before gallery.ini 
  and template.ini. It can thus be used to provide local settings such as index_file_url
  mentioned above. Note that base_file and base_url are automatically calculated 
  and should not need to be specified.</li>
  <li>If there is any content on the including page <em>before</em> external.php is
  included then singapore will not be able to send any headers which will 
  prevent you from using languages with non-default character sets. The 
  recommended solution is to turn on output buffering before any content is 
  output and do not flush it until after external.php is included. Essentially 
  a call to <code>ob_start()</code> at the beginning of the including file is 
  all that is needed. <a href="http://uk.php.net/manual/en/ref.outcontrol.php">About 
  output control</a>.</li>
  <li>Currently mod_rewrite doesn't work with such included installations of singapore.</li>
</ul>

<h2><a name="popup">Opening images in a popup</a></h2>

<p>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.</p>

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

<p>Evil I tell you...</p>

<p><em>$Date: 2006/08/06 13:50:20 $</em></p>

</body>
</html>