SloozeSloozeHome | Description | Usage | Design | FAQ | Demo
Download the distribution from SourceForge and extract the contents.
Decide whether you are going to store the picture metadata (the data describing the pictures; like topics, captions, comments, etc.) in simple text files or a database.
Create a directory on your web server for Slooze called, say, photos. Copy to this directory the contents of the photos directory in the Slooze distribution. This is the blank Slooze database and the pages that form the starting point for your photo album. Ensure that the permissions for the five .txt files allow them to be written to by the web server.
Copy to this directory the contents of the src directory in the Slooze distribution. These are the source files for Slooze itself. Ensure that your web server can execute scripts in this directory - you may have to add the Execute permission to the directory.
That's it. Now go to Testing the installation and Adding photos below.
The file create.sql in the sql directory of the Slooze distribution contains SQL commands for creating a database, creating the required tables, and inserting the data for the root topic. Check that this SQL is okay for you (for example, maybe you want to change the name of the database it creates, or maybe you have a database already, or maybe you need to change the syntax slightly for your database) then execute it. For example, to create a MySQL database and grant access to username dbuser with password secret:
$ su $ mysql <create.sql $ mysql Welcome to the MySQL monitor. Commands end with ; or \g. mysql> grant all on slooze.* to dbuser@localhost identified by 'secret'; Query OK, 0 rows affected. mysql> quit; $
Create a directory on your web server for Slooze called, say, photos. Copy to this directory the photos.php, admin.php and style.css files from the photos directory in the Slooze distribution. These pages are the starting point for your photo album.
Copy to this directory the contents of the src directory in the Slooze distribution. These are the source files for Slooze itself.
Get the PHPLib distribution from its new location at http://sourceforge.net/projects/phplib/. PHPLib is a big library but you need just one file; the db_*.inc file for the RDBMS you are using. For example, if you are using MySQL then you need db_mysql.inc. Copy this file to your photos directory.
Edit slooze_local.php. You need to comment out (with //) some parts that apply to storing data in text files, and uncomment (by removing the // from the start of the lines) the parts that apply to storing data in your particular database. You also need to fill in a username and password for your database. There are instructions in the comments.
Call up .../photos/photos.php in your browser and check that you see the Slooze main page. There will be no topics or photos at this point.
Create sub-directories in your web server photos directory for each "roll" of photos. Copy your image files to these directories. Each image file should be named something.jpg and have a corresponding thumbnail image called something-t.jpg. Images and thumbnails can be any size, but thumbnails look best if they are all the same. If you do not create and upload thumbnails Slooze will attempt to create them for you. For further information see below.
Try to avoid using 'special' characters in image filenames. Avoiding characters like space, comma, quote, brackets, etc., will lessen the chance of problems with your webserver, the database, and viewer's browsers.
Call up .../photos/admin.php in your browser and check that you see the Slooze main page with admin forms enabled.
Add some topics. In the Add Topic form type a short ID for a topic (e.g. FloridaVacation), a short description (e.g. Vacation in Florida July 2000), and an optional longer summary. The TopicID is what is used in URLs so it should be short and should not contain any 'special' characters. The Description is what is shown to visitors for navigation, and as the title for the topic. The optional summary, which can be several paragraphs of text, is shown at the top of the topic page. Click the Add button. Repeat for all required topics. Place topics in a hierarchy by choosing a suitable parent topic for each new topic you create. You can add (and delete) topics at any time, but for now, create the topics you need for the photos you are about to add.
Add your photos. Type the name of a roll (the name of the sub-directory you created earlier) into the Add Roll form and click the Add button. In the resulting Roll page, choose a topic and click the Add All Pictures button. Wait. All the photos in the roll will be added, and will be assigned to the topic you selected. You can put individual photos into different topics later if you wish. Click All Photos to go back to the main page and repeat for each roll.
Once your photos are added, click on their topic to see the thumbnails. Click on a photo thumbnail to see the detail page for that photo. Type a descriptive caption in the Update Picture form and click the button. You can also put the photo in a different topic now if you want. Repeat for all photos.
Call up .../photos/photos.php in your browser to view the results.
You may like to make some changes to the simple installation scheme described above. Most things can be customised. Here are some suggestions.
Customise the look and feel of the photo album page by editing photos.php. Or, just copy the few lines of PHP code from photos.php and insert them in one of your existing pages.
Edit the style.css stylesheet, or use your own. Slooze generates no formatting tags (<FONT>, etc) so you can change the look of all Slooze output with the stylesheet.
Put the Slooze PHP include files somewhere other than in the photos directory, for example in your common PHP include directory. If the Slooze PHP include files are not on the PHP include_path then add the path to the require statement in photos.php.
Put the photos.php and admin.php files somewhere other than the photos directory, to separate the web pages from the photo database. Change the values in slooze_local.php as appropriate.
Rename photos.php as you wish - the name is not hardcoded anywhere. For example, rename it to index.php or whatever your webserver uses as a default, to make your URLs shorter.
Change other customisable features by editing slooze_local.php. For example, change the file name suffixes used for photos and thumbnails.
Try to avoid editing the Slooze source files, except slooze_local.php. Most things can be changed by overriding configuration variables in this file. This way, when a new version of Slooze is released you will be able to upgrade to the new source files without losing any customisations.
You may allow users to search your pictures by description and comments. This feature is enabled by the enableSearch variable. The default value is TRUE, meaning that the search box is shown to all users.
Set enableSearch to FALSE by overriding it in slooze_local.php if you do not want the search box to be shown.
You may allow users to add comments to pictures. This feature is enabled by the enableComments variable. The default value is TRUE, meaning that all users can add comments to pictures.
Note: Previously this variable was named adminComments. It has been renamed for consistency and clarity.
Set enableComments to FALSE by overriding it in slooze_local.php if you do not want any users to be able to add comments. Or set it to TRUE or FALSE after you instantiate the Slooze object on your page to control comments on a per-user basis.
The IP address of each users who posts a comment is stored. By default this information is not shown to ordinary users, but it is shown in admin mode. If you want the IP address to be shown always, set the showCommentIPs variable to TRUE.
You may opt to have Slooze send you an email each time a new comment is added. This feature is enabled by the enableCommentsEmail variable. The default value is FALSE, meaning that email is not sent. Set enableCommentsEmail to TRUE by overriding it in slooze_local.php if you want to receive email. Also set the value of the emailTo and emailFrom variables.
You may count the number of times each picture is viewed, to gain an idea as to which are the most popular pictures. This feature is enabled by the enableViews variable. The default value is FALSE, meaning that picture views are not counted.
Set enableViews to TRUE by overriding it in slooze_local.php if you want picture views to be counted.
If views counting is enabled then a new link will be shown in each topic, allowing the most viewed pictures to be seen. The number of pictures shown is controlled by the sortThreshold variable. The default value is 5. The link only appears if there are more than this number of pictures in the topic.
You may wish not to count picture views originating from yourself, to avoid skewing the statistics when you are maintaining your website. If you have a fixed IP address (or a limited range of IP addresses) you may set the ownIPSubstring variable. Picture views originating from IP addresses that match ownIPSubstring are not counted. Additionally, picture views are not counted in admin mode.
Views counting is not recommended for sites with heavy traffic using text file storage.
You may allow users to rate the pictures. This feature is enabled by the enableRatings variable. The default value is TRUE, meaning that all users can rate pictures.
Set enableRatings to FALSE by overriding it in slooze_local.php if you do not want any users to be able to rate pictures. Or set it to TRUE or FALSE after you instantiate the Slooze object on your page to control ratings on a per-user basis.
If ratings are enabled then a new link will be shown in each topic, allowing the highest rated pictures to be seen. The number of pictures shown is controlled by the sortThreshold variable. The default value is 5. The link only appears if there are more than this number of pictures in the topic.
If you have a site with a lot of traffic you may wish to enable caching. The first time a page is called up it is generated on-the-fly in the usual way. It is also saved to a file. The next time the same page is called up it is simply read from the file. This can mean an order of magnitude (or more) faster performance, which can be important on heavily trafficed sites.
This feature is enabled by the enableCache variable. The default value is FALSE, meaning that the cache is not used.
Set enableCache to TRUE by overriding it in slooze_local.php if you want to enable caching.
The cache algorithm is fairly simple. In particular, the whole cache is invalidated (cleared) when any update is made. For this reason, there is little benefit in enabling the cache if you have enabled Comments, Views Counting or Ratings.
If you have more than a few pictures in each topic you may wish to take advantage of enhanced navigation. This provides a First, Prev, Next and Last link on each picture page to allow navigating through all the pictures in a topic without having to return to the topic page.
This feature is enabled by the enableNav variable. The default value is TRUE, meaning that the enhanced navigation is shown.
Set enableNav to FALSE by overriding it in slooze_local.php if you want to disable the enhanced navigation. You may want to disable it if you have only a few pictures in each topic.
If you wish, the bulleted list of topics shown on each topic page can have a thumbnail image for each topic as well as a text link. This feature is enabled by creating a directory named topics (in the same place as all the roll directories) and placing image files in it. Each image file should be named TopicID-t.jpg, i.e. exactly as per the ID for the topic, with the standard thumbnail suffix. The images can be any size but they look best if they are all the same. You don't need to enable or disable this feature. If the images exist they will be shown automatically.
If you do not create and upload thumbnail images along with the full-size ones Slooze will attempt to create them for you. This feature depends on a version of the GD library that supports JPEG images being installed and available to PHP. This will be the case for most recent PHP installations. Also, ensure that your web server can write to the "roll" directories to create the thumbnails - you may have to change the permissions on the directories.
If you take advantage of this feature you may wish to set the thumb_height variable by overriding it in slooze_local.php. This sets the size of the automatically generated thumbnail images.
If you are using text file storage, the thumbnails are displayed in the order that they are listed in the photos.txt file. If you added the pictures in a roll by hand, one-by-one, then they will be in this order. If you added all the pictures in a roll at once, using the Add All Pictures button, then they will have been added in the order that they were found in the directory. This is likely to be the order that they were created, which in turn is likely to be the order in which your FTP program uploaded them, which is likely to be alphabetical. Although there is currently no re-order function, you can just edit photos.txt in a text editor and re-order the lines as you want.
If you are using database storage, the thumbnails are sorted into order based on the FrameID (i.e. the picture filenames). You can change this behaviour to sort on any other field in the Pictures table by changing the sqlPictureOrderBy variable in slooze_local.php (although the FrameID field is the only one that it currently makes much sense to use).
If the web server you are hosting your Slooze website on runs under Windows you need to be aware of a few things:
If you are not sure whether these notes apply to you, don't worry, they probably don't. Almost all web site hosting services use some flavour of UNIX.
If you already have information about your pictures maintained in some other database, a spreadsheet, or even another text file, you should be able to export the information to Slooze very easily.
If you are using the text files to store your data, examine the rolls.txt, topics.txt, pictures.txt comments.txt and ratings.txt files to see the format. The first line of each file is the field names; each subsequent line describes one entry. Commas separate the fields. Quotes are used to surround fields that may contain commas. Simply edit these files to include your data.
If you are using an RDBMS to store your data, use the LOAD DATA command to import data to your database from a text file. See your RDBMS docs for details. If your RDBMS enforces the referential intergity between the tables then you should import data to the tables in this order: Topics, Rolls, Pictures, Comments, then Ratings.
Slooze does not impose (or provide) any particular method of authenticating users. The top-level Slooze object contains a member variable called admin. Set this to TRUE to enable display and processing of the admin forms. Set this to FALSE (the default) for the normal user view, and to disable processing of admin commands.
The supplied example consists of two pages, photos.php and admin.php. In photos.php the Slooze object is simply instantiated and used. This gives the normal user view. In admin.php the Slooze object is instantiated, the admin variable is set to TRUE, and then the object is used. This gives the admin view. A simple way to introduce user authentication for admin functions in this scheme would be to configure the web server to require authentication for admin.php, perhaps by adding a .htaccess file in the same directory as admin.php along these lines:
AuthType Basic AuthName Slooze AuthUserFile (path to password file) <Files admin.php> <Limit GET POST> require valid-user </Limit> </Files>
See this Webmonkey tutorial or your web server docs.
An even simpler scheme for a web site with a largely static collection of pictures is simply to delete admin.php once the site is set up.
This is not the only way of controlling access to admin functions. If you currently allow users to log in to your site in some way then you can control admin functions by simply setting admin to TRUE or FALSE as appropriate. You do not even need two separate pages. Simply instantiate a Slooze object on whatever page you need it and set admin before you use it, based on whether you want to do admin at that point, and whether the user is allowed to.
Not including an authentication scheme in Slooze increases flexibility. If you currently have a way of managing users on your web site you can continue to use it. Slooze does not impose an additional, different, login scheme on the photos part of your site. If you do not currently have a way of managing users you can use the scheme suggested in the example, or any other system you choose.
