/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *\
 *  singapore - Copyright 2004 Tamlyn Rhodes <tam@zenology.co.uk>      *
 *                                                                     *
 *  singapore is free software; you can redistribute it and/or modify  *
 *  it under the terms of the GNU General Public License 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      *
 \* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */

You are kindly requested to display a link such as the following on all pages generated by singapore:

Powered by singapore v0.9.11

1. Extract all the files in the archive, conserving the directory hierarchy, and upload everything to your web server.
2. Set file permissions. The directories that need to be made writable are:
   • data/ and all subdirectories and files
   • galleries/ and all subdirectories and files

1. If you wish to change any path settings or use one of the SQL backends, make the necessary changes to singapore.ini. If you don't know why you might want to do this then you don't need to do it.
2. Point your browser to the install/ directory and follow the instructions.
3. Delete the install/ directory to prevent unauthorised access.
4. If upgrading from v0.9.9b or earlier run tools/convertdb.php to upgrade your database.
5. Log into the admin section and change the password. The username is admin and the default password is password.
6. You're ready to roll!

Optional but recommended:

• Have a browse through singapore.ini 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 overriding default settings.
• Make your own header image (templates/default/images/header.gif) with the name of your site.
  -or-
  Edit the default style sheet (templates/default/main.css) to integrate it with your site.
  -or-
  Browse the pre-existing templates available for singapore on the templates page. -or-
  Create your own template be 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 templates forum for help and advice.

Always back-up first!

Upgrading is usually just a matter of unzipping the new version over the old. Your galleries, images, metadata, logs and cache will not be affected but the admin password will be reset and the root ini file (singapore.ini) will be overwritten. Unless otherwise stated 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 WinMerge to merge the differences.

The default templates will also be overwritten in an upgrade. For this reason it is advisable to start a new template (in a separate directory) when making customisations.

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 cleanup script to make all server-generated files world writable. This should allow you to delete them like any other file.

If using the info in file name 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 galleries/. To add, move or delete images in a gallery simply add, move or delete the image files in the appropriate directory.

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 info in file name. The username is admin and the default password is password.

Galleries may contain either 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.

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.

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 compressed folders on Windows. You need an unzipping utility on your server to use this feature. Most Linux/Unix machines come with the free unzip utility by Info-Zip preinstalled but precompiled binaries for nearly all operating systems ever conceived can be found on the Info-Zip website. A Win32 version is also available here: http://singapore.sourceforge.net/binaries/singapore-unzip-Win32.zip. Simply place the executable in your PATH or in the singapore root directory.

Upload the archive using the 'new image' option in the singapore admin and select 'Upload multiple files'

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.

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.

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.

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 separate section. 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.

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).

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).

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'.

Permissions are NOT inherited from parent objects.

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.

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.

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.

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.

Installation

an installation of singapore is contained within a website. It is usually in its own separate directory and contains one gallery: the root gallery.

Root gallery

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 pathto_galleries option. It is usually referred to in URLs with a single dot (as in ?gallery=.).

Gallery

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.

Album

an album is a special case of gallery that it 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.

Image

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.

Child gallery (also known as subgallery)

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.

Parent gallery

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).