ZenPhoto

This is a short tutorial about how to use Zenphoto’s object model framework  that you for example can use to leave the standard theme way described on the  theming tutorial or to do other custom stuff.

Before reading this you should be familiar with Zenphoto themes in general and having read the theming tutorial. Also you should have quite some PHP knowledge and an understanding about how object orientation works.

1. Zenphoto’s main classes
2. Global object variables
3. Creating an object
4. Changing objects
5. Deleting objects

Zenphoto’s main classes

• Gallery: the gallery itself
• PersistentObject: This is a very general and powerful abstract database persistence class. It defines types by table names and records by a set of unique fields (keys). To instantiate a new database based object in Zenphoto, all that’s needed are the values of those unique fields. PersistentObject provides caching, lazy-evaluating, persistable object support.  PersistentObject is the root class for the following objects:
  • Album:  represents an album.
  • Image:  represents an image within an album. The base Image object has been extended to handle other “image” types:
    • Video (optional video class plugin):  represents an extended image that is multimedia content like mp3,mp4,flv
    • TextObject (optional text object class plugin): its object represents an image object that is a .txt file. This object is intended as an example on how to extend Zenphoto for other filetypes
  • ZenpageNews (optional Zenpage CMS plugin): represents a Zenpage news article
  • ZenpagePages (optional Zenpage CMS plugin): represents a Zenpage page
• SearchEngine: represents a search

Global object variables

Zenphoto operates with several global object variables that for example contain the object of the current image, album or if using Zenpage the current new article or page if in the related theme context.

On this little roundup we will concentrate on examples of the three most important globals: $_zp_gallery for the Gallery class object, $_zp_current_album for the Album class object and of course $_zp_current_image for the Image object classes. As you see the globals are named quite understandable.

These global objects are automatically set up depending on the context. So  depends of course on the context:

• $_zp_gallery is always setup on all theme pages as it represents the gallery in total.
• $_zp_current_album is setup in album context as within the next_album() loop or on a theme’s album.php.
• $_zp_current_image is setup in image context as within the next_image() loop on a theme’s album.php or on the single image display on image.php.

For example to get the title of the current album selected you can use $_zp_current_album->getTitle(). This is actually the same as the template function getAlbumTitle().

All template functions of course use these global objects and you can actually do everything with the class methodes directly. Although that would mean double work in some places as some template functions will output full html sets for your convenience (like the tag cloud html list, the page navigation and similar things).

Read more: A more complete list of Zenphoto’s global variables

Creating a new object

Of course you can create objects besides being “current” within any context. That is pretty standard object orientation. Here the steps to create an image and album object with Zenphoto’s framework:

1. New gallery object: $galleryobject = new Gallery();
2. New album object:
   $albumobject = new Album($galleryobject,"<folder name of the album>");
   Note that “folder name” means the name of the real folder on the filesystem within the root “albums” folder of your installation. If you want to create an object of a subalbum the name must include the parent album name(s) like “toplalbumfoldername/subalbum1folder/subalbum2folder” (etc);
3. New image object:
   $imageobject = newImage($albumobject,"<file name of the image>");
   NOTE: This is not a typo as you should NOT use the constructor new Image() for creating a new image object but always the special function newImage()! It is this function that determines the appropriate “image” class to instantiate based on the filename suffix.

It works similar for Zenpage items as well:

1. New news article object: $newsobj = new ZenpageNews("<titlelink of article>");
2. New page object = $pageobj = new ZenpagePage("<titlelink of page>");

You can now use all methodes of the classes with their object. One speciality: For all objects that contain objects of child classes of the main PeristentObject class you can use $object->get("<name of the database field">); to get the value of any database field entry for this item.

Read more: Available class methods

Changing objects

As you now know $_zp_current_album->getTitle() gets the title of the current image. That title is of course stored in the “images” table of the database.

Now the object model alsp provides functionality to change this value. So for the current image object you could change the image’s title like this:

$imageobject->set("title","<new title>");

Just doing this  the change will be temporarily. If you really want a persistent change of the database entry you also have to save it:

$imageobject->save();

Deleting an object

You can delete an object using this:

$obj->remove();

NOTE: Deleting an object of an image or album also deletes the file/folder on the file system. In case of albums it will also delete all content of this album like images or sub albums recursivly.