0,0 → 1,599 |
<!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 <tam@zenology.co.uk> * |
* * |
* 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 & 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 & 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 & 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> |