Zenphoto's object model framework Feb 22, 2010 / Updated: May 18, 2013
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.
With Zenphoto 1.4.4 the internal structure has changed a little for optimization reasons. The functionality is the same though:
- 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. PersistentObjectis the root class for the following objects:
- Zenphoto_Administrator: represents a user
- Comments: represents a comment
- Zenpage: 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 album.
- _Image: represents an image within an album. The base Imageobject has been extended to handle other "image" types:
- 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
- ZenpageRoot: Base class from which all Zenpage classes derive
- ZenpageCategory: represents a Zenpage news category
- ZenpageItems: sub base class for Zenpage items:
- ZenpageNews: represents a Zenpage news article
- ZenpagePages: represents a Zenpage page
- Zenphoto_Authority: functions used in password hashing for zenphoto
- SearchEngine: represents a search
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 value added 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
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:
- New gallery object:
- $galleryobject = new Gallery();
- New album object:
$albumobject = new Album($galleryobject,"<folder name>");
NOTE: 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);
- New image object:
$imageobject = newImage($albumobject,"<image name>");
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:
- New news article object: $newsobj = new ZenpageNews("<TitleLink>");
- New page object: $pageobj = new ZenpagePage("<TitleLink>");
- 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 class methods
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:
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:
You can delete an object using this:
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!
This work by www.zenphoto.org is licensed under a Creative Commons Attribution-ShareAlike 3.0 Unported License.