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 - Readme</title> 6 <title>singapore - Readme</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 v0.10.1 - Readme</h1> 13 <h1>singapore v0.10.1 - Readme</h1>
14   14  
15 <ul> 15 <ul>
16 <li><a href="#release">Release notes</a></li> 16 <li><a href="#release">Release notes</a></li>
17 <li><a href="#history">Version history</a></li> 17 <li><a href="#history">Version history</a></li>
18 <li><a href="#license">License information</a></li> 18 <li><a href="#license">License information</a></li>
19 <li><a href="#install">Installation</a></li> 19 <li><a href="#install">Installation</a></li>
20 <li><a href="#upgrade">Upgrading</a></li> 20 <li><a href="#upgrade">Upgrading</a></li>
21 <li><a href="#managing">Gallery management</a></li> 21 <li><a href="#managing">Gallery management</a></li>
22 <li><a href="#permissions">Help with file permissions</a></li> 22 <li><a href="#permissions">Help with file permissions</a></li>
23 <li><a href="#adminpermissions">The deal with admin permissions</a></li> 23 <li><a href="#adminpermissions">The deal with admin permissions</a></li>
24 <li><a href="#users">Managing users</a></li> 24 <li><a href="#users">Managing users</a></li>
25 <li><a href="#nomenclature">Naming of parts (glossary)</a></li> 25 <li><a href="#nomenclature">Naming of parts (glossary)</a></li>
26 <li><a href="Advanced.html">Advanced features</a></li> 26 <li><a href="Advanced.html">Advanced features</a></li>
27 <li><a href="Development.html">Developer documentation</a></li> 27 <li><a href="Development.html">Developer documentation</a></li>
28 <li><a href="Translation.html">Translating singapore</a></li> 28 <li><a href="Translation.html">Translating singapore</a></li>
29 </ul> 29 </ul>
30   30  
31   31  
32 <h2><a name="license">Licensing information</a></h2> 32 <h2><a name="license">Licensing information</a></h2>
33   33  
34 <pre> 34 <pre>
35 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *\ 35 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *\
36 * <a href="http://www.sgal.org/">singapore</a> - Copyright 2002-6 Tamlyn Rhodes &lt;tam@zenology.co.uk&gt; * 36 * <a href="http://www.sgal.org/">singapore</a> - Copyright 2002-6 Tamlyn Rhodes &lt;tam@zenology.co.uk&gt; *
37 * * 37 * *
38 * singapore is free software; you can redistribute it and/or modify * 38 * singapore is free software; you can redistribute it and/or modify *
39 * it under the terms of the <a href="License.txt">GNU General Public License</a> as published * 39 * it under the terms of the <a href="License.txt">GNU General Public License</a> as published *
40 * by the Free Software Foundation; either version 2 of the License, * 40 * by the Free Software Foundation; either version 2 of the License, *
41 * or (at your option) any later version. * 41 * or (at your option) any later version. *
42 * * 42 * *
43 * singapore is distributed in the hope that it will be useful, * 43 * singapore is distributed in the hope that it will be useful, *
44 * but WITHOUT ANY WARRANTY; without even the implied warranty * 44 * but WITHOUT ANY WARRANTY; without even the implied warranty *
45 * of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. * 45 * of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. *
46 * See the GNU General Public License for more details. * 46 * See the GNU General Public License for more details. *
47 * * 47 * *
48 * You should have received a copy of the GNU General Public License * 48 * You should have received a copy of the GNU General Public License *
49 * along with this; if not, write to the Free Software Foundation, * 49 * along with this; if not, write to the Free Software Foundation, *
50 * Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA * 50 * Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA *
51 \* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ 51 \* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
52 </pre> 52 </pre>
53   53  
54 <p>You are kindly requested to display a link such as the following on all 54 <p>You are kindly requested to display a link such as the following on all
55 pages generated by singapore. However in cases where this is not desirable, 55 pages generated by singapore. However in cases where this is not desirable,
56 a project donation of 20USD is considered a suitable alternative.</p> 56 a project donation of 20USD is considered a suitable alternative.</p>
57   57  
58 <p class="boxed">Powered by <a href="http://www.sgal.org/">singapore</a></p> 58 <p class="boxed">Powered by <a href="http://www.sgal.org/">singapore</a></p>
59   59  
60   60  
61 <h2><a name="release">Release notes</a></h2> 61 <h2><a name="release">Release notes</a></h2>
62   62  
63 <p>This is a recommended update as it addresses a critical bug in the 63 <p>This is a recommended update as it addresses a critical bug in the
64 template handling that could allow an attacker to view the contents of system 64 template handling that could allow an attacker to view the contents of system
65 files on the web server. Several other less severe bugs have been fixed 65 files on the web server. Several other less severe bugs have been fixed
66 including acces control settings inheritance in the admin which should now 66 including acces control settings inheritance in the admin which should now
67 work correctly. The latest version of the 'modern' template is also included.</p> 67 work correctly. The latest version of the 'modern' template is also included.</p>
68   68  
69   69  
70 <h2><a name="install">Installation</a></h2> 70 <h2><a name="install">Installation</a></h2>
71   71  
72 <ol> 72 <ol>
73 <li>Extract all the files in the archive, conserving the directory hierarchy.</li> 73 <li>Extract all the files in the archive, conserving the directory hierarchy.</li>
74 74
75 <li>If you wish to change any path settings or use one of the SQL backends, 75 <li>If you wish to change any path settings or use one of the SQL backends,
76 make the necessary changes to <code>singapore.ini</code>. If you don't know 76 make the necessary changes to <code>singapore.ini</code>. If you don't know
77 why you might want to do this then you don't need to do it.</li> 77 why you might want to do this then you don't need to do it.</li>
78   78  
79 <li>Upload everything to your web server.</li> 79 <li>Upload everything to your web server.</li>
80 80
81 <li>Set file permissions. The directories that need to be made writable are: 81 <li>Set file permissions. The directories that need to be made writable are:
82 <ul> 82 <ul>
83 <li><code>data/</code> and all subdirectories and files</li> 83 <li><code>data/</code> and all subdirectories and files</li>
84 <li><code>galleries/</code> and all subdirectories and files</li> 84 <li><code>galleries/</code> and all subdirectories and files</li>
85 </ul> 85 </ul>
86 <a href="#permissions">Help with file permissions</a>. 86 <a href="#permissions">Help with file permissions</a>.
87 </li> 87 </li>
88 88
89 <li>Point your browser to the <code>install/</code> directory and follow the instructions.</li> 89 <li>Point your browser to the <code>install/</code> directory and follow the instructions.</li>
90 90
91 <li>Delete the <code>install/</code> directory to prevent unauthorised access.</li> 91 <li>Delete the <code>install/</code> directory to prevent unauthorised access.</li>
92 92
93 <li>Log into the admin section and change the password. The username is 93 <li>Log into the admin section and change the password. The username is
94 <code>admin</code> and the default password is <code>password</code>.</li> 94 <code>admin</code> and the default password is <code>password</code>.</li>
95 95
96 <li>You're ready to roll! <a href="#managing">More info on how to roll...</a></li> 96 <li>You're ready to roll! <a href="#managing">More info on how to roll...</a></li>
97 </ol> 97 </ol>
98   98  
99 <p>Optional but recommended:</p> 99 <p>Optional but recommended:</p>
100 <ul> 100 <ul>
101 <li>Have a browse through <code>singapore.ini</code> and look at the 101 <li>Have a browse through <code>singapore.ini</code> and look at the
102 available options. Each option has comments explaining its function. For most 102 available options. Each option has comments explaining its function. For most
103 purposes the default values will be fine but you may be able to tweak them 103 purposes the default values will be fine but you may be able to tweak them
104 to your benefit. See also <a href="Advanced.html#override">overriding default 104 to your benefit. See also <a href="Advanced.html#override">overriding default
105 settings</a>.</li> 105 settings</a>.</li>
106 106
107 <li>Make your own header image (<code>templates/default/images/header.gif</code>) 107 <li>Make your own header image (<code>templates/default/images/header.gif</code>)
108 with the name of your site.<br /> 108 with the name of your site.<br />
109 -or-<br /> 109 -or-<br />
110 Edit the default style sheet (<code>templates/default/main.css</code>) 110 Edit the default style sheet (<code>templates/default/main.css</code>)
111 to integrate it with your site.<br /> 111 to integrate it with your site.<br />
112 -or-<br /> 112 -or-<br />
113 Browse the pre-existing templates available for singapore on the 113 Browse the pre-existing templates available for singapore on the
114 <a href="http://www.sgal.org/wiki/files/templates">templates</a> page. 114 <a href="http://www.sgal.org/wiki/files/templates">templates</a> page.
115 -or-<br /> 115 -or-<br />
116 Create your own template by editing an existing one. There is currently no 116 Create your own template by editing an existing one. There is currently no
117 documentation on this topic but anyone with a basic grasp of PHP should be 117 documentation on this topic but anyone with a basic grasp of PHP should be
118 able to work it out. Visit the 118 able to work it out. Visit the
119 <a href="http://www.sgal.org/forum/viewforum.php?id=2">templates forum</a> 119 <a href="http://www.sgal.org/forum/viewforum.php?id=2">templates forum</a>
120 for help and advice.</li> 120 for help and advice.</li>
121 </ul> 121 </ul>
122   122  
123   123  
124 <h2><a name="upgrade">Upgrading</a></h2> 124 <h2><a name="upgrade">Upgrading</a></h2>
125   125  
126 <p>Always back-up first!</p> 126 <p>Always back-up first!</p>
127   127  
128 <p>A patch is also available for people wishing only to fix the security problem.</p> 128 <p>A patch is also available for people wishing only to fix the security problem.</p>
129   129  
130 <p>Upgrading is usually just a matter of unzipping the new version over the old. 130 <p>Upgrading is usually just a matter of unzipping the new version over the old.
131 Your galleries, images, metadata will not be affected but the 131 Your galleries, images, metadata will not be affected but the
132 admin password will be reset and the root ini file (singapore.ini) will be 132 admin password will be reset and the root ini file (singapore.ini) will be
133 overwritten. The location of log files and thumbnail cache has changed in this 133 overwritten. The location of log files and thumbnail cache has changed in this
134 version. See the forum for 134 version. See the forum for
135 <a href="http://www.sgal.org/forum/viewtopic.php?id=1267">instructions on 135 <a href="http://www.sgal.org/forum/viewtopic.php?id=1267">instructions on
136 copying your old logs over to their new location</a>. 136 copying your old logs over to their new location</a>.
137 You can keep your old users.csv.php file. 137 You can keep your old users.csv.php file.
138 When new configuration options are added you will need to either add these 138 When new configuration options are added you will need to either add these
139 to your old singapore.ini or re-edit the new singapore.ini in order to keep your 139 to your old singapore.ini or re-edit the new singapore.ini in order to keep your
140 personal settings. You may want to use a file difference utility such as 140 personal settings. You may want to use a file difference utility such as
141 <a href="http://winmerge.sourceforge.net">WinMerge</a> to merge the differences.</p> 141 <a href="http://winmerge.sourceforge.net">WinMerge</a> to merge the differences.</p>
142   142  
143 <p>The default templates will also be overwritten in an upgrade. For this reason 143 <p>The default templates will also be overwritten in an upgrade. For this reason
144 it is advisable to copy the default template to a new directory when making 144 it is advisable to copy the default template to a new directory when making
145 customisations.</p> 145 customisations.</p>
146   146  
147   147  
148 <h2><a name="uninstall">Uninstallation</a></h2> 148 <h2><a name="uninstall">Uninstallation</a></h2>
149   149  
150 <p>Server generated content may be owned by the web server and it may therefore 150 <p>Server generated content may be owned by the web server and it may therefore
151 not be possible to delete these files via ftp. Use the 151 not be possible to delete these files via ftp. Use the
152 <a href="../tools/cleanup.php">cleanup script</a> to make all server-generated 152 <a href="../tools/cleanup.php">cleanup script</a> to make all server-generated
153 files world writable. This should allow you to delete them like any other file.</p> 153 files world writable. This should allow you to delete them like any other file.</p>
154   154  
155   155  
156 <h2><a name="managing">Managing your galleries</a></h2> 156 <h2><a name="managing">Managing your galleries</a></h2>
157   157  
158 <p>If using the <a href="Advanced.html#iifn">info in file name</a> system then 158 <p>If using the <a href="Advanced.html#iifn">info in file name</a> system then
159 all management can be done 159 all management can be done
160 directly on the files using, for example, an ftp client. To create new galleries 160 directly on the files using, for example, an ftp client. To create new galleries
161 simply create a new subdirectory of <code>galleries/</code>. To add, move or delete 161 simply create a new subdirectory of <code>galleries/</code>. To add, move or delete
162 images in a gallery simply add, move or delete the image files in the 162 images in a gallery simply add, move or delete the image files in the
163 appropriate directory.</p> 163 appropriate directory.</p>
164   164  
165 <p>If you use the admin mode to edit your galleries or images it will 165 <p>If you use the admin mode to edit your galleries or images it will
166 automatically create the relevant metadata files. If these files are deleted 166 automatically create the relevant metadata files. If these files are deleted
167 singapore will revert to using <em>info in file name</em>. The username is 167 singapore will revert to using <em>info in file name</em>. The username is
168 <code>admin</code> and the default password is <code>password</code>.</p> 168 <code>admin</code> and the default password is <code>password</code>.</p>
169   169  
170 <p>Galleries may contain <em>either</em> images or further galleries. This 170 <p>Galleries may contain <em>either</em> images or further galleries. This
171 means that if you create one or more child galleries in a gallery that already 171 means that if you create one or more child galleries in a gallery that already
172 contains images, these images will be 'hidden'. Removing these child galleries 172 contains images, these images will be 'hidden'. Removing these child galleries
173 will make the images visible again. Galleries containing only images are called 173 will make the images visible again. Galleries containing only images are called
174 albums.</p> 174 albums.</p>
175   175  
176   176  
177 <h3>Bulk image uploading</h3> 177 <h3>Bulk image uploading</h3>
178   178  
179 <p class="note">NOTE: this feature is experimental. It works on some servers but 179 <p class="note">NOTE: this feature is experimental. It works on some servers but
180 does not on others (including the sf.net servers) and I don't know why. It may 180 does not on others (including the sf.net servers) and I don't know why. It may
181 or may not work for you.</p> 181 or may not work for you.</p>
182   182  
183 <p>You may upload several images at the same time by first storing them in a 183 <p>You may upload several images at the same time by first storing them in a
184 PKWARE compatible ZIP file. Most archiving utilities are able to produce such 184 PKWARE compatible ZIP file. Most archiving utilities are able to produce such
185 files also sometimes referred to as <em>compressed folders</em> on Windows. You 185 files also sometimes referred to as <em>compressed folders</em> on Windows. You
186 need an unzipping utility on your server to use this feature. Most Linux/Unix 186 need an unzipping utility on your server to use this feature. Most Linux/Unix
187 machines come with the free <em>unzip</em> utility by Info-Zip preinstalled but 187 machines come with the free <em>unzip</em> utility by Info-Zip preinstalled but
188 precompiled binaries for nearly all operating systems ever conceived can be 188 precompiled binaries for nearly all operating systems ever conceived can be
189 found on the <a href="http://www.info-zip.org/">Info-Zip website</a>. <!--A Win32 189 found on the <a href="http://www.info-zip.org/">Info-Zip website</a>. <!--A Win32
190 version is also available here: 190 version is also available here:
191 <a href="http://singapore.sourceforge.net/binaries/singapore-unzip-Win32.zip">http://singapore.sourceforge.net/binaries/singapore-unzip-Win32.zip</a>.--> 191 <a href="http://singapore.sourceforge.net/binaries/singapore-unzip-Win32.zip">http://singapore.sourceforge.net/binaries/singapore-unzip-Win32.zip</a>.-->
192 Simply place the executable in your PATH or in the singapore root directory.</p> 192 Simply place the executable in your PATH or in the singapore root directory.</p>
193   193  
194 <p>Upload the archive using the 'new image' option in the singapore admin and 194 <p>Upload the archive using the 'new image' option in the singapore admin and
195 select 'Upload multiple files'</p> 195 select 'Upload multiple files'</p>
196   196  
197 <p>If the archive contains only images, these will be added to the current 197 <p>If the archive contains only images, these will be added to the current
198 gallery just as if they had been uploaded individually. If an archive contains 198 gallery just as if they had been uploaded individually. If an archive contains
199 subdirectories, these will be copied into the current gallery. Any images in 199 subdirectories, these will be copied into the current gallery. Any images in
200 the archive root directory will be imported as above. This mechanism 200 the archive root directory will be imported as above. This mechanism
201 may be used to upload complete directory structures including metadata.csv 201 may be used to upload complete directory structures including metadata.csv
202 and gallery.ini files. If the archive root directory contains no images and a 202 and gallery.ini files. If the archive root directory contains no images and a
203 single directory, singapore will navigate into this directory and proceed to 203 single directory, singapore will navigate into this directory and proceed to
204 import the contents into the current gallery as though they were in the root 204 import the contents into the current gallery as though they were in the root
205 directory.</p> 205 directory.</p>
206   206  
207 <p>NOTE: There is a maximum size of file that PHP will allow you to upload. 207 <p>NOTE: There is a maximum size of file that PHP will allow you to upload.
208 This defaults to 2MB and cannot be changed by singapore. Consult the PHP manual 208 This defaults to 2MB and cannot be changed by singapore. Consult the PHP manual
209 or you server's administrator for more information.</p> 209 or you server's administrator for more information.</p>
210   210  
211 <h2><a name="permissions">Help with file permissions</a></h2> 211 <h2><a name="permissions">Help with file permissions</a></h2>
212   212  
213 <p>How to make a file writable is dependent on your operating system and 213 <p>How to make a file writable is dependent on your operating system and
214 web server setup and can seem quite daunting for a beginner. One option that 214 web server setup and can seem quite daunting for a beginner. One option that
215 will work on nearly all Unix/Linux servers is to chmod the relevant 215 will work on nearly all Unix/Linux servers is to chmod the relevant
216 files/directories to 777 (consult your FTP software documentation for help on 216 files/directories to 777 (consult your FTP software documentation for help on
217 using the chmod command). However this option is not considered very secure as 217 using the chmod command). However this option is not considered very secure as
218 anyone who has write access the web server (such as the owners of other web 218 anyone who has write access the web server (such as the owners of other web
219 sites hosted on the same computer) can potentially write to or delete these 219 sites hosted on the same computer) can potentially write to or delete these
220 directories. There may be a better way to make your files writable by your 220 directories. There may be a better way to make your files writable by your
221 server but this is something you must take up with your server administrator.</p> 221 server but this is something you must take up with your server administrator.</p>
222   222  
223   223  
224 <h2><a name="adminpermissions">The deal with admin permissions</a></h2> 224 <h2><a name="adminpermissions">The deal with admin permissions</a></h2>
225   225  
226 <p>First thing to point out is that singapore admin permissions are not related 226 <p>First thing to point out is that singapore admin permissions are not related
227 to unix/windows filesystem permissions. If you get a "permission denied" message 227 to unix/windows filesystem permissions. If you get a "permission denied" message
228 from php about a certain file, that's the filesystem permissions discussed in a 228 from php about a certain file, that's the filesystem permissions discussed in a
229 <a href="#permissions">separate section</a>. For the purposes of this section an 229 <a href="#permissions">separate section</a>. For the purposes of this section an
230 'object' is anything that can have admin permissions associated with it; i.e. an 230 'object' is anything that can have admin permissions associated with it; i.e. an
231 image or a gallery.</p> 231 image or a gallery.</p>
232   232  
233 <p>There are two types of users: administrators and users. Administrators can do 233 <p>There are two types of users: administrators and users. Administrators can do
234 everything and are not bound by permission settings. Only administrators may 234 everything and are not bound by permission settings. Only administrators may
235 create and edit users and change ownership of objects. Ownership is set at the 235 create and edit users and change ownership of objects. Ownership is set at the
236 time of creation of the object to the user creating the object. The owner of an 236 time of creation of the object to the user creating the object. The owner of an
237 object may do anything to it except change the owner. Only the owner or an 237 object may do anything to it except change the owner. Only the owner or an
238 administrator may alter the permissions of an object, including changing its 238 administrator may alter the permissions of an object, including changing its
239 group(s).</p> 239 group(s).</p>
240   240  
241 <p>There are four kinds of action that may be either allowed or disallowed: 241 <p>There are four kinds of action that may be either allowed or disallowed:
242 read, edit, add and delete. Read permissions allow an object to be viewed. Edit 242 read, edit, add and delete. Read permissions allow an object to be viewed. Edit
243 permissions allow a user to edit (i.e. change) aspects of the object. Add 243 permissions allow a user to edit (i.e. change) aspects of the object. Add
244 permissions allow a user to add sub objects (i.e. images and subgalleries). This 244 permissions allow a user to add sub objects (i.e. images and subgalleries). This
245 is obviously meaningless when applied to images but it may be used later to 245 is obviously meaningless when applied to images but it may be used later to
246 allow image comments. Finally Delete permissions allow a user to delete the 246 allow image comments. Finally Delete permissions allow a user to delete the
247 object concerned (and any sub objects).</p> 247 object concerned (and any sub objects).</p>
248   248  
249 <p>These four permissions come in two flavours: group and world. World 249 <p>These four permissions come in two flavours: group and world. World
250 permissions apply to all users so if, for example, a gallery has the world add 250 permissions apply to all users so if, for example, a gallery has the world add
251 permission set then any user can add objects to it. The groups system is 251 permission set then any user can add objects to it. The groups system is
252 slightly less intuitive but very powerful. A user may belong to any number of 252 slightly less intuitive but very powerful. A user may belong to any number of
253 groups. These groups are simply alphanumeric names separated by spaces. An 253 groups. These groups are simply alphanumeric names separated by spaces. An
254 object may also belong to any number of groups. If a user belongs to at least 254 object may also belong to any number of groups. If a user belongs to at least
255 one group to which the object concerned also belongs then the group permissions 255 one group to which the object concerned also belongs then the group permissions
256 are considered. For example a user has this for their groups field "team23 256 are considered. For example a user has this for their groups field "team23
257 photographers friends" and an image belongs to the following groups "friends 257 photographers friends" and an image belongs to the following groups "friends
258 family" and has the group delete permission set then that user may delete the 258 family" and has the group delete permission set then that user may delete the
259 object since both belong to the group 'friends'.</p> 259 object since both belong to the group 'friends'.</p>
260   260  
261 <p>Permissions are NOT inherited from parent objects.</p> 261 <p>Permissions are NOT inherited from parent objects.</p>
262   262  
263 <p class="note">NOTE: read permissions are not currently enforced, a future 263 <p class="note">NOTE: read permissions are not currently enforced, a future
264 version will prevent anyone from seeing objects that do not have sufficient read 264 version will prevent anyone from seeing objects that do not have sufficient read
265 permissions. Note also that there is no mechanism to set image permissions this 265 permissions. Note also that there is no mechanism to set image permissions this
266 will be amended in a later release. Finally, since there is no database 266 will be amended in a later release. Finally, since there is no database
267 concurrency handling, odd things might happen if two users are making changes 267 concurrency handling, odd things might happen if two users are making changes
268 to the same gallery or image simultaneously.</p> 268 to the same gallery or image simultaneously.</p>
269   269  
270   270  
271 <h2><a name="users">Managing users</a></h2> 271 <h2><a name="users">Managing users</a></h2>
272   272  
273 <p>As mentioned above there are two types of users: administrators and users. 273 <p>As mentioned above there are two types of users: administrators and users.
274 Administrators can do everything and are not bound by permission settings. Only 274 Administrators can do everything and are not bound by permission settings. Only
275 administrators may create and edit users. Administrators may also edit existing 275 administrators may create and edit users. Administrators may also edit existing
276 users' details including changing their passwords though, of course, they cannot 276 users' details including changing their passwords though, of course, they cannot
277 view their existing passwords.</p> 277 view their existing passwords.</p>
278   278  
279 <p>Users may also be suspended. This preserves all the user's details but 279 <p>Users may also be suspended. This preserves all the user's details but
280 prevents them from loggin in until their account is unsuspended by an 280 prevents them from loggin in until their account is unsuspended by an
281 administrator.</p> 281 administrator.</p>
282   282  
283 <p>There are two built-in accounts that cannot be deleted. The "admin" account 283 <p>There are two built-in accounts that cannot be deleted. The "admin" account
284 is an administrator. The "guest" account is special. It is like a user account 284 is an administrator. The "guest" account is special. It is like a user account
285 except that guests have no password, cannot change their details and cannot own 285 except that guests have no password, cannot change their details and cannot own
286 objects. This means guests can only affect objects with the appropriate world 286 objects. This means guests can only affect objects with the appropriate world
287 permissions set. Any object created by a guest is owned by the special user 287 permissions set. Any object created by a guest is owned by the special user
288 "__nobody__" and has full read, edit, add and delete permissions for both world 288 "__nobody__" and has full read, edit, add and delete permissions for both world
289 and group. You may disable guest access to your gallery by suspending the guest 289 and group. You may disable guest access to your gallery by suspending the guest
290 user.</p> 290 user.</p>
291   291  
292   292  
293 <h2><a name="nomenclature">Naming of parts</a></h2> 293 <h2><a name="nomenclature">Naming of parts</a></h2>
294   294  
295 <dl> 295 <dl>
296   296  
297 <dt>Installation</dt> 297 <dt>Installation</dt>
298 <dd>an installation of singapore is contained within a website. It is usually 298 <dd>an installation of singapore is contained within a website. It is usually
299 in its own separate directory and contains one gallery: the root gallery.</dd> 299 in its own separate directory and contains one gallery: the root gallery.</dd>
300 300
301 <dt>Root gallery</dt> 301 <dt>Root gallery</dt>
302 <dd>There is only one root gallery and it is not contained within any other 302 <dd>There is only one root gallery and it is not contained within any other
303 galleries. It is located directly in the directory specified by the 303 galleries. It is located directly in the directory specified by the
304 <code>pathto_galleries</code> option. It is usually referred to in URLs with a 304 <code>pathto_galleries</code> option. It is usually referred to in URLs with a
305 single dot (as in <code>?gallery=.</code>).</dd> 305 single dot (as in <code>?gallery=.</code>).</dd>
306 306
307 <dt>Gallery</dt> 307 <dt>Gallery</dt>
308 <dd>a gallery is contained within another gallery (except the root gallery 308 <dd>a gallery is contained within another gallery (except the root gallery
309 which is contained in an installation). Galleries may contain more galleries 309 which is contained in an installation). Galleries may contain more galleries
310 and also images.</dd> 310 and also images.</dd>
311   311  
312 <dt>Album</dt> 312 <dt>Album</dt>
313 <dd>an album is a special case of gallery that contains exactly zero 313 <dd>an album is a special case of gallery that contains exactly zero
314 galleries and zero or more images. In other words a gallery is called an 314 galleries and zero or more images. In other words a gallery is called an
315 album when it does not have any child galleries. So an album is a gallery 315 album when it does not have any child galleries. So an album is a gallery
316 but a gallery is not an album in much the same way that a kitchen is a room 316 but a gallery is not an album in much the same way that a kitchen is a room
317 but a room is not a kitchen.</dd> 317 but a room is not a kitchen.</dd>
318   318  
319 <dt>Image</dt> 319 <dt>Image</dt>
320 <dd>an image is contained within an album or a gallery. Due to the way 320 <dd>an image is contained within an album or a gallery. Due to the way
321 singapore operates, images will only be displayed if they are in albums since 321 singapore operates, images will only be displayed if they are in albums since
322 any images in non-album galleries will be hidden.</dd> 322 any images in non-album galleries will be hidden.</dd>
323   323  
324 <dt>Child gallery (also known as subgallery)</dt> 324 <dt>Child gallery (also known as subgallery)</dt>
325 <dd>this is a relative term. A child gallery is one contained within the 325 <dd>this is a relative term. A child gallery is one contained within the
326 gallery currently being viewed or edited. There may be zero or more.</dd> 326 gallery currently being viewed or edited. There may be zero or more.</dd>
327 327
328 <dt>Parent gallery</dt> 328 <dt>Parent gallery</dt>
329 <dd>this is a relative term. The parent gallery is the one which contains the 329 <dd>this is a relative term. The parent gallery is the one which contains the
330 gallery currently being viewed or edited. There is always exactly one (except 330 gallery currently being viewed or edited. There is always exactly one (except
331 in the case of the root gallery which has no parent).</dd> 331 in the case of the root gallery which has no parent).</dd>
332 332
333 </dl> 333 </dl>
334   334  
335 <h2><a name="history">Version history</a></h2> 335 <h2><a name="history">Version history</a></h2>
336   336  
337 <pre>Key to symbols: 337 <pre>Key to symbols:
338 + added 338 + added
339 - removed 339 - removed
340 * fixed 340 * fixed
341 o changed 341 o changed
342 </pre> 342 </pre>
343   343  
344 <p>A complete and up-to-date CVS changelog is 344 <p>A complete and up-to-date CVS changelog is
345 <a href="http://www.sgal.org/cvsdemo/ChangeLog">available online</a>.</p> 345 <a href="http://www.sgal.org/cvsdemo/ChangeLog">available online</a>.</p>
346   346  
347 <h3>0.10.1 - 2006-09-20</h3> 347 <h3>0.10.1 - 2006-09-20</h3>
348   348  
349 <pre> 349 <pre>
350 * fixed template security issue 350 * fixed template security issue
351 + access control settings are inherited by child galleries 351 + access control settings are inherited by child galleries
352 * fixed image hits total 352 * fixed image hits total
353 o updated modern template (see separate changelog) 353 o updated modern template (see separate changelog)
354 </pre> 354 </pre>
355   355  
356 <h3>0.10.0 - 2006-05-17</h3> 356 <h3>0.10.0 - 2006-05-17</h3>
357   357  
358 <pre> 358 <pre>
359 o code is now more object oriented and easier to understand 359 o code is now more object oriented and easier to understand
360 + added safe_mode hack using FTP 360 + added safe_mode hack using FTP
361 + can move &amp; copy galleries in admin 361 + can move &amp; copy galleries in admin
362 + can batch delete images and galleries in admin 362 + can batch delete images and galleries in admin
363 o thumbnails and logs stored in each gallery 363 o thumbnails and logs stored in each gallery
364 + thumbnails created on page load and statically linked 364 + thumbnails created on page load and statically linked
365 + ancestor metadata is parsed for crumb line 365 + ancestor metadata is parsed for crumb line
366 o removed leading ./ from gallery id in urls 366 o removed leading ./ from gallery id in urls
367 + next and previous gallery links 367 + next and previous gallery links
368 + 'up' links to correct page of parent gallery 368 + 'up' links to correct page of parent gallery
369 * base_path and base_url are no longer overwritten by external.php 369 * base_path and base_url are no longer overwritten by external.php
370 * fixed eastern european characters in data fields 370 * fixed eastern european characters in data fields
371 * fixed new lines in summary field 371 * fixed new lines in summary field
372 * fixed image resizing bug when image size equals maxsize 372 * fixed image resizing bug when image size equals maxsize
373 * fixed imagemagick v6.x support 373 * fixed imagemagick v6.x support
374 * fixed session.auto_start bug (aka login loop) 374 * fixed session.auto_start bug (aka login loop)
375 * fixed XSS vulnerability in template &amp; language flippers 375 * fixed XSS vulnerability in template &amp; language flippers
376 + added sort by date field to galleries 376 + added sort by date field to galleries
377 o rewritten hit logging code 377 o rewritten hit logging code
378 o added explicit chmod's instead of relying on umask 378 o added explicit chmod's instead of relying on umask
379 o new admin error handling in preparetion for our new admin backend 379 o new admin error handling in preparetion for our new admin backend
380 </pre> 380 </pre>
381   381  
382 <h3>0.9.11 - 2004-12-15</h3> 382 <h3>0.9.11 - 2004-12-15</h3>
383   383  
384 <pre> 384 <pre>
385 + added SQL abstraction backend with support for MySQL and SQLite 385 + added SQL abstraction backend with support for MySQL and SQLite
386 o changed IO class hierarchy 386 o changed IO class hierarchy
387 o streamlined install process 387 o streamlined install process
388 + separated editprofile from edituser 388 + separated editprofile from edituser
389 * fixed multiple vulnerabilities (thanks to SIG^2) 389 * fixed multiple vulnerabilities (thanks to SIG^2)
390 + added allow_dir_upload config option 390 + added allow_dir_upload config option
391 </pre> 391 </pre>
392   392  
393 <h3>0.9.10 - 2004-10-20</h3> 393 <h3>0.9.10 - 2004-10-20</h3>
394   394  
395 <pre> 395 <pre>
396 + implemented full multi-user support with permissions 396 + implemented full multi-user support with permissions
397 + reindex metadata feature in admin for importing ftp'd images 397 + reindex metadata feature in admin for importing ftp'd images
398 + language and template are now user-selectable on-the-fly 398 + language and template are now user-selectable on-the-fly
399 + language may be auto-detected from user agent headers 399 + language may be auto-detected from user agent headers
400 + summary field now used instead of description field 400 + summary field now used instead of description field
401 o introduced new streamlined admin template with quicklinks 401 o introduced new streamlined admin template with quicklinks
402 o tidied up css classes and annotated the default stylesheet 402 o tidied up css classes and annotated the default stylesheet
403 * fixed md5 dictionary attack vulnerability by hiding user account details 403 * fixed md5 dictionary attack vulnerability by hiding user account details
404 * fixed security issue with back-references in arguments to thumb.php 404 * fixed security issue with back-references in arguments to thumb.php
405 o made thumb.php reject files with extensions not in recognised_extensions 405 o made thumb.php reject files with extensions not in recognised_extensions
406 o changed base_file config option to index_file_url 406 o changed base_file config option to index_file_url
407 o changed language config option to default_language 407 o changed language config option to default_language
408 o changed template_name config option to default_template 408 o changed template_name config option to default_template
409 + new external.php file for integrating singapore into existing layouts 409 + new external.php file for integrating singapore into existing layouts
410 </pre> 410 </pre>
411   411  
412 <h3>0.9.9b - 2004-08-08</h3> 412 <h3>0.9.9b - 2004-08-08</h3>
413   413  
414 <pre> 414 <pre>
415 * fixed image size calculation (again) 415 * fixed image size calculation (again)
416 </pre> 416 </pre>
417   417  
418 <h3>0.9.9a - 2004-06-11</h3> 418 <h3>0.9.9a - 2004-06-11</h3>
419   419  
420 <pre> 420 <pre>
421 * fixed multi-page galleries bug in templates 421 * fixed multi-page galleries bug in templates
422 * fixed XHTML compliance 422 * fixed XHTML compliance
423 * fixed image size calculation 423 * fixed image size calculation
424 * possibly other things 424 * possibly other things
425 </pre> 425 </pre>
426   426  
427 <h3>0.9.9 - 2004-05-15</h3> 427 <h3>0.9.9 - 2004-05-15</h3>
428   428  
429 <pre> 429 <pre>
430 + added multi-image upload using ZIP files 430 + added multi-image upload using ZIP files
431 + added fixed size and aspect ratio thumbnail creation 431 + added fixed size and aspect ratio thumbnail creation
432 * fixed umask functionality (thanks to afuhrmann) 432 * fixed umask functionality (thanks to afuhrmann)
433 + added navigation by clickable image map 433 + added navigation by clickable image map
434 + added upload_overwrite config option 434 + added upload_overwrite config option
435 o moved url generation into separate function(s) (acsissman) 435 o moved url generation into separate function(s) (acsissman)
436 + enabled use of mod_rewrite with appropriate .htaccess (acsissman) 436 + enabled use of mod_rewrite with appropriate .htaccess (acsissman)
437 + added progressive jpeg option (thanks to joeforker) 437 + added progressive jpeg option (thanks to joeforker)
438 o moved i18n functions into separate class 438 o moved i18n functions into separate class
439 * made site navigation links xhtml compatible 439 * made site navigation links xhtml compatible
440 * fixed special characters in filenames under ImageMagick *again*? 440 * fixed special characters in filenames under ImageMagick *again*?
441 o introduced consistent 'gallery>album>image' naming scheme 441 o introduced consistent 'gallery>album>image' naming scheme
442 o GD2 used as default thumbnail_software (GD1 support unaffected) 442 o GD2 used as default thumbnail_software (GD1 support unaffected)
443 </pre> 443 </pre>
444   444  
445 <h3>0.9.8 - 2004-01-06</h3> 445 <h3>0.9.8 - 2004-01-06</h3>
446   446  
447 <pre> 447 <pre>
448 + automatic recognition of most URLs in 'description' field 448 + automatic recognition of most URLs in 'description' field
449 + do not process directories starting with dot (.) 449 + do not process directories starting with dot (.)
450 + enabled navigation bar in supporting browsers (e.g. mozilla, opera) 450 + enabled navigation bar in supporting browsers (e.g. mozilla, opera)
451 o made 'artist - name' iifn parsing optional 451 o made 'artist - name' iifn parsing optional
452 * fixed bizarre sort order in admin mode 452 * fixed bizarre sort order in admin mode
453 * use htmlspecialchars instead of htmlentities 453 * use htmlspecialchars instead of htmlentities
454 * fixed using special chars in filenames when magic_quotes_gpc is on (again) 454 * fixed using special chars in filenames when magic_quotes_gpc is on (again)
455 * fixed code that produced 'Notice' level errors with PHP 5 455 * fixed code that produced 'Notice' level errors with PHP 5
456 </pre> 456 </pre>
457   457  
458 <h3>0.9.7 - 2003-11-17</h3> 458 <h3>0.9.7 - 2003-11-17</h3>
459   459  
460 <pre> 460 <pre>
461 + added forced image resizing to fixed size 461 + added forced image resizing to fixed size
462 + added rudimentary image and gallery sort ordering 462 + added rudimentary image and gallery sort ordering
463 * fixed multi-page galleries listings 463 * fixed multi-page galleries listings
464 * fixed zero-width thumbnails for failed uploads 464 * fixed zero-width thumbnails for failed uploads
465 + added a few functions useful for templates 465 + added a few functions useful for templates
466 + added .jpe extension 466 + added .jpe extension
467 o changed details array format 467 o changed details array format
468 + added basePath parameter to allow removed instantiation of singapore class 468 + added basePath parameter to allow removed instantiation of singapore class
469 o fixed some untranslated strings in admin mode 469 o fixed some untranslated strings in admin mode
470 * maybe fixed using special chars in filenames when magic_quotes_gpc is on 470 * maybe fixed using special chars in filenames when magic_quotes_gpc is on
471 + added back-reference check to prevent file-system walking 471 + added back-reference check to prevent file-system walking
472 o merged __g functionality into _g and _ng 472 o merged __g functionality into _g and _ng
473 </pre> 473 </pre>
474   474  
475 <h3>0.9.6 - 2003-08-15</h3> 475 <h3>0.9.6 - 2003-08-15</h3>
476   476  
477 <pre> 477 <pre>
478 o code entirely reorganised and largely re-written into classes 478 o code entirely reorganised and largely re-written into classes
479 + multilanguage (i18n) support 479 + multilanguage (i18n) support
480 o interface is template driven 480 o interface is template driven
481 + per-gallery and per-template configuration files 481 + per-gallery and per-template configuration files
482 + nested gallery support (unlimited depth) 482 + nested gallery support (unlimited depth)
483 + crumb line for easier navigation 483 + crumb line for easier navigation
484 * all image and gallery names are now urlencoded 484 * all image and gallery names are now urlencoded
485 + many new config options 485 + many new config options
486 </pre> 486 </pre>
487   487  
488 <h3>0.9.5 - 2003-05-31</h3> 488 <h3>0.9.5 - 2003-05-31</h3>
489   489  
490 <pre> 490 <pre>
491 * fixed GD2 support in thumb.php (0.9.4a always used GD1) 491 * fixed GD2 support in thumb.php (0.9.4a always used GD1)
492 - removed secret string option 492 - removed secret string option
493 + added config options for admin session name (allows multiple installs on same server), 493 + added config options for admin session name (allows multiple installs on same server),
494 path to convert (ImageMagick), remove jpeg profile (ImageMagick), 494 path to convert (ImageMagick), remove jpeg profile (ImageMagick),
495 character encoding &amp; site name (page title) 495 character encoding &amp; site name (page title)
496 o execution_timer off by default and default galleries per page set to 10 496 o execution_timer off by default and default galleries per page set to 10
497 + thumb.php always uses fopen on remote files (now works on windows) 497 + thumb.php always uses fopen on remote files (now works on windows)
498 + more checks in test.php including ImageMagick support and bugfix #743954 (upload_tmp_dir) 498 + more checks in test.php including ImageMagick support and bugfix #743954 (upload_tmp_dir)
499 </pre> 499 </pre>
500   500  
501 <h3>0.9.4a - 2003-05-16</h3> 501 <h3>0.9.4a - 2003-05-16</h3>
502   502  
503 <pre> 503 <pre>
504 + added PNG and GIF support under GD (GIF only with compatible versions of GD) 504 + added PNG and GIF support under GD (GIF only with compatible versions of GD)
505 + added PNG, GIF, TIFF, BMP, and support from pretty much every 505 + added PNG, GIF, TIFF, BMP, and support from pretty much every
506 other file type under ImageMagick 506 other file type under ImageMagick
507 + more checks in test.php 507 + more checks in test.php
508 * fixed image counting in iifn mode 508 * fixed image counting in iifn mode
509 * fixed show_image_name_in_thumbnail_view 509 * fixed show_image_name_in_thumbnail_view
510 + images link back to correct page of gallery (second link) 510 + images link back to correct page of gallery (second link)
511 </pre> 511 </pre>
512   512  
513 <h3>0.9.4 - 2003-05-13</h3> 513 <h3>0.9.4 - 2003-05-13</h3>
514   514  
515 <pre> 515 <pre>
516 o changed config to ini file + global config object 516 o changed config to ini file + global config object
517 o changed directory structure (moved documentation into docs/, moved writable files into data/) 517 o changed directory structure (moved documentation into docs/, moved writable files into data/)
518 + gallery (thumbnail) view shows more information 518 + gallery (thumbnail) view shows more information
519 + gallery (thumbnail) view can show image name under thumbnail (off by default) 519 + gallery (thumbnail) view can show image name under thumbnail (off by default)
520 + gallery (list) view shows number of images in gallery 520 + gallery (list) view shows number of images in gallery
521 + implemented random thumbnail image in gallery (list) view 521 + implemented random thumbnail image in gallery (list) view
522 + added test.php and setup.php (not very useful yet) 522 + added test.php and setup.php (not very useful yet)
523 * fixed handling of gallery_thumb_number config option 523 * fixed handling of gallery_thumb_number config option
524 * password change bug 524 * password change bug
525 * remote file thumbnail generation with ImageMagick 525 * remote file thumbnail generation with ImageMagick
526 </pre> 526 </pre>
527   527  
528 <h3>0.9.3 - 2003-05-10</h3> 528 <h3>0.9.3 - 2003-05-10</h3>
529   529  
530 <pre> 530 <pre>
531 + web admin can add and delete images and galleries 531 + web admin can add and delete images and galleries
532 + added GD 2 and ImageMagic thumbnail generation support 532 + added GD 2 and ImageMagic thumbnail generation support
533 * does not generate any E_NOTICE errors anymore 533 * does not generate any E_NOTICE errors anymore
534 + added config option for generated thumbnail JPEG quality 534 + added config option for generated thumbnail JPEG quality
535 * handles extended characters in gallery and image names (Piotr) 535 * handles extended characters in gallery and image names (Piotr)
536 * fixed 'images link back to correct page of gallery' 536 * fixed 'images link back to correct page of gallery'
537 + added directory_mode and file_mode options 537 + added directory_mode and file_mode options
538 * track_views and show_views now work independently 538 * track_views and show_views now work independently
539 o admin bar now visible everywhere when logged in 539 o admin bar now visible everywhere when logged in
540 </pre> 540 </pre>
541   541  
542 <h3>0.9.2 - 2003-04-27</h3> 542 <h3>0.9.2 - 2003-04-27</h3>
543   543  
544 <pre> 544 <pre>
545 * fixed non-expiration of admin sessions in some cases 545 * fixed non-expiration of admin sessions in some cases
546 + added purge cached thumbnails option 546 + added purge cached thumbnails option
547 + new 'XP' theme 547 + new 'XP' theme
548 * fixed hit logging functions 548 * fixed hit logging functions
549 + added image hit log viewing in admin mode 549 + added image hit log viewing in admin mode
550 + images link back to correct page of gallery 550 + images link back to correct page of gallery
551 o optimised config.php 551 o optimised config.php
552 * fixed some css issues 552 * fixed some css issues
553 </pre> 553 </pre>
554   554  
555 <h3>0.9.1 - 2003-04-23</h3> 555 <h3>0.9.1 - 2003-04-23</h3>
556   556  
557 <pre> 557 <pre>
558 o changed database format 558 o changed database format
559 + added visible database fields for artist email, darkroom manipulation and 559 + added visible database fields for artist email, darkroom manipulation and
560 digital manipulation 560 digital manipulation
561 + added invisible (control) database fields for thumbnail, owner, groups and categories 561 + added invisible (control) database fields for thumbnail, owner, groups and categories
562 o put header and footer code into separate files 562 o put header and footer code into separate files
563 + implemented limited themeing support 563 + implemented limited themeing support
564 + added config options for custom paths to cache, galleries, logs, themes, 564 + added config options for custom paths to cache, galleries, logs, themes,
565 header, footer and custom css 565 header, footer and custom css
566 o improved navigation in admin mode 566 o improved navigation in admin mode
567 + added optional script execution timer 567 + added optional script execution timer
568 * fixed proliferation of newlines in 'desc' field 568 * fixed proliferation of newlines in 'desc' field
569 * fixed wrongly escaped characters when saving info 569 * fixed wrongly escaped characters when saving info
570 </pre> 570 </pre>
571   571  
572 <h3>0.9a - 2003-04-13</h3> 572 <h3>0.9a - 2003-04-13</h3>
573   573  
574 <pre> 574 <pre>
575 + added much better documentation 575 + added much better documentation
576 </pre> 576 </pre>
577   577  
578 <h3>0.9 - 2003-03-30</h3> 578 <h3>0.9 - 2003-03-30</h3>
579   579  
580 <pre> 580 <pre>
581 + admin section (allows editing image and gallery info) 581 + admin section (allows editing image and gallery info)
582 + nicer gallery list layout 582 + nicer gallery list layout
583 + filename parser for if no metadata file found 583 + filename parser for if no metadata file found
584 o split into separate include files for io operations, ui generation etc 584 o split into separate include files for io operations, ui generation etc
585 * fixed some css issues 585 * fixed some css issues
586 + lots of other little things 586 + lots of other little things
587 </pre> 587 </pre>
588   588  
589 <h3>0.0 (unnumbered version) - 2003-03-29</h3> 589 <h3>0.0 (unnumbered version) - 2003-03-29</h3>
590   590  
591 <pre> 591 <pre>
592 o first release under GPL 592 o first release under GPL
593 + everything 593 + everything
594 </pre> 594 </pre>
595   595  
596 <p><em>$Date: 2006/05/18 16:14:20 $</em></p> 596 <p><em>$Date: 2006/05/18 16:14:20 $</em></p>
597   597  
598 </body> 598 </body>
599 </html> 599 </html>