<!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 - Readme</title>
<link rel="stylesheet" type="text/css" href="docstyle.css" />
</head>

<body>


<h1>singapore v0.10.1 - Readme</h1>

<ul>
  <li><a href="#release">Release notes</a></li>
  <li><a href="#history">Version history</a></li>
  <li><a href="#license">License information</a></li>
  <li><a href="#install">Installation</a></li>
  <li><a href="#upgrade">Upgrading</a></li>
  <li><a href="#managing">Gallery management</a></li>
  <li><a href="#permissions">Help with file permissions</a></li>
  <li><a href="#adminpermissions">The deal with admin permissions</a></li>
  <li><a href="#users">Managing users</a></li>
  <li><a href="#nomenclature">Naming of parts (glossary)</a></li>
  <li><a href="Advanced.html">Advanced features</a></li>
  <li><a href="Development.html">Developer documentation</a></li>
  <li><a href="Translation.html">Translating singapore</a></li>
</ul>


<h2><a name="license">Licensing information</a></h2>

<pre>
 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *\
 *  <a href="http://www.sgal.org/">singapore</a> - Copyright 2002-6 Tamlyn Rhodes &lt;tam@zenology.co.uk&gt;    *
 *                                                                     *
 *  singapore is free software; you can redistribute it and/or modify  *
 *  it under the terms of the <a href="License.txt">GNU General Public License</a> as published  *
 *  by the Free Software Foundation; either version 2 of the License,  *
 *  or (at your option) any later version.                             *
 *                                                                     *
 *  singapore 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; if not, write to the Free Software Foundation,    *
 *  Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA      *
 \* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
</pre>

<p>You are kindly requested to display a link such as the following on all 
pages generated by singapore. However in cases where this is not desirable,
a project donation of 20USD is considered a suitable alternative.</p>

<p class="boxed">Powered by <a href="http://www.sgal.org/">singapore</a></p>


<h2><a name="release">Release notes</a></h2>

<p>This is a recommended update as it addresses a critical bug in the 
template handling that could allow an attacker to view the contents of system 
files on the web server. Several other less severe bugs have been fixed 
including acces control settings inheritance in the admin which should now 
work correctly. The latest version of the 'modern' template is also included.</p>


<h2><a name="install">Installation</a></h2>

<ol>
  <li>Extract all the files in the archive, conserving the directory hierarchy.</li> 
  
  <li>If you wish to change any path settings or use one of the SQL backends, 
  make the necessary changes to <code>singapore.ini</code>. If you don't know 
  why you might want to do this then you don't need to do it.</li>

  <li>Upload everything to your web server.</li>
  
  <li>Set file permissions. The directories that need to be made writable are:
  <ul>
    <li><code>data/</code> and all subdirectories and files</li>
    <li><code>galleries/</code> and all subdirectories and files</li>
  </ul>
  <a href="#permissions">Help with file permissions</a>.
  </li>
  
  <li>Point your browser to the <code>install/</code> directory and follow the instructions.</li>
  
  <li>Delete the <code>install/</code> directory to prevent unauthorised access.</li>
  
  <li>Log into the admin section and change the password. The username is 
  <code>admin</code> and the default password is <code>password</code>.</li>
  
  <li>You're ready to roll! <a href="#managing">More info on how to roll...</a></li>
</ol>

<p>Optional but recommended:</p>
<ul>
  <li>Have a browse through <code>singapore.ini</code> and look at the 
  available options. Each option has comments explaining its function. For most 
  purposes the default values will be fine but you may be able to tweak them 
  to your benefit. See also <a href="Advanced.html#override">overriding default 
  settings</a>.</li>
  
  <li>Make your own header image (<code>templates/default/images/header.gif</code>)
  with the name of your site.<br />
  -or-<br />
  Edit the default style sheet (<code>templates/default/main.css</code>)  
  to integrate it with your site.<br />
  -or-<br />
  Browse the pre-existing templates available for singapore on the 
  <a href="http://www.sgal.org/wiki/files/templates">templates</a> page.
  -or-<br />
  Create your own template by editing an existing one. There is currently no 
  documentation on this topic but anyone with a basic grasp of PHP should be 
  able to work it out. Visit the 
  <a href="http://www.sgal.org/forum/viewforum.php?id=2">templates forum</a>
  for help and advice.</li>
</ul>


<h2><a name="upgrade">Upgrading</a></h2>

<p>Always back-up first!</p>

<p>A patch is also available for people wishing only to fix the security problem.</p>

<p>Upgrading is usually just a matter of unzipping the new version over the old. 
Your galleries, images, metadata will not be affected but the 
admin password will be reset and the root ini file (singapore.ini) will be 
overwritten. The location of log files and thumbnail cache has changed in this 
version. See the forum for 
<a href="http://www.sgal.org/forum/viewtopic.php?id=1267">instructions on 
copying your old logs over to their new location</a>.
You can keep your old users.csv.php file. 
When new configuration options are added you will need to either add these 
to your old singapore.ini or re-edit the new singapore.ini in order to keep your 
personal settings. You may want to use a file difference utility such as
<a href="http://winmerge.sourceforge.net">WinMerge</a> to merge the differences.</p>

<p>The default templates will also be overwritten in an upgrade. For this reason 
it is advisable to copy the default template to a new directory when making 
customisations.</p>


<h2><a name="uninstall">Uninstallation</a></h2>

<p>Server generated content may be owned by the web server and it may therefore 
not be possible to delete these files via ftp. Use the 
<a href="../tools/cleanup.php">cleanup script</a> to make all server-generated 
files world writable. This should allow you to delete them like any other file.</p>


<h2><a name="managing">Managing your galleries</a></h2>

<p>If using the <a href="Advanced.html#iifn">info in file name</a> system then 
all management can be done 
directly on the files using, for example, an ftp client. To create new galleries
simply create a new subdirectory of <code>galleries/</code>. To add, move or delete 
images in a gallery simply add, move or delete the image files in the 
appropriate directory.</p>

<p>If you use the admin mode to edit your galleries or images it will 
automatically create the relevant metadata files. If these files are deleted  
singapore will revert to using <em>info in file name</em>. The username is 
<code>admin</code> and the default password is <code>password</code>.</p>

<p>Galleries may contain <em>either</em> images or further galleries. This 
means that if you create one or more child galleries in a gallery that already 
contains images, these images will be 'hidden'. Removing these child galleries 
will make the images visible again. Galleries containing only images are called 
albums.</p>


<h3>Bulk image uploading</h3>

<p class="note">NOTE: this feature is experimental. It works on some servers but 
does not on others (including the sf.net servers) and I don't know why. It may 
or may not work for you.</p>

<p>You may upload several images at the same time by first storing them in a 
PKWARE compatible ZIP file. Most archiving utilities are able to produce such 
files also sometimes referred to as <em>compressed folders</em> on Windows. You 
need an unzipping utility on your server to use this feature. Most Linux/Unix 
machines come with the free <em>unzip</em> utility by Info-Zip preinstalled but 
precompiled binaries for nearly all operating systems ever conceived can be 
found on the <a href="http://www.info-zip.org/">Info-Zip website</a>. <!--A Win32 
version is also available here: 
<a href="http://singapore.sourceforge.net/binaries/singapore-unzip-Win32.zip">http://singapore.sourceforge.net/binaries/singapore-unzip-Win32.zip</a>.-->
Simply place the executable in your PATH or in the singapore root directory.</p>

<p>Upload the archive using the 'new image' option in the singapore admin and 
select 'Upload multiple files'</p>

<p>If the archive contains only images, these will be added to the current 
gallery just as if they had been uploaded individually. If an archive contains 
subdirectories, these will be copied into the current gallery. Any images in 
the archive root directory will be imported as above. This mechanism 
may be used to upload complete directory structures including metadata.csv 
and gallery.ini files. If the archive root directory contains no images and a 
single directory, singapore will navigate into this directory and proceed to 
import the contents into the current gallery as though they were in the root 
directory.</p>

<p>NOTE: There is a maximum size of file that PHP will allow you to upload.
This defaults to 2MB and cannot be changed by singapore. Consult the PHP manual
or you server's administrator for more information.</p>

<h2><a name="permissions">Help with file permissions</a></h2>

<p>How to make a file writable is dependent on your operating system and 
web server setup and can seem quite daunting for a beginner. One option that 
will work on nearly all Unix/Linux servers is to chmod the relevant 
files/directories to 777 (consult your FTP software documentation for help on 
using the chmod command). However this option is not considered very secure as 
anyone who has write access the web server (such as the owners of other web 
sites hosted on the same computer) can potentially write to or delete these 
directories. There may be a better way to make your files writable by your 
server but this is something you must take up with your server administrator.</p>


<h2><a name="adminpermissions">The deal with admin permissions</a></h2>

<p>First thing to point out is that singapore admin permissions are not related 
to unix/windows filesystem permissions. If you get a "permission denied" message
from php about a certain file, that's the filesystem permissions discussed in a
<a href="#permissions">separate section</a>. For the purposes of this section an 
'object' is anything that can have admin permissions associated with it; i.e. an 
image or a gallery.</p>

<p>There are two types of users: administrators and users. Administrators can do 
everything and are not bound by permission settings. Only administrators may 
create and edit users and change ownership of objects. Ownership is set at the 
time of creation of the object to the user creating the object. The owner of an 
object may do anything to it except change the owner. Only the owner or an 
administrator may alter the permissions of an object, including changing its 
group(s).</p>

<p>There are four kinds of action that may be either allowed or disallowed: 
read, edit, add and delete. Read permissions allow an object to be viewed. Edit 
permissions allow a user to edit (i.e. change) aspects of the object. Add 
permissions allow a user to add sub objects (i.e. images and subgalleries). This 
is obviously meaningless when applied to images but it may be used later to 
allow image comments. Finally Delete permissions allow a user to delete the 
object concerned (and any sub objects).</p>

<p>These four permissions come in two flavours: group and world. World 
permissions apply to all users so if, for example, a gallery has the world add 
permission set then any user can add objects to it. The groups system is 
slightly less intuitive but very powerful. A user may belong to any number of 
groups. These groups are simply alphanumeric names separated by spaces. An 
object may also belong to any number of groups. If a user belongs to at least 
one group to which the object concerned also belongs then the group permissions 
are considered. For example a user has this for their groups field "team23 
photographers friends" and an image belongs to the following groups "friends 
family" and has the group delete permission set then that user may delete the 
object since both belong to the group 'friends'.</p>

<p>Permissions are NOT inherited from parent objects.</p>

<p class="note">NOTE: read permissions are not currently enforced, a future 
version will prevent anyone from seeing objects that do not have sufficient read 
permissions. Note also that there is no mechanism to set image permissions this 
will be amended in a later release. Finally, since there is no database 
concurrency handling, odd things might happen if two users are making changes 
to the same gallery or image simultaneously.</p>


<h2><a name="users">Managing users</a></h2>

<p>As mentioned above there are two types of users: administrators and users. 
Administrators can do everything and are not bound by permission settings. Only 
administrators may create and edit users. Administrators may also edit existing 
users' details including changing their passwords though, of course, they cannot
view their existing passwords.</p>

<p>Users may also be suspended. This preserves all the user's details but 
prevents them from loggin in until their account is unsuspended by an 
administrator.</p>

<p>There are two built-in accounts that cannot be deleted. The "admin" account
is an administrator. The "guest" account is special. It is like a user account 
except that guests have no password, cannot change their details and cannot own 
objects. This means guests can only affect objects with the appropriate world 
permissions set. Any object created by a guest is owned by the special user 
"__nobody__" and has full read, edit, add and delete permissions for both world 
and group. You may disable guest access to your gallery by suspending the guest 
user.</p>


<h2><a name="nomenclature">Naming of parts</a></h2>

<dl>

<dt>Installation</dt>
  <dd>an installation of singapore is contained within a website. It is usually 
  in its own separate directory and contains one gallery: the root gallery.</dd>
  
<dt>Root gallery</dt>
  <dd>There is only one root gallery and it is not contained within any other 
  galleries. It is located directly in the directory specified by the 
  <code>pathto_galleries</code> option. It is usually referred to in URLs with a 
  single dot (as in <code>?gallery=.</code>).</dd>
  
<dt>Gallery</dt>
  <dd>a gallery is contained within another gallery (except the root gallery 
  which is contained in an installation). Galleries may contain more galleries 
  and also images.</dd>

<dt>Album</dt>
  <dd>an album is a special case of gallery that contains exactly zero
  galleries and zero or more images. In other words a gallery is called an 
  album when it does not have any child galleries. So an album is a gallery
  but a gallery is not an album in much the same way that a kitchen is a room 
  but a room is not a kitchen.</dd>

<dt>Image</dt>
  <dd>an image is contained within an album or a gallery. Due to the way 
  singapore operates, images will only be displayed if they are in albums since
  any images in non-album galleries will be hidden.</dd>

<dt>Child gallery (also known as subgallery)</dt>
  <dd>this is a relative term. A child gallery is one contained within the 
  gallery currently being viewed or edited. There may be zero or more.</dd>
  
<dt>Parent gallery</dt>
  <dd>this is a relative term. The parent gallery is the one which contains the 
  gallery currently being viewed or edited. There is always exactly one (except 
  in the case of the root gallery which has no parent).</dd>
  
</dl>

<h2><a name="history">Version history</a></h2>

<pre>Key to symbols:
+ added
- removed
* fixed
o changed
</pre>

<p>A complete and up-to-date CVS changelog is 
<a href="http://www.sgal.org/cvsdemo/ChangeLog">available online</a>.</p>

<h3>0.10.1 - 2006-09-20</h3>

<pre>
* fixed template security issue
+ access control settings are inherited by child galleries
* fixed image hits total
o updated modern template (see separate changelog)
</pre>

<h3>0.10.0 - 2006-05-17</h3>

<pre>
o code is now more object oriented and easier to understand
+ added safe_mode hack using FTP
+ can move &amp; copy galleries in admin
+ can batch delete images and galleries in admin
o thumbnails and logs stored in each gallery
+ thumbnails created on page load and statically linked
+ ancestor metadata is parsed for crumb line
o removed leading ./ from gallery id in urls
+ next and previous gallery links
+ 'up' links to correct page of parent gallery
* base_path and base_url are no longer overwritten by external.php
* fixed eastern european characters in data fields
* fixed new lines in summary field
* fixed image resizing bug when image size equals maxsize
* fixed imagemagick v6.x support
* fixed session.auto_start bug (aka login loop)
* fixed XSS vulnerability in template &amp; language flippers
+ added sort by date field to galleries
o rewritten hit logging code
o added explicit chmod's instead of relying on umask
o new admin error handling in preparetion for our new admin backend 
</pre>

<h3>0.9.11 - 2004-12-15</h3>

<pre>
+ added SQL abstraction backend with support for MySQL and SQLite
o changed IO class hierarchy
o streamlined install process
+ separated editprofile from edituser
* fixed multiple vulnerabilities (thanks to SIG^2)
+ added allow_dir_upload config option
</pre>

<h3>0.9.10 - 2004-10-20</h3>

<pre>
+ implemented full multi-user support with permissions
+ reindex metadata feature in admin for importing ftp'd images
+ language and template are now user-selectable on-the-fly
+ language may be auto-detected from user agent headers
+ summary field now used instead of description field
o introduced new streamlined admin template with quicklinks
o tidied up css classes and annotated the default stylesheet
* fixed md5 dictionary attack vulnerability by hiding user account details
* fixed security issue with back-references in arguments to thumb.php
o made thumb.php reject files with extensions not in recognised_extensions
o changed base_file config option to index_file_url
o changed language config option to default_language
o changed template_name config option to default_template
+ new external.php file for integrating singapore into existing layouts
</pre>

<h3>0.9.9b - 2004-08-08</h3>

<pre>
* fixed image size calculation (again)
</pre>

<h3>0.9.9a - 2004-06-11</h3>

<pre>
* fixed multi-page galleries bug in templates
* fixed XHTML compliance
* fixed image size calculation
* possibly other things
</pre>

<h3>0.9.9 - 2004-05-15</h3>

<pre>
+ added multi-image upload using ZIP files
+ added fixed size and aspect ratio thumbnail creation
* fixed umask functionality (thanks to afuhrmann)
+ added navigation by clickable image map
+ added upload_overwrite config option
o moved url generation into separate function(s) (acsissman)
+ enabled use of mod_rewrite with appropriate .htaccess (acsissman)
+ added progressive jpeg option (thanks to joeforker)
o moved i18n functions into separate class
* made site navigation links xhtml compatible
* fixed special characters in filenames under ImageMagick *again*?
o introduced consistent 'gallery>album>image' naming scheme
o GD2 used as default thumbnail_software (GD1 support unaffected)
</pre>

<h3>0.9.8 - 2004-01-06</h3>

<pre>
+ automatic recognition of most URLs in 'description' field
+ do not process directories starting with dot (.)
+ enabled navigation bar in supporting browsers (e.g. mozilla, opera)
o made 'artist - name' iifn parsing optional
* fixed bizarre sort order in admin mode
* use htmlspecialchars instead of htmlentities
* fixed using special chars in filenames when magic_quotes_gpc is on (again)
* fixed code that produced 'Notice' level errors with PHP 5
</pre>

<h3>0.9.7 - 2003-11-17</h3>

<pre>
+ added forced image resizing to fixed size
+ added rudimentary image and gallery sort ordering
* fixed multi-page galleries listings
* fixed zero-width thumbnails for failed uploads
+ added a few functions useful for templates
+ added .jpe extension
o changed details array format
+ added basePath parameter to allow removed instantiation of singapore class
o fixed some untranslated strings in admin mode
* maybe fixed using special chars in filenames when magic_quotes_gpc is on
+ added back-reference check to prevent file-system walking
o merged __g functionality into _g and _ng
</pre>

<h3>0.9.6 - 2003-08-15</h3>

<pre>
o code entirely reorganised and largely re-written into classes
+ multilanguage (i18n) support
o interface is template driven
+ per-gallery and per-template configuration files
+ nested gallery support (unlimited depth)
+ crumb line for easier navigation
* all image and gallery names are now urlencoded
+ many new config options
</pre>

<h3>0.9.5 - 2003-05-31</h3>

<pre>
* fixed GD2 support in thumb.php (0.9.4a always used GD1)
- removed secret string option
+ added config options for admin session name (allows multiple installs on same server), 
  path to convert (ImageMagick), remove jpeg profile (ImageMagick), 
  character encoding &amp; site name (page title)
o execution_timer off by default and default galleries per page set to 10
+ thumb.php always uses fopen on remote files (now works on windows)
+ more checks in test.php including ImageMagick support and bugfix #743954 (upload_tmp_dir)
</pre>

<h3>0.9.4a - 2003-05-16</h3>

<pre>
+ added PNG and GIF support under GD (GIF only with compatible versions of GD)
+ added PNG, GIF, TIFF, BMP, and support from pretty much every 
  other file type under ImageMagick
+ more checks in test.php
* fixed image counting in iifn mode
* fixed show_image_name_in_thumbnail_view
+ images link back to correct page of gallery (second link)
</pre>

<h3>0.9.4 - 2003-05-13</h3>

<pre>
o changed config to ini file + global config object
o changed directory structure (moved documentation into docs/, moved writable files into data/)
+ gallery (thumbnail) view shows more information
+ gallery (thumbnail) view can show image name under thumbnail (off by default)
+ gallery (list) view shows number of images in gallery
+ implemented random thumbnail image in gallery (list) view
+ added test.php and setup.php (not very useful yet)
* fixed handling of gallery_thumb_number config option
* password change bug
* remote file thumbnail generation with ImageMagick
</pre>

<h3>0.9.3 - 2003-05-10</h3>

<pre>
+ web admin can add and delete images and galleries
+ added GD 2 and ImageMagic thumbnail generation support
* does not generate any E_NOTICE errors anymore
+ added config option for generated thumbnail JPEG quality
* handles extended characters in gallery and image names (Piotr)
* fixed 'images link back to correct page of gallery'
+ added directory_mode and file_mode options
* track_views and show_views now work independently
o admin bar now visible everywhere when logged in
</pre>

<h3>0.9.2 - 2003-04-27</h3>

<pre>
* fixed non-expiration of admin sessions in some cases
+ added purge cached thumbnails option
+ new 'XP' theme
* fixed hit logging functions
+ added image hit log viewing in admin mode
+ images link back to correct page of gallery
o optimised config.php
* fixed some css issues
</pre>

<h3>0.9.1 - 2003-04-23</h3>

<pre>
o changed database format
+ added visible database fields for artist email, darkroom manipulation and
  digital manipulation
+ added invisible (control) database fields for thumbnail, owner, groups and categories
o put header and footer code into separate files
+ implemented limited themeing support
+ added config options for custom paths to cache, galleries, logs, themes, 
  header, footer and custom css
o improved navigation in admin mode
+ added optional script execution timer
* fixed proliferation of newlines in 'desc' field
* fixed wrongly escaped characters when saving info
</pre>

<h3>0.9a - 2003-04-13</h3>

<pre>
+ added much better documentation
</pre>

<h3>0.9 - 2003-03-30</h3>

<pre>
+ admin section (allows editing image and gallery info)
+ nicer gallery list layout
+ filename parser for if no metadata file found
o split into separate include files for io operations, ui generation etc
* fixed some css issues
+ lots of other little things
</pre>

<h3>0.0 (unnumbered version) - 2003-03-29</h3>

<pre>
o first release under GPL
+ everything
</pre>

<p><em>$Date: 2006/05/18 16:14:20 $</em></p>

</body>
</html>