ZenPhoto

1. Categories of plugins
2. Template plugins
3. Filters
4. Zenphoto core plugins
5. Plugin options
6. Separate plugin translations

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/zp-extensions 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. (Third party plugins should be placed in the root plugins folder.)

Categories of plugins

There are three categories of plugins implemented in Zenphoto. The categorys you most likely will experience is plugins that extend the functionality of Themes. These are Template Plugins and Filters.

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.

Filters modify the behavior of existing Zenphoto functions. Examples of this kind of filter are found in the scripts filter_zenphoto_seo.php and filter_admin_toolbox.php.  Filters are applied to the output of other functions and may make modifications to that output. So, for instance, filter_zenphoto_seo has a filter for the seoFriendlyURL function that changes accented characters into non accented equivalents.

The third 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. Template Plugins

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/zp-extensions folder. It may optionally use a folder of its same name, also in the zp-core/extensions 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.
• $plugin_disable controls setting the checkbox to enable the plugin. If the plugin cannot run, set this to the “reason” and admin will display the “reason” and will not enable the plugin. The variable should not be present or be set to empty the plugin may be enabled.
• $plugin_is_filter [1.2.5] flags this plugin as a filter type plugin and sets it load priority. The filters will be loaded in decending priority order. Normal front-end plugins should set this variable to 1. They will be loaded by index.php after the front-end environment has been established. Values greater than 1 will cause the plugin to load with the class libraries. These will be available to the admin scipts as well as to the front-end, but will load before the front-end environment is established. Values less than zero will load normally on the front-end but will also be available to the admin scripts.[1.2.6] The absolute value of value will be used for the load prioirity.[1.2.7]
• $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.

Filters

By convention, any plugin wishing to provide Zenphoto Filtering should be named filter_<name>. Filters are added to a function (which has filtering support) by using the function  zp_register_filter function($hook, $function_name, $priority, $accepted_args)).  $hook is the name of the filter item, $function_name is the function that will be invoked to filter the item, $priority is the rank of this filter among the list of filters for this item (defaults to 5), and $accepted_args is how many parmeters the filter requires (defaults to the number of parameters supplied). Filters are applied in ascending $priority order.

The registered function will be passed the parameters(with the exception of the filter name string) from the zp_apply_filter()  call. The function must always return the initial parameter of the list (if it exists) as this is then passed on to subsequent filters in the chain. This provides a means of filters operating on the changes made by other filters.

Zenphoto currently provides filter invocation for the following. Function parameters are indicated within the parens:

• new_image ($image_object)
  Invoked just after Zenphoto saves a newly discovers image to the database.
• image_instantiate ($image_object) [1.2.9]
  Invoked when an image object is instantiated.
• image_refresh
• new_album ($album_object)
  Invoked whenever Zenphoto saves a newly discovered album to the database.
• album_instantiate ($album_object) [1.2.9]
  Invoked when an album object is instantiated.
• album_refresh
• new_page ($page_object) [1.2.5]
  Invoked when Zenpage saves a newly created page.
• new_article ($news_object) [1.2.5]
  Invoked when Zenpage saves a newly created news article.
• seoFriendlyURL ($string)
  Invoked wherever Zenphoto thinks that URL string text should be processed for non-seo friendly characters. The function return value is used as the new value of the string text.
• album_filter ($files[])
  Invoked when Zenphoto checks for albums (folders) for the gallery or a subalbum. The parameter is an array of filenames discovered. The return value of the function is the edited list of filenames.
• image_filter ($files[])
  Similar to album_filter, but for when Zenphoto checks an album for images. The return value is the updated image name list.
• admin_login_attempt($success, $user, $password)[1.2.6]
  Invoked whenever an attempt is made to log in as an administrator. Success is the rights of the user  if the login was successful. $user and $password are the credentials presented for the login.
• guest_login_attempt($success, $user, $password, $athority)[1.2.6]
  Invoked whenever an attempt is made to log in as a guest user. Success is true if the login was successful. $user and $password are the credentials presented for the login. $athority is the kind of login, e.g. gallery, album, etc.
• check_album_credentials($success)[1.2.9]
  Invoked when checking if a viewer is permitted to access an album. It should return true if access is allowed. If it returns true, no further checking is performed.
• admin_toolbox_<position> [updated for 1.2.5]
  These filters allow additions to the Admin Toolbox links. <position> indicates where in the link list they will be placed. The positions are :
• • global:  on all instances of the links
  • gallery:   on a gallery page
  • album($albumname):  on an album page
  • image($albumname, $imagename):  on an image page
  • search:  on a search page
  • news:  on a zenpage article page
  • page:  on a zenpage page

  The filter should output the HTML for the link it desires to place in the Admin Toolbox.

• album_<album database field> ($text, $object, $context, $field) [1.2.4]
• image_<image database field> ($text, $object, $context, $field) [1.2.4]
  These filters are invoked by the various editable print functions. $text is the content that would be printed if there were no filter. The actual text printed will be the function return. $object is the Zenphoto album or image, $context will be  ’album’, or ‘image’, $field is the <database field> name.
• comment_post ($commentobject, $ownerobject)
  This filter is called just before a newly posted comment is saved to the database. $commentobject is the comment and $ownerobject is the item (image, album, etc.) to which the object is posted.
• comment_approve($commentobject)
  This filter is called when a SPAM comment is marked as approved (no longer SPAM) by the administrator.
• comment_disapprove($commentobject) [1.2.7]
  This filter is called when a normal comment is marked as SPAM by the administrator.
• edit_album_utilities ($html, $album, $prefix) [1.2.5]
  Used to insert items in the “Utilities” acton box on the admin album edit tab.
• save_album_utilities_data ($html, $album, $prefix) [1.2.5]
  Used to process the POST of edit_album_utilities actions.
• admin_tabs($tabs, $current) [1.2.6]
  Used to insert (or delete)  tabs for Admin pages.
• admin_alterrights($alterrights, $userobj) [1.2.6]
  Used to override disabling of admin rights and managed album user edit sections.
• edit_image_utilities ($html, $imag, $prefix, $subpage, $tagsort) [1.2.5]
  Used to insert items in the “Utilities” action box of the admin image edit tab.
• save_image_utilities_data ($html, $image, $prefix, $page, $sort) [1.2.5]
  Used to process the POST of edit_image_utilities actions.
• custom data handling filters (data, userobject, index)[1.2.5]
  These filters (listed below) are called to process editing and saving of the custom_data of images, albums, or comments. The edit variant allows you to format the data on the Admin edit pages. The save variant lets you process the information presented by the edit variant.The filters are:
  • save_image_custom_data
  • edit_image_custom_data
  • save_album_custom_data
  • edit_album_custom_data
  • save_comment_custom_data
  • edit_comment_custom_data
  • save_album_custom_data [1.2.6]
  • edit_album_custom_data [1.2.6]
  • save_admin_custom_data [1.2.6]
  • edit_admin_custom_data [1.2.6]
  • save_admin_custom_data [1.2.7]
  • edit_admin_custom_data [1.2.7]
• register_user filters [1.2.7]
  Used to allow extensions to the register_user plugin
  • register_user_form ($html)
    add to the registeration form
  • register_user_register ($userobj)
    Called when a user registers
  • register_user_verify ($userobj)
    Called when a user has been verified
• publish_article_utilities ($html) [1.2.6]
  Used to insert items into “Publish” action box on the Zenpage article edit tab.
• publish_page_utilities($html) [1.2.6]
  Used to insert items into “Publish” action box on the Zenpage pages edit tab.
• general_zenpage_utilities($html, $zenpage_object) [1.2.6]
  Used to insert items into “General” action box on the article and pages edit tabs.
• new_page($message, $pageobject) [1.2.6]
  Called just before saving a new Zenpage page.
• update_page($message, $pageobject, $oldtitlelink) [1.2.6]
  Called just before updating an existing Zenpage page.
• new_article($message, $pageobject) [1.2.6]
  Called just before saving a new Zenpage aticle.
• update_article($message, $pageobject, $oldtitlelink) [1.2.6]
  Called just before updating an existing Zenpage page.
• admin_utilities_buttons($buttons) [1.2.7]
  Called just before the Utilities functions buttons are displayed. Use this filter to add buttons to the admin overview page.
• admin_overview_left($discard) [1.2.9]
  Called at the bottom of the left column on the admin overview page.
• admin_overview_right($discard) [1.2.9]
  Called at the bottom of the right column on the admin overview page.
• setupTheme($theme)
• Image HTML handling filters [1.2.7]
  These filters are called passing the img src HTML so that custom processing can be done. reflection_custom_images passes an additional parameter describing if the image is to be considered a thumbnail
  • reflection_std_images
  • reflection_custom_images
  • reflection_std_image_thumbs
  • reflection_std_album_thumbs
  • reflection_custom_album_thumbs

  Zenphoto core plugins

  Zenphoto core plugins are implementations of a particular class used by the Zenphoto core. The current Zenphoto implementation makes use of three classes: class objects, spamfilters and themeoptions. These classes support an options interface (see below.)

  Themeoption 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.

  Class objects extend Zenphoto class capabilities. Currently the only class objects are for extending the “image” capabilities of Zenphoto. class_video.php provides support for video files and the example class_textobject.php is an example of how a new file type might be supported in Zenphoto by use of a class object plugin.

  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, multi-lingual and texteditor flags, and option description. (the multi-lingual flag is used only for options of type text, see bellow.) 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' => 4

  ‘buttons’ => array(gettext(«button text») => «button value»,…),

  ’selections’ => array(gettext(«selector text») => «selector value»,…),

  ‘multilingual’ => 1,

  ‘texteditor’ => 1,

  ‘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
  • 'type' => 3 will cause admin to use a standard textarea for the option (version 1.2.1)
  • 'type' => 4 will cause admin to use radio buttons for the option (version 1.2.1)
  • 'type' => 5 will cause admin to use a standard selector for the option (version 1.2.1)
  • 'type' => 6 will produce an array of checkboxeds (version 1.2.3)
  • 'type' => 7 will produce an unorder  list of checkboxs (version 1.2.3)
  • 'type' => 8 will produce a Color picker (version 1.2.4)

  For textarea and for a textbox where the 'multilingual' element in the array has a value of 1 these fields will be presented as multi-lingual input fields. That is, there will be a textbox/textarea for each of zenphoto’s supported languages. (This does assume that the global multi-lingual option has been selected.) When this option is displayed in a theme, get_language_string() must be used to isolate the appropriate language string for display. 'texteditor' can be associated with type ‘3′ options. If set it will attempt to attach a text editor to the textarea. (This is a version 1.2.2 feature and requires also that a texteditor be configured.) 'buttons' is the set of radio buttons to display. 'selector' is the list of options for the selection. 'buttons' and 'selector' are required only for type ‘4′ and type ‘5′ options respectively. For types 6 and 7 'checkboxes' is the list of checkboxes.

  handleOption($option, $currentValue) is called when the ‘type’ value of an option is ‘2′ and must generate 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

  Separate plugin translations

  If you provide a theme as a third party, it’s translation is naturally not included with Zenphoto’s general translation file. But with Zenphoto 1.2 you can have an independent translation file for your plugin. Zenphoto uses gettext for translations. Please visit our translating tutorial for more detailed information about that.

  To set up your plugin for separate gettext translation, you just need to place the following function on top of the plugin file or on each file if you plugin consists of several files:

  <?php setPluginDomain("<plugin name>"); ?>

  This function tells Zenphoto that this plugin uses it’s own translation.

  If your plugin consists of just one single file <plugin name>.php, you have to create an additional folder of the same name next to the plugin file. Use exact this folder setup:

  /plugins/<plugin name>/locale/

  /plugins/<plugin name>/locale/<language locale>/LC_MESSAGES/

  /plugins/<plugin name>/locale/<language locale>/LC_MESSAGES/<plugin name>.po/plugins/<plugin name>/locale/<language locale>/LC_MESSAGES/<plugin name>.mo

[1.2.7]
Called just after the current theme is determined. Use this filter to redirect to a different theme. ($image_object) [1.2.7]
Invokde just after Zenphoto saves an album object during a metadate refresh. ($image_object) [1.2.5]
Invokde just after Zenphoto saves an image object during a metadate refresh.