Rev 229 Rev 234
1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
2 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 2 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3   3  
4 <html xmlns="http://www.w3.org/1999/xhtml"> 4 <html xmlns="http://www.w3.org/1999/xhtml">
5 <head> 5 <head>
6 <title>singapore - Advanced features</title> 6 <title>singapore - Advanced features</title>
7 <link rel="stylesheet" type="text/css" href="docstyle.css" /> 7 <link rel="stylesheet" type="text/css" href="docstyle.css" />
8 </head> 8 </head>
9   9  
10 <body> 10 <body>
11   11  
12   12  
13 <h1>singapore - Advanced features</h1> 13 <h1>singapore - Advanced features</h1>
14   14  
15 <ul> 15 <ul>
16 <li><a href="#iifn">Info in filename</a></li> 16 <li><a href="#iifn">Info in filename</a></li>
17 <li><a href="#override">Overriding settings</a></li> 17 <li><a href="#override">Overriding settings</a></li>
18 <li><a href="#hiding">Hiding galleries</a></li> 18 <li><a href="#hiding">Hiding galleries</a></li>
19 <li><a href="#modrewrite">Using Apache mod_rewrite</a></li> 19 <li><a href="#modrewrite">Using Apache mod_rewrite</a></li>
20 <li><a href="#including">Including singapore into another page</a></li> 20 <li><a href="#including">Including singapore into another page</a></li>
21 <li><a href="#popup">Opening images in a popup</a></li> 21 <li><a href="#popup">Opening images in a popup</a></li>
22 <li><a href="Readme.html">General readme</a></li> 22 <li><a href="Readme.html">General readme</a></li>
23 <li><a href="Development.html">Developer documentation</a></li> 23 <li><a href="Development.html">Developer documentation</a></li>
24 <li><a href="Translation.html">Translating singapore</a></li> 24 <li><a href="Translation.html">Translating singapore</a></li>
25 </ul> 25 </ul>
26   26  
27 <h2><a name="iifn">Info in file name</a></h2> 27 <h2><a name="iifn">Info in file name</a></h2>
28   28  
29 <p>If singapore doesn't find a metadata file in a gallery it will try to 29 <p>If singapore doesn't find a metadata file in a gallery it will try to
30 extract some sensible information from the image file and directory names as 30 extract some sensible information from the image file and directory names as
31 follows:</p> 31 follows:</p>
32   32  
33 <p>Underscores (_) are converted to spaces and the file extension is discarded 33 <p>Underscores (_) are converted to spaces and the file extension is discarded
34 by removing all characters after the last . (dot) in the filename. If a filename or 34 by removing all characters after the last . (dot) in the filename. If a filename or
35 directory name contains the sequence '<code>_-_</code>' (underscore hyphen underscore) 35 directory name contains the sequence '<code>_-_</code>' (underscore hyphen underscore)
36 or '<code> - </code>' (space hyphen space) then the name will be split on this 36 or '<code> - </code>' (space hyphen space) then the name will be split on this
37 separator. The first half will be interpreted as the artist name and the second 37 separator. The first half will be interpreted as the artist name and the second
38 half will be interpreted as the gallery or image name depending on context. If 38 half will be interpreted as the gallery or image name depending on context. If
39 a separator is not found then the file or directory name is interpreted as the 39 a separator is not found then the file or directory name is interpreted as the
40 image or gallery name, respectively.</p> 40 image or gallery name, respectively.</p>
41   41  
42 <p>For example <code>Holiday_Snaps/Bob_Fenderson_-_Pretty_picture_of_Sunset.jpg</code> 42 <p>For example <code>Holiday_Snaps/Bob_Fenderson_-_Pretty_picture_of_Sunset.jpg</code>
43 will be translated into an image called "Pretty picture of Sunset" by "Bob 43 will be translated into an image called "Pretty picture of Sunset" by "Bob
44 Fenderson" in a gallery called "Holiday Snaps".</p> 44 Fenderson" in a gallery called "Holiday Snaps".</p>
45   45  
46   46  
47 <h2><a name="override">Overriding settings</a></h2> 47 <h2><a name="override">Overriding settings</a></h2>
48   48  
49 <p>All configuration options may be overridden on a per-gallery and/or 49 <p>All configuration options may be overridden on a per-gallery and/or
50 per-template basis. This means that a particular gallery may use, for example, 50 per-template basis. This means that a particular gallery may use, for example,
51 a different template or language to the rest of the site. Also, templates may 51 a different template or language to the rest of the site. Also, templates may
52 introduce their own configuration settings if they so wish.</p> 52 introduce their own configuration settings if they so wish.</p>
53   53  
54 <p>Gallery config options are stored in files named <code>gallery.ini</code> in 54 <p>Gallery config options are stored in files named <code>gallery.ini</code> in
55 the chosen gallery directory. Settings are not inherited by subgalleries; they 55 the chosen gallery directory. Settings are not inherited by subgalleries; they
56 affect only the current gallery and its images.</p> 56 affect only the current gallery and its images.</p>
57   57  
58 <p>Template config options are stored in files named <code>template.ini</code> 58 <p>Template config options are stored in files named <code>template.ini</code>
59 in the chosen template directory. Some of these settings are not present in the 59 in the chosen template directory. Some of these settings are not present in the
60 default config file; they are only found in the template config file.</p> 60 default config file; they are only found in the template config file.</p>
61   61  
62 <p>Settings are loaded in this order: default settings (<code>singapore.ini</code>) 62 <p>Settings are loaded in this order: default settings (<code>singapore.ini</code>)
63 &gt; gallery settings (<code>gallery.ini</code>) &gt; template settings 63 &gt; gallery settings (<code>gallery.ini</code>) &gt; template settings
64 (<code>template.ini</code>). This may be changed in the future to allow gallery 64 (<code>template.ini</code>). This may be changed in the future to allow gallery
65 settings to override template settings.</p> 65 settings to override template settings.</p>
66   66  
67 <p>Note that there is no restriction on which options may be overridden. 67 <p>Note that there is no restriction on which options may be overridden.
68 Overriding some settings may lead to unpredictable operation (e.g. changing 68 Overriding some settings may lead to unpredictable operation (e.g. changing
69 <code>pathto_galleries</code> in <code>gallery.ini</code>).</p> 69 <code>pathto_galleries</code> in <code>gallery.ini</code>).</p>
70   70  
71   71  
72 <h2><a name="hiding">Hiding galleries</a></h2> 72 <h2><a name="hiding">Hiding galleries</a></h2>
73   73  
74 <p>Any gallery (except the root gallery) may be hidden from the listing view 74 <p>Any gallery (except the root gallery) may be hidden from the listing view
75 by prefixing the directory name with a dot (<code>.</code>). However it is still 75 by prefixing the directory name with a dot (<code>.</code>). However it is still
76 accessible by using its exact URL. For example consider the following directory 76 accessible by using its exact URL. For example consider the following directory
77 structure:</p> 77 structure:</p>
78   78  
79 <pre> 79 <pre>
80 galleries/ 80 galleries/
81 |- my_pretty_pictures/ 81 |- my_pretty_pictures/
82 | |- trees/ 82 | |- trees/
83 | `- flowers/ 83 | `- flowers/
84 |- .a_hidden_gallery/ 84 |- .a_hidden_gallery/
85 | |- some_embarrassing_pictures/ 85 | |- some_embarrassing_pictures/
86 | `- .this_is_also_hidden/ 86 | `- .this_is_also_hidden/
87 `- some_other_things/ 87 `- some_other_things/
88 </pre> 88 </pre>
89   89  
90 <p>A user browsing the root gallery (e.g. <code>www.example.com/?gallery=.</code>) 90 <p>A user browsing the root gallery (e.g. <code>www.example.com/?gallery=.</code>)
91 will see <code>my_pretty_pictures</code> and <code>some_other_things</code>; 91 will see <code>my_pretty_pictures</code> and <code>some_other_things</code>;
92 <code>.a_hidden_gallery</code> and all its contents will be hidden from view. If, 92 <code>.a_hidden_gallery</code> and all its contents will be hidden from view. If,
93 however, the user is supplied with the exact URL (e.g. <code>www.example.com/?gallery=./.a_hidden_gallery</code>) 93 however, the user is supplied with the exact URL (e.g. <code>www.example.com/?gallery=./.a_hidden_gallery</code>)
94 they will be able to see the contents as usual (in this case only 94 they will be able to see the contents as usual (in this case only
95 <code>some_embarrassing_pictures</code> because <code>.this_is_also_hidden</code> 95 <code>some_embarrassing_pictures</code> because <code>.this_is_also_hidden</code>
96 is hidden as above).</p> 96 is hidden as above).</p>
97   97  
98 <p>Since a user could guess the exact URL or discover it by some other means, 98 <p>Since a user could guess the exact URL or discover it by some other means,
99 this feature is not to be used for concealing sensitive information.</p> 99 this feature is not to be used for concealing sensitive information.</p>
100   100  
101 <p>NOTE: see the <a href="#modrewrite">mod_rewrite</a> section for instructions 101 <p>NOTE: see the <a href="#modrewrite">mod_rewrite</a> section for instructions
102 on renaming files starting with a . on Windows.</a></p> 102 on renaming files starting with a . on Windows.</a></p>
103   103  
104   104  
105 <h2><a name="modrewrite">Using Apache mod_rewrite</a></h2> 105 <h2><a name="modrewrite">Using Apache mod_rewrite</a></h2>
106   106  
107 <p>Firstly you need to ensure that mod_rewrite is available. You must be running 107 <p>Firstly you need to ensure that mod_rewrite is available. You must be running
108 <a href="http://httpd.apache.org/">Apache</a>, have mod-rewrite installed and 108 <a href="http://httpd.apache.org/">Apache</a>, have mod-rewrite installed and
109 enabled and furthermore be allowed to override Apache configuration directives 109 enabled and furthermore be allowed to override Apache configuration directives
110 on a per-directory basis with the use of .htaccess files.</p> 110 on a per-directory basis with the use of .htaccess files.</p>
111   111  
112 <p>If you don't know the answer to the above then probably the easiest way to 112 <p>If you don't know the answer to the above then probably the easiest way to
113 find out is to try the following instructions.</p> 113 find out is to try the following instructions.</p>
114   114  
115 <p>First copy <code>tools/mod_rewrite.htaccess</code> to the singapore base 115 <p>First copy <code>tools/mod_rewrite.htaccess</code> to the singapore base
116 directory and rename it to simply <code>.htaccess</code>. Note: Windows shines 116 directory and rename it to simply <code>.htaccess</code>. Note: Windows shines
117 here as a Totally Idiotic Operating System&reg; as it will not let you type 117 here as a Totally Idiotic Operating System&reg; as it will not let you type
118 filenames starting with a . kindly saying "You must type a filename". The only 118 filenames starting with a . kindly saying "You must type a filename". The only
119 way that I know of to get around this totally pointless message is to drop into 119 way that I know of to get around this totally pointless message is to drop into
120 the command line and use <code>ren</code> to rename it. Aaaaaaaarrrrgggghhhh!</p> 120 the command line and use <code>ren</code> to rename it. Aaaaaaaarrrrgggghhhh!</p>
121   121  
122 <p>Moving swiftly on...</p> 122 <p>Moving swiftly on...</p>
123   123  
124 <p>You now need to edit singapore.ini and turn on <code>use_mod_rerwite</code>. 124 <p>You now need to edit singapore.ini and turn on <code>use_mod_rerwite</code>.
125 You also need to specify the <code>base_url</code> option. Set this to the full 125 You also need to specify the <code>base_url</code> option. Set this to the full
126 web absolute path to your installation (e.g. the bit after the .com, .org or 126 web absolute path to your installation (e.g. the bit after the .com, .org or
127 whatever). For example if your gallery is accessed by typing 127 whatever). For example if your gallery is accessed by typing
128 www.example.com/singapore/ then the <code>base_url</code> is 128 www.example.com/singapore/ then the <code>base_url</code> is
129 <code>/singapore/</code>.</p> 129 <code>/singapore/</code>.</p>
130   130  
131 <p>Lastly you need to edit the .htaccess file. On each of the two lines starting 131 <p>Lastly you need to edit the .htaccess file. On each of the two lines starting
132 <code>RewriteRule</code>, about half way along the line there is a 132 <code>RewriteRule</code>, about half way along the line there is a
133 <code>/singapore/</code>. Change this to whatever you put as the <code>base_url</code> 133 <code>/singapore/</code>. Change this to whatever you put as the <code>base_url</code>
134 above.</p> 134 above.</p>
135   135  
136 <h3>If it doesn't work</h3> 136 <h3>If it doesn't work</h3>
137   137  
138 <p>If you get <em>404 File Not Found</em> errors then either mod_rewrite or .htaccess 138 <p>If you get <em>404 File Not Found</em> errors then either mod_rewrite or .htaccess
139 files are not enabled. If you get singapore <em>Gallery not found</em> errors 139 files are not enabled. If you get singapore <em>Gallery not found</em> errors
140 then there might be a problem with the rewrite rules. If you get unstyled 140 then there might be a problem with the rewrite rules. If you get unstyled
141 singapore pages with no images then then your base_path is probably wrong. If do 141 singapore pages with no images then then your base_path is probably wrong. If do
142 get images but the pages are still unstyled then your template probably needs 142 get images but the pages are still unstyled then your template probably needs
143 adapting to use the base_url config option. See the default template for an 143 adapting to use the base_url config option. See the default template for an
144 example. If you still can't work out what's wrong then just give up :P</p> 144 example. If you still can't work out what's wrong then just give up :P</p>
145   145  
146 <h2><a name="including">Including singapore into another page</a></h2> 146 <h2><a name="including">Including singapore into another page</a></h2>
147   147  
148 <p>Since v0.9.10 it has been possible to include singapore into your web design 148 <p>Since v0.9.10 it has been possible to include singapore into your web design
149 using external.php. Just place this code where you want singapore to appear: 149 using external.php. Just place this code where you want singapore to appear:
150 <code>&lt;?php include("path/to/singapore/external.php");?&gt;</code> (supplying 150 <code>&lt;?php include("path/to/singapore/external.php");?&gt;</code> (supplying
151 the correct relative or absolute path to singapore instead of 151 the correct relative or absolute path to singapore instead of
152 '/path/to/singapore'). There are, however, a few things that need to be noted:</p> 152 '/path/to/singapore'). There are, however, a few things that need to be noted:</p>
153   153  
154 <ul> 154 <ul>
155 <li>You will almost certainly need to edit your chosen template in order that 155 <li>You will almost certainly need to edit your chosen template in order that
156 the HTML generated is still valid. For example you do not want two &lt;html&gt; 156 the HTML generated is still valid. For example you do not want two &lt;html&gt;
157 start tags, two &lt;head&gt; sections etc. Alternatively you can use the 157 start tags, two &lt;head&gt; sections etc. Alternatively you can use the
158 <em>external</em> template (available to download from the website) which is 158 <em>external</em> template (available to download from the website) which is
159 the default template with the unnecessary (X)HTML removed.</li> 159 the default template with the unnecessary (X)HTML removed.</li>
160 <li>If the file into which you are including singapore is named something 160 <li>If the file into which you are including singapore is named something
161 other than index.php or it requires additional GET variables (such as page etc.) 161 other than index.php or it requires additional GET variables (such as page etc.)
162 then you will need to change index_file_url to reflect this. For example if 162 then you will need to change index_file_url to reflect this. For example if
163 the page you are including singapore into is <code>site.php?page=gallery</code> 163 the page you are including singapore into is <code>site.php?page=gallery</code>
164 you will need to change index_file_url to <code>site.php?page=gallery&amp;amp;</code></li> 164 you will need to change index_file_url to <code>site.php?page=gallery&amp;amp;</code></li>
165 <li>If you want to keep both the included singapore installation and the 165 <li>If you want to keep both the included singapore installation and the
166 original simultaneously functional then you can place a file named 166 original simultaneously functional then you can place a file named
167 <code>singapore.local.ini</code> in the same directory as the including file. 167 <code>singapore.local.ini</code> in the same directory as the including file.
168 If found, this file will be loaded after singapore.ini but before gallery.ini 168 If found, this file will be loaded after singapore.ini but before gallery.ini
169 and template.ini. It can thus be used to provide local settings such as index_file_url 169 and template.ini. It can thus be used to provide local settings such as index_file_url
170 mentioned above. Note that base_file and base_url are automatically calculated 170 mentioned above. Note that base_file and base_url are automatically calculated
171 and should not need to be specified.</li> 171 and should not need to be specified.</li>
172 <li>If there is any content on the including page <em>before</em> external.php is 172 <li>If there is any content on the including page <em>before</em> external.php is
173 included then singapore will not be able to send any headers which will 173 included then singapore will not be able to send any headers which will
174 prevent you from using languages with non-default character sets. The 174 prevent you from using languages with non-default character sets. The
175 recommended solution is to turn on output buffering before any content is 175 recommended solution is to turn on output buffering before any content is
176 output and do not flush it until after external.php is included. Essentially 176 output and do not flush it until after external.php is included. Essentially
177 a call to <code>ob_start()</code> at the beginning of the including file is 177 a call to <code>ob_start()</code> at the beginning of the including file is
178 all that is needed. <a href="http://uk.php.net/manual/en/ref.outcontrol.php">About 178 all that is needed. <a href="http://uk.php.net/manual/en/ref.outcontrol.php">About
179 output control</a>.</li> 179 output control</a>.</li>
180 <li>Currently mod_rewrite doesn't work with such included installations of singapore.</li> 180 <li>Currently mod_rewrite doesn't work with such included installations of singapore.</li>
181 </ul> 181 </ul>
182   182  
183 <h2><a name="popup">Opening images in a popup</a></h2> 183 <h2><a name="popup">Opening images in a popup</a></h2>
184   184  
185 <p>Firstly I must say how much I disapprove of popups. If someone wants to open 185 <p>Firstly I must say how much I disapprove of popups. If someone wants to open
186 something in a new window THEY WILL DO IT THEMSELVES! Why do you think so many 186 something in a new window THEY WILL DO IT THEMSELVES! Why do you think so many
187 people have popup blockers? POPUPS ARE BAD! However I have been asked how to 187 people have popup blockers? POPUPS ARE BAD! However I have been asked how to
188 make singapore open images in popup windows so often that I finally yielded and 188 make singapore open images in popup windows so often that I finally yielded and
189 wrote a little bit of JavaScript to do it neatly.</p> 189 wrote a little bit of JavaScript to do it neatly.</p>
190   190  
191 <p>Open album.tpl.php in the directory of your current template (e.g. 191 <p>Open album.tpl.php in the directory of your current template (e.g.
192 templates/default/album.tpl.php) and replace <code>$sg-&gt;gallery-&gt;images[$index]-&gt;thumbnailLink()</code> 192 templates/default/album.tpl.php) and replace <code>$sg-&gt;gallery-&gt;images[$index]-&gt;thumbnailLink()</code>
193 with <code>$sg-&gt;gallery-&gt;images[$index]-&gt;thumbnailPopupLink()</code>. But don't do it. It's bad.<p> 193 with <code>$sg-&gt;gallery-&gt;images[$index]-&gt;thumbnailPopupLink()</code>. But don't do it. It's bad.<p>
194   194  
195 <p>Evil I tell you...</p> 195 <p>Evil I tell you...</p>
196   196  
197 <p><em>$Date: 2006/08/06 13:50:20 $</em></p> 197 <p><em>$Date: 2006/08/06 13:50:20 $</em></p>
198   198  
199 </body> 199 </body>
200 </html> 200 </html>