ZenPhoto

The Zenphoto 1.2 release contains an implementation of “plugins” so that the functionality of the product can be extended without “bloating” the core code. Only users of the plugin will require the resources it uses. This article describes the architecture of Zenphoto plugins.Zenphoto plugins reside in the zp-core/plugins folder of the Zenphoto installation. (Theme option plugins are a special exception to this rule. They reside in the theme folder along with the rest of the theme files.) Plugins may come with the Zenphoto distribution or may be available for download from third party developers.

Categories of plugins

There are two categories of plugins implemented in Zenphoto. The category you most likely will experience is plugins that extend the functionality of Themes. These are Template Plugins. Template Plugins add optional functions to the repertoire of capabilities available to Theme designers. Examples of this category of plugin are: Google Maps which adds the facility of printing maps based on GPS data from the image EXIF, Rating which provides an image rating system, and shutterfly which enables viewers to print a copy of an image using the Shutterfly WEB service.

The second category of plugin is used to provide alternative implementations of Zenphoto core functions. Examples of these plugins are: The spamfilter set and the theme options implementation. These plugins let Zenphoto developers provide choices for how the particular feature is handled. For instance, administrators can choose among four different spam filters to screen comments posted to their galleries.

Template Plugins

Template Plugins are PHP scripts that consist of two sections. There is a section that provides the “glue” between the plugin and the Zenphoto core. Then there is the section that implements the functionality provided by the plugin. The plugin consists of at least a PHP file residing in the zp-core/plugins folder. It may optionally use a folder of its same name, also in the zp-core/plugins folder.

The “glue” section is the interface to Zenphoto. In it are several (possibly optional) statements to initialize variables or register scripts pertaining to the plugin.

• $plugin_description should be set to the text you wish displayed on the admin plugins tab description of the plugin.
• $plugin_author is the author of the plugin. This is also displayed on the plugins tab.
• $plugin_version is the version of the plugin.
• $plugin_URL is an URL to the usage documentation for the plugin. For plugins distributed with Zenphoto this is an URL to the PHP documentation page of the plugin on zenphoto.org.
• $option_interface If your plugin supports options, this variable should set to an instance of the option handler class for the plugin. (See Plugin Options below.)
• addPluginScript(); If your plugin requires JavaScript libraries or CSS files to be loaded at the head of the theme page, register the link(s) with calls on this function.

The implementation section contains any initialization code needed by the plugin and all the function statements that are to be provided to the Theme designer.

Zenphoto core plugins

Zenphoto core plugins are implementations of a particular class used by the Zenphoto core. The current Zenphoto implementation makes use of two classes: spamfilters and themeoptions. Both these classes provide an options interface (see below.)

Theme option plugins support only the options interface. This allows theme designers to have optional implementations and the gallery administrator to choose the appropriate values for these options. Themes are not required to support options and therefore the themeoptions plugin is optional.

Spam filter plugins provide, in addition, a filtermessage() function.

filterMessage($author, $email, $website, $body, $imageLink)

• $author is the author field of the comment
• $email is the email field of the comment
• $website is the website field of the comment
• $body is the comment text
• $imageLink is the url to the full image

This function is called to process comment postings. It may pass the comment (return value: 2), reject it (return value: 0), or mark it for moderation (return value: 1). The gallery administrator selects the filter appropriate for his needs from the ones found in the plugins/spamfilters folder.

Plugin options

Plugins may choose to have options that modify their behavior. These options are implemented through the options interface object. To support options, the plugin must declare a class which contains at least the following interface functions:

• getOptionsSupported()
• handleOptions()

Additionally, the class instantiation function should make calls on setOptionDefault() to initialize default values for all the options the plugin uses.

getOptionsSupported () is called from admin Options tab. It returns an array of the option names the theme supports.

The array is indexed by the option name. The value for each option is an array of elements for each option. Each element contains the option key, option type, and option description. For the option names to be translatable, the key for the array element should be a “gettext()” call with a parameter of the display value of the option name. Also the description should be enclosed in a “gettext()” call. An example of an option array element is:

gettext('My Option') => array('key' => 'my_option_key', 'type' => 0,
'desc' => gettext('descripton telling what this options is about.'))

The values for the type are:

• ‘type’ => 0 says for admin to use a standard textbox for the option
• ‘type’ => 1 says for admin to use a standard checkbox for the option
• ‘type’ => 2 will cause admin to call handleOption() to generate the HTML for the option

handleOption($option, $currentValue) is called when the ‘type’ value of an option is ‘2′ and generates the HTML for the option user interface.

• $option is the key name of the option being processed
• $currentValue is the “before” value of the option