User guide

Zenphoto Plugin Architecture

    As from the 1.2 release Zenphoto 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. Plugins may come with the Zenphoto distribution or may be available for download from third party developers.

    We have provided some example plugins to help with your understanding. Note that these plugins are not formally supported by the Zenphoto team.

    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.

    1. 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. Zenphoto plugins reside in the zp-core/zp-extensions folder of the Zenphoto installation. Third party plugins should be placed in the root plugins folder.
    2. Core plugins are the third category of plugin and are 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. The folder residence is the same as for Template Plugins.
    3. Admin utilities are backend plugins that appear as a button on the overview tab's utilities section. There are several plugins included in the release that you might look at as examples. They resides in zp-core/utilities.
      These plugins do not add anything to the core itself, although template or core plugins can add utility buttons. An example is the sitemap-extended plugin (Zenphoto 1.3).
    Template (theme) 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 plugins folder (/zp-core/zp-extensions for official Zenphoto plugins, /plugins for third party supplied ones.).

    It may optionally use a folder of its same name within the plugins folder. Example:

    /plugins/<yourplugin>.php
    /plugins/<yourplugin>/ (folder containing additional files needed by your plugin - optional)
    

    A third party plugin may be "branded" by placing a 16x16 pixel image named logo.png in its folder. That image will appear with the plugin on the plugins tab.

    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] [1.4] There are three defines used in conjunction with this variable which control when in the script load process the plugin will be loaded. They are:
      • CLASS_PLUGIN->the plugin is loaded with the Zenphoto "classes" (album, image, etc.)
      • ADMIN_PLUGIN->the plugin is loaded with the "classes", but only on the back-end
      • THEME_PLUGIN->the plugin is loaded once the theme context has been established
      NOTE: you "or" these to the base priority. It is permissable to "or" ADMIN_PLUGIN with THEME_PLUGIN to get a plugin that operates in both environments. CLASS_PLUGIN stands alone as these plugins will always be loaded.
    • $option_interface If your plugin supports options, this variable should set to the option handler for the plugin. (See Plugin Options below.) Note: as from Zenphoto 1.4 the "name" of the class should be stored rather than an instantiation of it. This is to eliminate unneeded class instantiations in the main-line of Zenphoto. We have determined these are costly of performance.
    • Theme interfaces: There are three "standard interface points" where your plugin can insert HTML into a plugin script. You use the zp_register_filter() function to define what you wish to handle of these insertion points. (see below for how filters work.) The points of insertion are in the head of the script, just after the start of the body and just before then end of the body of the script. Register a filter for 'theme_head' for the first and one for 'theme_body_open' and 'theme_body_close" for the latter two. For instance you can emit HTML to load CSS files in the head with 'theme_head' or to insert javaScript using any of these filters.

    Note: These variables are parsed from the file since they are used even if the plugin is not activated (=loaded). So you need to remove those you don't want to use, e.g. simply commenting out the $option_interface line will not do it if your plugin has no options. It would still be listed as plugin having options.

    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.

    Review demo template file on GitHub

    Core plugins

    Zenphoto core plugins are extensions to the Zenphoto core. They may extend Zenphoto classes or provide new "back-end" capabilities. The current Zenphoto implementation makes use of three classes: class objects, spamfilters and themeoptions. These classes support an options interface (see below.)

    1. Themeoption plugins support only the options interface. This is the themeoptions.php file you see in themes. 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. More info on themeoptions on the theming tutorial.
    2. Spam filter plugins provide a filtermessage() function to examine a posting and determine if it is Spamor not.
      • 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.
    3. 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.

    Besides their specialities core plugins #2 and #3 follow the same structure as theme plugins discussed above.

    Admin utilities

    This is a special type of plugin that actually exists only within the official release package as admin utilities are stored within /zp-core/utilities/. If you create third party plugins you should never add plugins there at all but use the filter way described in the demo plugin file linked above. This documentation is included for completeness.

    These plugins provide admin buttons on the admin overview page and are a little different because they typically are loaded directly. So you basically create a .php file as follows: 

    define('OFFSET_PATH', 3);
    chdir(dirname(dirname(__FILE__)));
    require_once(dirname(dirname(__FILE__)).'/admin-globals.php');
    $buttonlist[] = array(
    'category' => gettext('<category on the overview page to sort the button in>'),
    'enable' => true,
    'button_text' => gettext('My Utility'),
    'formname' => 'myutility.php',
    'action' => 'utilities/myutilityphp',
    'icon' => 'images/bar_graph.png',
    'title' => gettext('Description of the utility.'),
    'alt' => '',
    'hidden' => '',
    'rights' => ADMIN_RIGHTS // What users should be able to see and use the button
    );
    admin_securityChecks(ADMIN_RIGHTS, currentRelativeURL()); //Security check for page access
    printAdminHeader();
    ?>
    <!-- The opening of the <html> and <head> is printed by printAdminHeader() so you can add further stuff to the head here -->
    </head>
    <body>
    <?php printLogoAndLinks(); ?>
    <div id="main">
    <?php printTabs('home'); ?>
    <div id="content">
    <h1><?php echo (gettext('<Name of your utility>')); ?></h1>
    <!-- Here you can do whatever your utility should do -->
    </div><!-- content -->
    </div><!-- main -->
    <?php printAdminFooter(); ?>
    </body>
    </html>

    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() returns an array of options in the form (option display name=>array('type'=>type,'key'=>option_name,'desc'=>option description) )
    • handleOptions($option, $currentValue)
      • $option is the key name of the option being processed
      • $currentValue is the "before" value of the option

    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' => OPTION_TYPE_RADIO
    '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:

    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. 'selections' is the list of options for the selection. 'buttons' and 'selector' are required only for type OPTION_TYPE_RADIO and type OPTION_TYPE_SELECTOR options respectively. For types OPTION_TYPE_CHECKBOX_ARRAY and OPTION_TYPE_CHECKBOX_UL '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.

    You find a complete demo plugin with examples of all possible options here:
    https://github.com/zenphoto/DevTools/blob/master/demo_plugin-and-theme/demo_plugin/zenphoto_demoplugin.php

    Separate plugin translations

    If you provide a plugin as a third party, its translation is naturally not included with Zenphoto's general translation file. Zenphoto uses gettext for translations of literal strings on your plugin.

    Please visit the translating tutorial for more detailed information on how to setup your plugin for plugin translations and how gettext translation works in general..

    Extra database storage

    If your plugin requires to store extra info you can use the general available table plugin_storage together with the object model. This table provdes this field setup to use:

    • id - int(11) unsigned (auto increment)
    • type - varchar(32)
    • aux - varchar(255)
    • data - text

    Zenphoto filters

    Filters modify the behavior of existing Zenphoto functions and can be used by any of the plugin types. Examples of filter use are found noted with each filter. 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.

    Filters are added to a function (which has filtering support) by using the function zp_register_filter ($hook, $function_name, $priority). $hook is the name of the filter item, $function_name is the function that will be invoked to filter the item, and $priority is the rank of this filter among the list of filters for this item (defaults to plugin's priority as set with $plugin_is_filter). 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.

    You find some example or template filter plugins to build your own here:
    http://www.zenphoto.org/category/extensions/example-plugins/

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

    Admin filters

    These filters allow for the extension of the Zenphoto administrator interface.

    Comment

    • comment_approve(comment)

      Invoked when an administrator marks a comment.

      Invoked from:

      • admin-functions.php
      • plugin/comment_form/admin-comments.php
    • comment_disapprove(comment)

      Invoked when an administrator marks a comment as SPAM.

      Invoked from:

      • admin-functions.php
      • plugin/comment_form/admin-comments.php
    Media

    • admin_managed_albums_access(bool, return)

      This filter allows a plugin to intervene when a request to edit an album is being denied for insufficient permissions.

      For example see plugin/security-logger.php

      Invoked from:

      • admin-albumsort.php
      • admin-dynamic-album.php
      • admin-edit.php
      • ...
    • bulk_album_actions(checkarray_albums)

      Allows a filter to establish bulk album action items

      For example see plugin/xmpMetadata.php

      Invoked from:

      • admin-edit.php
    • bulk_image_actions(checkarray_images)

      Allows a filter to establish bulk image action items

      For example see plugin/xmpMetadata.php

      Invoked from:

      • admin-albumsort.php
      • admin-edit.php
    • edit_album_custom_data(string, album, prefix)

      Allows a plugin to manage custom data for images. This invocation is for when the image is presented for editing.

      For example see plugin/common/fieldExtender.php

      Invoked from:

      • admin-functions.php
    • edit_album_utilities(string, album, prefix)

      Allows a plugin to place items in the utilities area for albums. This invocation is for when the album is presented for editing.

      For example see plugin/rating.php

      Invoked from:

      • admin-functions.php
      • pluginDoc.php
    • edit_error(string)

      Provides an interface for plugins to report errors when processing image or album saves.

      For example see plugin/admin-approval.php

      Invoked from:

      • admin-edit.php
    • edit_image_custom_data(string, image, currentimage)

      Allows a plugin to manage custom data for images. This invocation is for when the comment is presented for editing.

      For example see plugin/common/fieldExtender.php

      Invoked from:

      • admin-edit.php
    • edit_image_utilities(string, image, currentimage, pagenum, tagsort)

      Allows a plugin to place items in the utilities area for images. This invocation is for when the image is presented for editing.

      For example see plugin/crop_image.php

      Invoked from:

      • admin-edit.php
      • pluginDoc.php
    • save_album_custom_data(custom, prefix)

      Allows a plugin to manage custom data for albums. This invocation is for when the album object is saved.

      Invoked from:

      • admin-functions.php
    • save_album_utilities_data(album, prefix)

      Allows a plugin to process saves of items in the album Utilities area.

      For example see plugin/common/fieldExtender.php

      Invoked from:

      • admin-functions.php
    • save_image_custom_data(custom, i)

      Allows a plugin to manage image data for comments. This invocation is for when the comment is saved.

      Invoked from:

      • admin-edit.php
    • save_image_utilities_data(image, i)

      Allows a plugin to place items in the utilities area for images. This invocation is for when the image is saved.

      For example see plugin/common/fieldExtender.php

      Invoked from:

      • admin-edit.php
    Miscellaneous

    • admin_XSRF_access(bool, action)

      Invoked when Zenphoto detects an attempt at Cross Site Reference Forgery.

      For example see plugin/security-logger.php

      Invoked from:

      • admin-functions.php
    • admin_allow_access(bool, returnurl)

      Allows mitigation of the normal Zenphoto back-end security checks.

      For example see plugin/ipBlocker.php

      Invoked from:

      • admin-functions.php
    • admin_general_data()

      Allows plugins to insert items onto the <general%gt; tab.

      Invoked from:

      • admin-options.php
    • admin_head()

      Allows plugins to place HTML into the <head> region of admin pages.

      For example see plugin/galleryArticles.php

      Invoked from:

      • admin-functions.php
      • plugin/tinymce4/plugins/tinyzenpage/tinyzenpage.php
    • admin_headers()

      Allows plugins to place HTML into the header region of admin pages.

      Invoked from:

      • admin-functions.php
    • admin_log_actions(bool, file, action)

      Reports when a log has been deleted, cleared, or downloaded.

      For example see plugin/security-logger.php

      Invoked from:

      • admin-logs.php (3)
    • admin_note(string, string)

      This filter is invoked at the head of each admin page to allow a filter to place a note there.

      For example see plugin/user-expiry.php

      Invoked from:

      • admin-albumsort.php
      • admin-dynamic-album.php
      • admin-functions.php
      • ...
    • admin_overview()

      Allows plugins to add items to the Overview page on the back-end.

      For example see plugin/zenphotoDonate.php

      Invoked from:

      • admin.php
    • admin_tabs(zenphoto_tabs)

      Allows plugins to add Tabs to the administrative pages.

      For example see plugin/user-expiry.php

      Invoked from:

      • admin-globals.php
    • admin_theme_buttons(theme, alb)

      Allows a filter to insert buttons in the Theme tab actions column

      Invoked from:

      • admin-themes.php
    • admin_utilities_buttons(buttonlist)

      Allows plugins to add buttons to the admin utilities box on the overview page.

      For example see plugin/rating.php

      Invoked from:

      • admin.php
      • pluginDoc.php
    • installation_information()

      Allows plugins to show items in the "Installation Information" section of the overview page.

      For example see plugin/site_upgrade.php

      Invoked from:

      • admin.php
    • plugin_tabs(classXlate)

      Use to add translatable tabs to the plugin main tab

      Invoked from:

      • admin-functions.php
    • seoFriendly_js()

      Allows a plugin to provide a JavaScript function to names that might contain diacritical marks into text that does not.

      For example see plugin/seo_null.php

      Invoked from:

      • functions.php
    Zenpage

    • edit_article_custom_data(string, result)

      Allows a plugin to manage custom data for News articles. This invocation is for when the news article is presented for editing.

      For example see plugin/common/fieldExtender.php

      Invoked from:

      • plugin/zenpage/admin-edit.php
    • edit_category_custom_data(string, result)

      Allows a plugin to manage custom data for Zenpage categories. This invocation is for when the category is presented for editing.

      For example see plugin/common/fieldExtender.php

      Invoked from:

      • plugin/zenpage/admin-edit.php
    • edit_page_custom_data(string, result)

      Allows a plugin to manage custom data for Zenpage pages. This invocation is for when the page object is presented for editing.

      For example see plugin/common/fieldExtender.php

      Invoked from:

      • plugin/zenpage/admin-edit.php
    • general_zenpage_utilities(string, result)

      Allows plugins to add items to the General area of the Zenpage edit pages.

      For example see plugin/tweet_news.php

      Invoked from:

      • plugin/zenpage/admin-edit.php
    • new_article(string, article)

      Invoked when a new news article is created.

      For example see plugin/multiple_layouts.php

      Invoked from:

      • plugin/zenpage/zenpage-admin-functions.php
    • new_category(string, cat)

      Invoked when a new Zenpage category is created.

      For example see plugin/multiple_layouts.php

      Invoked from:

      • plugin/zenpage/zenpage-admin-functions.php
    • new_page(string, page)

      Invoked when a new Zenpage page is created.

      For example see plugin/multiple_layouts.php

      Invoked from:

      • plugin/zenpage/zenpage-admin-functions.php
    • publish_article_utilities(string, result)

      Allows a plugin to process saves of items in the news article Utilities area.

      For example see plugin/multiple_layouts.php

      Invoked from:

      • plugin/zenpage/admin-edit.php
    • publish_category_utilities(string, result)

      Allows a plugin to process saves of items in the Zenpage category Utilities area.

      For example see plugin/multiple_layouts.php

      Invoked from:

      • plugin/zenpage/admin-edit.php
    • publish_page_utilities(string, result)

      Allows a plugin to process saves of items in the Zenpage page Utilities area.

      For example see plugin/multiple_layouts.php

      Invoked from:

      • plugin/zenpage/admin-edit.php
    • save_article_custom_data(custom, article)

      Allows a plugin to manage custom data for news articles. This invocation is for when the article is saved.

      For example see plugin/common/fieldExtender.php

      Invoked from:

      • plugin/zenpage/zenpage-admin-functions.php
    • save_category_custom_data(custom, cat)

      Allows a plugin to manage custom data for Zenpage categories. This invocation is for when the category is saved.

      For example see plugin/common/fieldExtender.php

      Invoked from:

      • plugin/zenpage/zenpage-admin-functions.php
    • save_page_custom_data(custom, page)

      Allows a plugin to manage image data for Zenpage page. This invocation is for when the page is saved.

      For example see plugin/common/fieldExtender.php

      Invoked from:

      • plugin/zenpage/zenpage-admin-functions.php
    • update_article(string, article, oldtitlelink)

      Invoked when a news article is updated.

      For example see plugin/multiple_layouts.php

      Invoked from:

      • plugin/zenpage/zenpage-admin-functions.php
    • update_category(string, cat, oldtitlelink)

      Invoked when a Zenpage category is updated.

      For example see plugin/multiple_layouts.php

      Invoked from:

      • plugin/zenpage/zenpage-admin-functions.php
    • update_page(string, page, oldtitlelink)

      Invoked when a Zenpage page is updated.

      For example see plugin/multiple_layouts.php

      Invoked from:

      • plugin/zenpage/zenpage-admin-functions.php
    Miscellaneous filters

    • colorbox_themepath(string)

      allows overriding the path of the "custom" colorbox theme. getPlugin() will be called with this path to get the reference to the css when the selected colorbox theme is set to "custom".

      Invoked from:

      • plugin/colorbox_js.php
    • comment_form_data(string, string)

      Allows a plugin to provide data for the comment form.

      Invoked from:

      • plugin/comment_form.php
    • comment_post(commentobj, receiver)

      Invoked when a comment has been posted.

      Invoked from:

      • plugin/comment_form/functions.php
    • content_macro(string)

      Allows plugins and themes to provide macros for data substitutions.

      For example see plugin/exampleMacros.php

      Invoked from:

      • functions.php
    • favoritesHandler_action(string, img, this->name)

      Called when an object is added or removed from a user's favorites list

      Invoked from:

      • plugin/favoritesHandler/favoritesClass.php (4)
    • feature_plugin_load()

      Applied just before feature plugins are loaded for the front-end. Allows a CLASS plugin to take FEATURE actions.

      Invoked from:

      • index.php
    • handle_comment(bool)

      The hook for comment handling. Invoked from the controller to process comments.

      For example see plugin/comment_form.php

      Invoked from:

      • controller.php
    • image_processor_uri(uri)

      Called whenever an image processor URI is created for an image reference. Can be used, for instance, to note and then cache these images.

      For example see plugin/static_html_cache.php

      Invoked from:

      • functions-basic.php
    • load_request(bool)

      Invoked by the front-end when a page is being loaded. The filter may cause the page load to be aborted.

      For example see plugin/seo_locale.php

      Invoked from:

      • functions-controller.php
    • load_theme_script(_zp_script, zp_request)

      Allows for overriding the script loaded for a particular theme page

      For example see plugin/galleryArticles.php

      Invoked from:

      • index.php
    • log_setup(bool, string, string)

      Invoked when setup creates the setup log.

      For example see plugin/security-logger.php

      Invoked from:

      • admin.php (2)
      • setup/index.php (2)
      • setup/setup-option-defaults.php
    • security_misc(bool, string, string, string, link)

      Allows plugins to supply miscellaneous information to the security logger

      For example see plugin/security-logger.php

      Invoked from:

      • cron_runner.php
    • sendmail(string, email_list, subject, message, from_mail, from_name, cc_addresses, replyTo)

      Invoked when Zenphoto attempts to send an e-mail. The plugin is presumed to handle the mailing.

      For example see plugin/zenphoto_sendmail.php

      Invoked from:

      • functions.php (2)
    • seoFriendly(string)

      Invoked to transform names that might contain diacritical marks into text that does not.

      For example see plugin/seo_null.php

      Invoked from:

      • functions.php
    • setupTheme(theme)

      Allows a plugin to override the theme that Zenphoto will use to display WEB pages.

      For example see plugin/mobileTheme.php

      Invoked from:

      • functions.php
    • texteditor_config(string)

      Provides configuration information to the Text Editor plugin (normally TinyMCE).

      For example see plugin/tinymce4.php

      Invoked from:

      • admin-edit.php
      • admin-options.php
      • admin-plugins.php
      • ...
    • themeSwitcher_Controllink(theme)

      Invoked by themeSwitcher's theme_body_open filter. Allows themes to add to the selectors for theme related choices such as personality or color scheme.

      For example see plugin/zenpage.php

      Invoked from:

      • plugin/themeSwitcher.php
    • themeSwitcher_css(string)

      Use to override the css used to style the themeSwitcher control links

      Invoked from:

      • plugin/themeSwitcher.php
    • themeSwitcher_head(_themeSwitcherThemelist)

      Invoded by themeSwitcher's theme_head filter. Allows themes to add to the HTML placed in the theme head when themeSwitcher is active. The parameter passed is a array of theme=>enabled values. If enabled is false the theme will not be included in the selector. Filters can change this value to control if specific themes may be chosen.

      For example see plugin/zenpage.php

      Invoked from:

      • plugin/themeSwitcher.php
    • theme_headers()

      Allows adding headers to the theme output. Called after the standard headers are sent

      Invoked from:

      • 404.php
      • index.php
    • zenphoto_information(_zp_script, _zp_loaded_plugins, _index_theme)

      This filter is used to display the Zenphoto information HTML comment at the end of each page load

      For example see template-filters.php

      Invoked from:

      • index.php
    Object filters

    These filters provide modifications to the behavior of object methods.

    Media

    These filtera apply to Zenphoto "media" objects

    • album_filter(files)

      Allows plugins to remove some folders from the list of album folders that Zenphoto discovers.

      Invoked from:

      • class-album.php
      • class-gallery.php
    • album_instantiate(object)

      Invoked when an album is instantiated.

      For example see plugin/xmpMetadata.php

      Invoked from:

      • class-album.php (2)
    • album_refresh(album)

      Invoked during garbage collection when album object properties are updated.

      For example see plugin/xmpMetadata.php

      Invoked from:

      • class-gallery.php (2)
    • getLink(string, plain)

      Called each time Zenphoto generates a URL.

      For example see theme/zenpage/functions.php

      Invoked from:

      • class-album.php
      • class-image.php
      • template-functions.php (3)
      • ...
    • image_filter(files)

      Allow a plugin to remove files from the list of images found in an album so that they are not treated as images.

      Invoked from:

      • class-album.php
    • image_instantiate(image)

      Invoked when an image object in instantiated.

      For example see plugin/xmpMetadata.php

      Invoked from:

      • class-image.php
    • image_metadata(object)

      Allows a plugin to modify image metadata when a new image is detected or when its metadata is refreshed.

      For example see plugin/xmpMetadata.php

      Invoked from:

      • class-image.php
    • image_refresh(imageobj)

      Invoked when an image object is refreshed during a garbage collect.

      For example see plugin/quota_manager.php

      Invoked from:

      • class-gallery.php
    • new_album(object)

      Invoked when a new album is discovered.

      For example see plugin/galleryArticles.php

      Invoked from:

      • class-album.php (2)
    • new_image(object)

      Invoked when a new image is discovered.

      For example see plugin/galleryArticles.php

      Invoked from:

      • class-image.php
      • plugin/class-textobject/class-textobject_core.php
      • plugin/class-video.php
    Root_class

    • check_credentials(bool, object, action)

      Called when an object is requested to verify that the logged on user is allowed to perform the action on the item.

      Invoked from:

      • classes.php
    • copy_object(bool, object, new_unique_set)

      Invoked when an object"s copy method is called.

      For example see plugin/multiple_layouts.php

      Invoked from:

      • classes.php (2)
    • move_object(bool, object, new_unique_set)

      Invoked when an object"s move method is called.

      Invoked from:

      • classes.php
    • object_addComment(name, email, website, comment, code, code_ok, object, ip, private, anon, customdata)

      Comment handlers attach to this filter to handle adding a comment to an object.

      For example see plugin/comment_form.php

      Invoked from:

      • classes.php
    • remove_object(bool, object)

      Invoked when an object"s remove method is called.

      For example see plugin/multiple_layouts.php

      Invoked from:

      • classes.php
    • save_object(bool, object)

      Invoked when an object"s save method is invoked.

      Invoked from:

      • classes.php
    • show_change(object)

      This filter is invoded whenever the state of the show property changes.

      For example see plugin/galleryArticles.php

      Invoked from:

      • classes.php
    Search

    • search_criteria(result)

      Allows a filter to modify a search.

      Invoked from:

      • class-search.php
    • search_instantiate(object)

      Called at the end of the class SearchEngine construct method.

      Invoked from:

      • class-search.php
    • search_statistics(searchstring, string, string)

      Allows a plugin to record statistics about searches.

      For example see plugin/search_statistics.php

      Invoked from:

      • class-search.php (4)
    • searchable_fields(this->search_structure)

      Allows plugins to add to the searchEngine search_structure.

      For example see plugin/common/fieldExtender.php

      Invoked from:

      • class-search.php
    Template filters

    These filters modify behavior of the functions that support Zenphoto themes.

    • admin_toolbox_' . $gal(redirect, zf)

      This filter is applied for the catch-all page load. $gal is the running gallery page script.

      Invoked from:

      • template-functions.php
    • admin_toolbox_album(albumname, zf)

      Allows plugins to insert links into the album part of the "admin toolbox".

      Invoked from:

      • template-functions.php
    • admin_toolbox_close(redirect, zf)

      This filter is applied just before the Admin Toolbox "logout" link is emitted.

      Invoked from:

      • template-functions.php
    • admin_toolbox_gallery(zf)

      Allows plugins to insert links into the gallery part of the "admin toolbox".

      Invoked from:

      • template-functions.php
    • admin_toolbox_global(zf)

      Allows plugins to insert links into the general part of the "admin toolbox".

      For example see plugin/favoritesHandler.php

      Invoked from:

      • template-functions.php
    • admin_toolbox_image(albumname, imagename, zf)

      Allows plugins to insert links into the image part of the "admin toolbox".

      For example see plugin/crop_image.php

      Invoked from:

      • template-functions.php
    • admin_toolbox_search(zf)

      Allows plugins to insert links into the search part of the "admin toolbox".

      Invoked from:

      • template-functions.php
    • checkForGuest(string)

      Invoked when loading a front-end page. Allows plugins to determine if a visitor has logged on with the correct credentials for accessing the object.

      For example see plugin/zenpage.php

      Invoked from:

      • template-functions.php
    • checkPageValidity(string, gallery_page, page)

      Called to process the "default" case in the page number validity function.

      For example see plugin/favoritesHandler.php

      Invoked from:

      • template-functions.php
    • codeblock(string, object, number)

      Allow plugins to create codeblock content on-the-fly.

      For example see plugin/defaultCodeblocks.php

      Invoked from:

      • template-functions.php
    • custom_album_thumb_html(html)

      Allows plugins to alter the HTML for an album thumbnail reference.

      For example see plugin/flag_thumbnail.php

      Invoked from:

      • template-functions.php
    • custom_image_html(html, thumbStandin)

      Allows plugins to alter the HTML for an image reference.

      For example see plugin/flag_thumbnail.php

      Invoked from:

      • template-functions.php (2)
      • plugin/paged_thumbs_nav.php
      • theme/effervescence_plus/functions.php
    • isMyItemToView(string)

      Invoked when checking if an object may be viewed by a user.

      For example see plugin/zenpage.php

      Invoked from:

      • template-functions.php
    • standard_album_thumb_html(html)

      Allows a plugin to modify the HTML used to reference an album thumb.

      For example see plugin/flag_thumbnail.php

      Invoked from:

      • template-functions.php
    • standard_image_html(html)

      Allows a plugin to modify the HTML used to reference an image.

      For example see plugin/image_effects.php

      Invoked from:

      • class-image.php
      • template-functions.php
    • standard_image_thumb_html(html)

      Allows a plugin to modify the HTML used to reference an image thumb.

      For example see plugin/flag_thumbnail.php

      Invoked from:

      • template-functions.php
    Theme filters

    These filters should be called from all themes. They provide a way for the Zenphoto core and for plugins to add HTML content to the theme.

    • theme_body_close()

      Invoked by all themes just before the </body> HTML tag.

      For example see template-filters.php

      Invoked from:

      • theme/default/404.php
      • theme/default/album.php
      • theme/default/archive.php
      • ...
    • theme_body_open()

      Invoked by all themes just after the <body> HTML tag.

      For example see plugin/downloadList.php

      Invoked from:

      • theme/default/404.php
      • theme/default/album.php
      • theme/default/archive.php
      • ...
    • theme_head()

      Invoked by all themes just after the <head> HTML tag.

      For example see plugin/jcarousel_thumb_nav.php

      Invoked from:

      • password.php
      • plugin/deprecated-functions/deprecated-functions.php (2)
      • theme/default/404.php
      • ...
    Upload filters

    • admin_upload_process(string)

      Allows plugins to modify the folder where an upload will place images.

      Invoked from:

      • plugin/uploader_http/uploader.php
      • plugin/uploader_jQuery/uploader.php
    • check_upload_quota(string, tmp_name)

      Invoked when images are being uploaded. The filter ay return an error indication. If so, the upload is aborted.

      For example see plugin/quota_manager.php

      Invoked from:

      • plugin/uploader_http/uploader.php
    • get_upload_header_text(string, string)

      Allows plugins to modify the header and/or error text for the upload tab.

      For example see plugin/quota_manager.php

      Invoked from:

      • admin-upload.php
    • get_upload_limit(maxuploadint)

      Allows a plugin to override the size limits on image uplaods

      For example see plugin/quota_manager.php

      Invoked from:

      • admin-upload.php
      • plugin/elFinder/php/connector_zp.php
    • upload_filetypes(types)

      Allows a plugin to modify the file types allowed for an upload.

      For example see plugin/xmpMetadata.php

      Invoked from:

      • admin-upload.php
      • plugin/uploader_jQuery/uploader.php
    • upload_handlers(string)

      Allows a plugin to provide an upload handler for the Upload tab.

      For example see plugin/uploader_http.php

      Invoked from:

      • admin-upload.php
    • upload_helper_js(string)

      Allows a filter to insert JavaScript into the upload tab.

      For example see plugin/quota_manager.php

      Invoked from:

      • admin-upload.php
    • upload_root_ui(string)

      Allows a plugin to determine if a user may create root level albums.

      Invoked from:

      • admin-upload.php
    User_management filters

    These filters allow the extension of the Zenphoto user object and authentication.

    • admin_alterrights(local_alterrights, userobj)

      Allows a plugin to control what user properties users are allowed to change.

      For example see plugin/user_groups.php

      Invoked from:

      • admin-users.php
    • admin_login_attempt(_zp_loggedin, post_user, post_pass)

      Reports Zenphoto logon attempts.

      For example see plugin/user-expiry.php

      Invoked from:

      • lib-auth.php
    • alt_login_handler(string)

      Allows filters to provide links to alternate logon handlers. This list is presented as a selection list on the logon form as alternates to the Zenphoto provided process.

      For example see plugin/federated_logon.php

      Invoked from:

      • lib-auth.php
    • authorization_cookie(loggedin, auth, id)

      Allows a plugin to override cookie based authorization credentials.

      For example see plugin/user-expiry.php

      Invoked from:

      • lib-auth.php
    • can_set_user_password(bool, pass, userobj)

      Called from the "apply" processing of an Zenphoto user. Return "false" to prevent the password from being saved.

      For example see plugin/user-expiry.php

      Invoked from:

      • admin-users.php
    • edit_admin_custom_data(string, userobj, id, background, current, local_alterrights)

      Allows a plugin to manage custom data for users. This invocation is for when the user object is presented for editing.

      For example see plugin/user-expiry.php

      Invoked from:

      • admin-users.php
      • plugin/user_groups/user_groups-tab.php
    • federated_login_attempt(bool, user)

      Invoked when a user logs on via the Federated_Logon plugin. (As opposed to logging on through the Zenphoto authentication mechanism)

      For example see plugin/user-expiry.php

      Invoked from:

      • plugin/federated_logon.php
    • guest_login_attempt(success, post_user, post_pass, authType)

      Invoked when a visitor logs on with a guest password.

      For example see plugin/ipBlocker.php

      Invoked from:

      • functions.php
    • login_link(string)

      Overrides the login link so that an external handler handles the login

      Invoked from:

      • template-functions.php
      • plugin/user_login-out.php
    • login_redirect_link(string)

      Filters the return link of the login form.

      For example see plugin/show_not_logged-in.php

      Invoked from:

      • lib-auth.php
    • register_user_registered(userobj)

      Invoked when a new user registers.

      Invoked from:

      • plugin/register_user.php
    • register_user_verified(userobj)

      Invoked when a new user is verified.

      Invoked from:

      • plugin/federated_logon.php
      • plugin/register_user.php
    • remove_user(object)

      Called in Zenphoto_Administrator remove method to allow plugins to clean up anything associated with the user.

      For example see plugin/user-expiry.php

      Invoked from:

      • lib-auth.php
    • save_admin_custom_data(updated, userobj, i, alter)

      Allows a plugin to manage custom data for Zenphoto users. This invocation is for when the user object is saved.

      For example see plugin/common/fieldExtender.php

      Invoked from:

      • admin-users.php
      • plugin/user_groups/user_groups-tab.php
    • save_user(string, adminobj, string)

      Invoked when a user object is saved.

      For example see plugin/security-logger.php

      Invoked from:

      • admin-users.php (2)
    • zp_logout(string, _zp_current_admin_obj)

      Provides a link to an external logout handler

      Invoked from:

      • lib-auth.php
    Zenpage filters

    • tinymce_zenpage_config(string)

      Filter used by "file manager" plugins to attach themselves to tinyMCE.

      For example see plugin/elFinder.php

      Invoked from:

      • plugin/tinymce4/config/zenpage-basic.js.php
      • plugin/tinymce4/config/zenpage-classic.js.php
      • plugin/tinymce4/config/zenpage-full.js.php
      • ...

    Creative Commons LicenseThis text by www.zenphoto.org is licensed under a Creative Commons Attribution-ShareAlike 3.0 Unported License.

    For questions and comments please use the forum or discuss on the social networks.

    Related items