All text is available under the terms of the GNU Free Documentation License. For the latest version of this document, see Wikibooks.

Zoph/Using the Webinterface

This manual will describe how to start using Zoph. It assumes you have successfully installed all the components and are presented the logon screen when you visit http://localhost/zoph/logon.php.

Prior to version 0.3.3 this document was referred to as the tutorial.

Contents

Logging In For The First Time

An admin user was created when you loaded the database. You should be able to login as 'admin' using the password 'admin'. You will be presented with Zoph's home page where you will be greeted as 'Unknown Person'. There will be a blank square where a random photo would normally appear.

The first thing you should do is change the admin's password:

  1. Click on the 'prefs' tab.
  2. Click the 'change password' link.
  3. Enter a new password and click 'submit'.

Next, create a 'person' record for yourself:

  1. Click on the 'people' tab.
  2. Click on the [ new ] link on the right.
  3. Fill in your first name, last name and whatever other fields you wish.
  4. Click the 'Insert' button.

Now create a user for yourself:

  1. Click on the 'users' tab.
  2. Click on [ new ].
  3. Pick a username and password.
  4. Select yourself from the person pulldown.
  5. Change your class to Admin.
  6. Click the 'Insert' button.

An admin has permission to do anything so you don't need to grant the specific 'browse' or 'view details' permissions, nor grant permissions to individual albums.

Now that you have created a user:

  1. Click on the 'logout' tab.
  2. Login as your user.

Creating An Album, Category and Place

Before importing some images we'll create an album to put them in. Note that you do not need to assign photos to an album if you don't want to.

To create an album:

  1. Click on the 'albums' tab.
  2. Click on [ new ].
  3. Pick an album name. I'm using "Zoph Tutorial" for this example.
  4. Add an album description if you wish. This can be left blank.
  5. Click the 'Insert' button.

To create a category, click on the 'category' tab and do exactly as above. In creating this tutorial I took a picture of my hand so I created an "Appendages" category for it.

Both albums and categories are hierarchical in nature (each entry can have children entries as well). When you view photos in an album or category within Zoph you automatically see photos placed in that album or category's children as well.

To create a place:

  1. Click on the 'places' tab.
  2. Click on [ new ].
  3. Enter a title and city at minimum.
  4. Click the 'Insert' button.

The Web Based Importer

The web based importer is a new template in Zoph 0.3 that provides an alternative to the command line importer, zophImport.pl. This template does not yet contain all the functionality of zophImport.pl.

To use the importer, at least one of CLIENT_WEB_IMPORT and SERVER_WEB_IMPORT must be set to 1 in config.inc.php and you must be logged in as either an admin or a user that has been granted permission to import.

Enable CLIENT_WEB_IMPORT to upload files through the web-interface using a 'browse' button, and enable SERVER_WEB_IMPORT to import files through the web-interface for files that are already on the server. CLIENT_WEB_IMPORT and SERVER_WEB_IMPORT may be both activated.

If you are going to be importing directories of photos you will probably need to increase the size of max_execution_time in php.ini. The default is 30 seconds but you will probably need this to be a couple minutes or more, depending on how many images you import and how fast your computer is.

If you are running PHP >= 4.2, the importer will try to read the EXIF headers of the images you are loading. Beware that if you specify a date and an EXIF date header is found, the EXIF date will overwrite your date field.

Importing Images

Importing a Local File

A local file means one on the same computer as the person using Zoph (and not, necessarily, the computer running Zoph). The image is uploading using HTTP and is copied to the destination path. The file may be an image or a zip or tar archive. The images should not be placed in any directories within an archive.

To be able to upload archives you need to define the programs with which to do the extraction in config.inc.php. Example are given. Archives are extracted to a temporary directory created with the EXTRACT_DIR defined in config.inc.php. This directory should be writable by the webserver. The zip or tar files themselves are copies to the same location as the images and are not removed by Zoph.

Importing Files on the Server

The uploading step can be skipped for files already on the server running Zoph. This method also allows you to load a directory of images at once. Specify an absolute path in 'file/directory'.

If you are loading a directory of images, the fields you specify will apply to all of them.

File And Directory Permissions

In order to copy images and create thumbnails Zoph needs write permission to the directory you are importing to. The simplest but least secure way to do this is to give the import directory 777 permissions. Alternatively, you could try creating a new group, put yourself and the webserver user in that group, and give the group write permission to the directory.

Files and directories are affected by the IMPORT_UMASK in config.inc.php. The default setting is 0 which leads to files with 777 permissions. Directories are created with DIR_MODE permissions, the default is also 777.

So by default everything created by the importer is open to everyone. Beware!

Viewing Photos

Now that there are some photos in the database, I'll go over some features of the web interface. The UI is fairly self explanatory so you probably don't really have to read this section.

Finding Photos

There are numerous ways to find the photos you just entered, a few of which are:

  1. Browse to the album you created and click [ view photos ].
  2. Browse to yourself in 'people' and click [ photos by ].
  3. Browse to the place you took of photo and click [ photos at ].
  4. Use the search form. Specifying no criteria will bring up all photos.
  5. Use the 'photos' tab and you can browse every photo in Zoph.

The Results Page

By default the results page will show thumbnails of up to 12 photos (you can change this from the 'prefs' page). On the prefs page you can also choose whether or not to display descriptions under the thumbnails.

From this page you can:

  1. Click on a thumbnail to go to the photo page.
  2. Click on [ Prev ] or [ Next ], or use the pager, to page through the photos (if your results span more than one page).
  3. Click on [ Slideshow ] to enter slideshow mode.
  4. Reorder the photos by choosing a field from the pulldown.
  5. Change the direction of ordering by clicking on one of the triangles. The white triangle/arrow represents the current direction.
  6. Change the number of rows and columns displayed.

The Photo Page

Here you'll see a mid sized version of the photo plus all the information about the photo available.

From this page you can:

  1. Click the name of the file or the image itself to bring up the full sized photo.
  2. Click on a person, place, album, category or date to take you to the corresponding pages.
  3. Click on [ Prev ] or [ Next ] to move through the photos as they appeared on the results page.
  4. Click on [ email ] to email the photo (if EMAIL_PHOTOS was set).
  5. Click on [ lightbox ] to add the photo to your lightbox (if you have one)
  6. Click on [ edit ] or [ delete ] (if you are an admin or have been given write permission on the album in which the photo appears).

If you set the auto edit pref, you will automatically be presented with fields to edit the info about a photo whenever you click on a thumbnail. Clicking [ return ] takes you back to the regular view.

Slideshows

The slideshow mode (entered from the results page) will cycle through the current set of photos by refreshing the browser window. The interval between refreshes can be set on the 'prefs' page.

From the slideshow page you can:

  1. Click on [ pause ] to pause the slideshow.
  2. Click on [ stop ] to return to the results page.
  3. Click on [ open ] to view the current photo on the normal photo page.

The Search Page

You can search for photos using multiple criteria on the search page. Note that when you select an album or category, all descendant albums or categories will also automatically be chosen.

By default all criteria are joined by "and". You can choose "or" instead from the pulldowns in the left most column. Since you can not specify groupings of the conditions, you might not get the results you want if you try to construct complex queries using different conjunctions.

Note that the album, category, location, person and photographer menus are pruned so that only those entries that actually appear in a photo that the user has access to are shown.

Random Photos

The thumbnail that appears on the 'home' page is randomly selected. I tend to like this photo to be somewhat good so I created a setting on the 'prefs' page that lets you specify the minimum rating to be used when selecting a random photo.

If you want to create a never ending slideshow of random photos, you can do this by clicking the "randomly chosen photo" link on the home page. If you then click the [ Slideshow ] link on the results page a new random photo will be chosen for each slide. 5.7 Lightboxes

Lightboxes give someone a place to gather and share their favorite photos. In Zoph, lightboxes are simply albums. When editing a user, an admin can declare a certain album to be the lightbox for that user. The admin must grant the user permission to view the lightbox album as well.

IMPORTANT: Don't give a user write permission on their lightbox album. The user could then add any photo to their lightbox and be able to edit it.

Whenever the user views a photo they can click a 'lightbox' link which will add that photo to their lightbox. When a user is viewing their lightbox, each photo will have an 'x' below it. Clicking this will remove that photo from the lightbox.

Lightboxes allow users to gather photos of interest to them without requiring the ability to edit a photo to place it in an album.

Lightboxes are only activated for a user by specifying a lightbox album. The setup I used was to create a "Lightbox" album, under which I created separate albums for each user's lightbox (e.g. "Jason's Lightbox").

To share a lightbox an admin must grant permission to that album to other users.

Managing Users & Restricting Access

One of the features of Zoph is its system of access privileges. You have already created an admin class user for yourself. If you desire, you can create other users as well.

Users

A description of some of the attributes of users follows:

The following only apply to non-Admin users:

Albums

For non-Admin users, permissions to view photos are granted on a per album basis. For each album you grant a user access to, you must specify:

  1. An access level
  2. A Watermark level (if you have enabled watermarking in config.inc.php: see WATERMARKING)
  3. Whether that album will be writable

Zoph determines whether a user has access to a photo checking two things:

  1. Is this photo in an album that the user has access to?
  2. If so, is the user's access level for that album greater than or equal to the level of the photo?

If both of these conditions are met, the user has access to the photo.

If a photo appears in more than one album, a user needs only to have permission on one of them to see the photo. If the user has access to multiple albums in which a photo is found, the least restrictive (highest access level) permission is used.

The level of a photo (and therefore of access levels) can range from 0 to 10. The default access level is 5.

Zoph is designed so that these privileges should work transparently. It should appear to any user that they have access to all photos. There should be no reference to any album or photo (including photo counts) to which a user does not have access.

If an album is marked writable, that user may edit (but not delete) the photos that they have access to in that album.

If you want to grant a user access to all albums you can do this all at once and the access level and writable flag will apply to every album. This is handy if you want to let someone see everything but don't want them to change anything.

Note that when you create new albums you will have to grant permissions to any non-Admins before they will be able to see those album.

Watermarking

You can let Zoph superimpose a watermark over the fullsize picture. You can use this feature if you want your users to be able to look at the high quality pictures, but not use them for publication. To use this feature, the IMAGE_SERVICE has to be enabled. Zoph will put a watermark on each photo that has a level higher than the watermark level.

Scenarios

Access levels

Say you create an account for your parents but you don't want them to see the photos in the "New Years Party" album. Simply don't grant them permission to that album.

However, say the photos in this album are mostly harmless, except for a few that you would like to keep hidden. In this case, change the level of those photos to 6 (or higher) and grant the user permission to the album with an access level of 5 (or less).

Watermarks

You have taken a couple of brilliant landscape images. You really want to show them to one of your regular customers, but you're affraid they will simply take your image and publish it, without paying for it. You put the photos in an album "Landscape" and set their level to 3.

After that, you give your customers account access level 5 and watermark level 2. They will now be able to watch the photo, but when they look at the fullsize image, a large copyright message will be superimposed over the photo. In this way, they will be able to judge the quality of the image, but it will be unusable to use in their productions.

After they have payed for the photo, you can put the image in an album that does allow them to see the photo without a watermark, change the level of the photo or change the watermark level. (keep in mind that the latter two will also influence other accounts or photos, respectively).

The Image Service

If you plan on having multiple users of Zoph and you are planning on hiding some pictures or albums from some users, you may want to turn on the image service in config.inc.php.

The simplest and fastest setup is to have the images served by the web server. However, this requires that the images are accessible to the web server. And if this is true, they are also accessible to any user. Even if the application never links to a photo that a user should not be allowed to see, that user could still view that photo (or any photo) by simply typing its url directly into their browser. Since the image names tend to follow a well defined pattern, it would not be too hard for someone to just guess image names and see what came up.

One solution to this problem is to have the application serve the images rather than the web server. This is what the image service does. If is is used, the IMAGE_DIR defined in config.inc.php should NOT be reachable by the web server. The image service will instead set the proper headers and read out the file itself.

Unfortunately, this makes Zoph slower and can make handling the images more cumbersome. If you don't care about people seeing all of your images, don't bother with the image service. To use watermarking, the image service must be enabled.

But Don't Trust Me

Zoph has all these privilege mechanisms, but don't trust them too much to keep your secret photos hidden. It is beta software and hasn't been tested nearly enough for you to assume you'll be protected.

Defining a Default User

Starting with Zoph 0.2.1 a default user can be defined. This user is automatically logged in when a person first opens Zoph in their browser.

If you use Zoph locally you may want to make yourself the default user so that you never have to bother logging in. You may also want to use this feature to create a guest account with limited permissions.

To create a guest user, first create a person record to associate with the user (this could just be first name Guest, last name User). Then create a guest user, grant that user whatever permissions you want and set the user's preferences. Whichever user is defined as the default user is unable to modify their preferences while they are the default.

You will now need to find the user_id of your guest user. The simplest way is probably to look at the url when you are viewing the users's record in zoph (user.php?user_id=3).

The default user is defined in config.inc.php:

// set to the id of a non admin user or to 0 to disable
// note that this is a user_id, not a person_id
define(DEFAULT_USER, 3);

That's it. Now when you hit /zoph/zoph.php for the first time you'll be logged in as the guest user (if you are already logged in as someone you'll first have to log out). You can also log out when you are the guest user to be able to log back in as someone else.

What if a guest hits logout and wants to get back in but doesn't know the guest account info? Hitting submit on the logon page without specifying a user name or password will log you in as the default user.

Preferences

A user can customize Zoph using the preferences page. Below are descriptions of a few of the prefs.

Breadcrumbs

Between the tabs and the title bar you'll see a list of breadcrumbs by default. On the prefs page You can specify the number of breadcrumbs to show or you can choose to disable the breadcrumbs completely.

One note about breadcrumbs: clicking on the small x to the right of the breadcrumbs will clear the list of crumbs.

Choosing a Language

The default value is 'Browser Default'. This means that Zoph will try to present itself in the language you can specify in your browser's settings. If no translations are present for any of the languages in your browser's list, English will be displayed by default.

If you specify a language on the prefs page instead of 'Browser Default' your setting will override whatever you have your browser set to.

If you would like to provide a translation for another language please let me know (zoph@nother.net). The language files are stored in php/lang. Creating a new translation involves creating a file in this directory with the language's two letter code. Use one of the existing (non English) language files as an example.

Other Prefs

Here are descriptions of a few of the other prefs:

Backing Up Your Data

It's always a good idea to back up you photos. Periodically sync them to another machine or burn them to a cd. Zoph should never delete your photos, when you delete something from the ui only the database record is removed.

You should also periodically export the database. After you spend hours inserting and updating photos into Zoph, take two seconds and do the following:

> mysqldump -u zoph_admin -p zoph > zoph-`date +%Y%m%d`.sql

Integrating Zoph

In this section I thought I'd mention a couple of tips if you are interested in trying to integrate Zoph with other parts of your website. This is still a work in progress.

Looking Up People

Say you have a site that has its own person or user records and you would like to map between the two systems (you want to put a "photos of" link on the profile page of a user, for example). Though Zoph usually uses it's own person_id field, you can pass a name instead:

http://www.nother.net/zoph/photos.php?person=Geiger,Jason

will show you photos of a person. You also can use "photographer":

http://www.nother.net/zoph/photos.php?photographer=Geiger,Jason

Or instead of jumping to the photos page you can hit the person page:

http://www.nother.net/zoph/person.php?person=Geiger,Jason

Other Lookups

For albums, categories and locations these sorts of lookups don't exist at the moment. But they are fairly easy to incorporate if anyone is interested.

Of course it is easy to generate urls for the other photo fields (that don't require joins) like title or description. Just call photos.php?field=val. Any string that does not start with an underscore is assumed to be a field to search on.

Incompatibilities

While developing Zoph I've discovered a couple of oddities which I'll mention below. Problems that have solutions are likely to appear in the FAQ.

Slideshows

For some reason this feature does not work with IE 5 for Mac OS X. Every other photo is shown or the same photo is shown over and over.

The slideshow involves a simple refresh header so I'm not sure what the problem is. It works correctly with IE for Windows and OmniWeb for OSX.

Slideshows worked fine for me using Netscape 4.7 under Linux and Windows but I have been told of one problem using Netscape under Windows where once the slideshow is finished the photo results page that you are redirected to starts refreshing itself. Browsing to another page stops the problem. This may be slightly annoying but at least it doesn't prevent the slideshow from functioning.

Emailing a Photo

Some servers or clients seem to have a problem with preserving or decoding the attachments generated by the Mime class. The often seems related to how lines are terminated.

I have currently set things up to terminate lines with \n (and not a \r\n). Here is the behavior I have observed:

To play around with this, edit mail.php.

Optgroups

Most browsers still don't completely support optgroups in select tags. Mozilla and IE 5 for Windows label the pulldown according to the groups but do not display cascading menus. IE 5 Mac does attempt to display a cascading pulldown but it seems there is a problem where a cache get corrupted or something. I often see results from one pulldown being merged with another (people and places, for example). When I view the page source everything looks ok but somehow it is being displayed incorrectly.

You can set GROUPED_PULLDOWN_SIZE in config.inc.php to something small to experiment yourself.