Object model framework February 22, 2010 / Updated: January 05, 2023

This is a short tutorial about how to use Zenphoto's object model framework which allows you to extend the standard way of theming, as described in the theming tutorial and cusomize your gallery any way you like.

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

Zenphoto's main classes

This is the general class structure:

• 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. 
  • Administrator: Represents a user
  • Comment: Represents a comment
  • Zenpage (optional Zenpage CMS plugin): Base class for items of the optional Zenpage CMS plugin
  • ThemeObject: base class Zenphoto theme objects:
    • MediaObject: sub base class for Zenphoto Gallery items:
      • Album: represents an static file system based album
      • dynamicAlbum: represents a dynamic search based album (1.4.6)
      • Transientimage: creates a transient image (that is, one that is not stored in the database)
      • 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
    • Albumbase
    • Image: represents an image within an album. The base Imageobject has been extended to handle other "image" types:
    • ZenpageRoot (optional Zenpage CMS plugin): Base class from which all Zenpage classes derive
      • ZenpageNews: represents a Zenpage news article
      • ZenpagePages: represents a Zenpage page
    • ZenpageCategory: represents a Zenpage news category
    • ZenpageItems: sub base class for Zenpage items:
• Authority: functions used in password hashing for zenphoto
• SearchEngine: represents a search
• feed: base class for feeds

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.

• $_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. Many times the template functions provide added value such as outputing 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

If you want to venture past the standard current context objects you can instantiate your own. 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();
   NOTE: "gallery" refers to the site itself, not to your albums. It is the base and there actually should and needs to be  one gallery object at the time. In normal theme or backend context it is always set in the global $_zp_gallery already.
2. New album object:
   $albumobject = newAlbum("<folder name>");
   NOTE 1: The "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);
   NOTE 2: This is not a typo as you should NOT use the constructor new Album() (note the space) for creating a new album object but always the special function newAlbum()! It is this function that determines the appropriate "album" class to instantiate based on the filename suffix.
3. New image object:
   $imageobject = newImage($albumobject,"<image name>");
   NOTE: This is not a typo as you should NOT use the constructor new Image() (note the space) 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>");
2. New page object: $pageobj = new ZenpagePage("<TitleLink>");
3. New news category object: $catobj = new ZenpageCategory("<TitleLink>"); (Zenphoto 1.3.2)

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("); to get the value of any database field entry for this item. This is, however, discouraged since it does bypass any method algorithm that the object applies to the field.
 
Read more: Available core classes

Changing objects

As you now know $_zp_current_image->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->setTitle("<yourtitle>");

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();

Not all db colums have methods like the title in the example above. For other colums you can use the generic method set():

$imagobject->set('<db table colum to change>', '<value>');

Deleting an object

You can delete an object using this:

$imageobject->remove();

NOTE: Removing an object will also remove any items associated with it. For instance deleting an album will delete all its images, subalbums, and their images. This includes the actual files on disk!