Plugin API

Contents

Plugin Hooks

Plugin hooks are the primary ways your plugin can modify the behavior of Omeka. The add_plugin_hook() function contains two arguments:

  1. The name of the hook, which will run at a predefined time during an Omeka process. See below for some often used hooks.
  2. The name of your custom function (called a callback) that will be run at the specified time. It is important to ensure that your callback function is named uniquely, so we recommend prefixing your plugin name to the callback name. 
<?php add_plugin_hook('hook_name', 'plugin_name_callback_name'); ?>


<?php add_plugin_hook('install', 'myplugin_installer'); ?>


General Hooks

install

This hook only runs when the plugin is installed. It is primarily used to set plugin version number and other options to the database and to create tables. We do not recommend altering existing tables in the database, but rather create your own tables that use foreign key relationships.

initialize

This runs during every request on installed/activated plugins. It is primarily used to modify the runtime behavior of Omeka for every request and response.

config_form

This runs when the 'Configure' button is clicked for a specific plugin on the admin plugins panel. Use this hook to directly output the HTML that goes inside the form tag on your configuration form.

config

This hook processes the configuration form posted by the config_form hook. Most use cases will involve setting configuration options to the database using set_option().

Both config and config_form hooks are used when creating a configuration form for your plugin.

uninstall

This hook runs when a superuser uninstalls the plugin. We recommend that you completely remove all data that the plugin introduced into your system using delete_option() and DELETE SQL.

define_acl

This hook runs when Omeka's ACL is instantiated. It receives the Omeka_Acl instance as the first argument to the callback, which allows the plugin writer to manipulate the ACL that controls user access in Omeka. Omeka_Acl is subclassed from Zend_Acl.

define_routes

This hook runs when Omeka's router is instantiated. It receives a router instance as the first argument to the callback, which allows the plugin writer to add routes to Omeka. For more information on routes and Zend Framework, see ZF's documentation.

Admin Theme Hooks

admin_theme_header

arguments: $request Zend_Controller_Request_Http

location: in <head> tag of common/header.php in the admin theme

admin_theme_footer

arguments: $request Zend_Controller_Request_Http

location: in footer div of common/footer.php in the admin theme

admin_append_to_dashboard_primary

arguments: none

location: right before end of "primary" div on index.php of the admin theme

admin_append_to_dashboard_secondary

arguments: none

location: right before end of "secondary" div on index.php of the admin theme

admin_append_to_items_show_primary

arguments: none

location: right before end of "primary" div on items/show.php of the admin theme

admin_append_to_items_show_secondary

arguments: none

location: right before end of "secondary" div on items/show.php of the admin theme

admin_append_to_items_browse_primary

arguments: none

location: right before end of "primary" div on items/browse.php of the admin theme

admin_append_to_items_browse_detailed_each

arguments: none

location: inside the loop, inside the 'append-to-item-detail' div on items/detailed-view.php of the admin theme

admin_append_to_items_form_tags

arguments: $item Item

location: at the end of the tag-form div on the admin items form (items/tag-form.php)

admin_append_to_items_form_files

arguments: $item Item

location: at the end of the Files tab on the admin items form (items/files-form.php)

admin_append_to_items_form_collection

arguments: $item Item

location: at the end of the Collection tab on the admin items form (items/collection-form.php)

admin_append_to_users_form

arguments: $user User

location: at the end of the admin users form (users/form.php)

admin_append_to_collections_browse_primary

arguments: none

location: at the end of the "primary" div on collections/browse.php of the admin theme

admin_append_to_collections_show_primary

arguments: none

location: at the end of the "primary" div on collections/show.php of the admin theme

admin_append_to_collections_form

arguments: none

location: at the end of the admin collections form (collections/form.php)

admin_append_to_item_types_browse_primary

arguments: $itemtypes array of ItemType objects

location: at the end of the "primary" div on the item-types/browse.php of the admin theme

admin_append_to_item_types_show_primary

arguments: $itemtype ItemType object

location: at the end of the "primary" div on the item-types/show.php of the admin theme

admin_append_to_item_types_form

arguments: $itemtype ItemType object

location: at the end of the item-types form on the admin

admin_append_to_users_form

arguments: $user User object

location: at the end of the users form on the admin

admin_append_to_advanced_search

Public Theme Hooks

public_theme_header

arguments: $request Zend_Controller_Request_Http

location: in <head> tag of common/header.php in the public theme

public_theme_footer

arguments: $request Zend_Controller_Request_Http

location: in footer div of common/footer.php in the public theme

public_append_to_items_browse_each

arguments: none

location: wherever plugin_append_to_items_browse_each() is called (highly recommended that this be called only inside the loop on the items/browse.php page of the public theme

public_append_to_items_browse

arguments: none

location: wherever plugin_append_to_items_browse() is called (recommended that this only be called before the end of the "primary" div on items/browse.php of public theme

public_append_to_items_show

arguments: none

location: plugin_append_to_items_show(), end of "primary" div on items/show.php in public theme

public_append_to_collections_browse_each

arguments: none

location: see 'public_append_to_items_browse_each'

public_append_to_collections_browse

arguments: none

location: see 'public_append_to_items_browse'

public_append_to_collections_show

arguments: none

location: see 'public_append_to_items_show'

public_append_to_advanced_search

arguments: none

location: called right before the end of the search div on

Database Hooks

make_item_public

remove_item_tag

after_upload_file

make_item_not_public

make_item_featured

make_item_not_featured

make_collection_public

make_collection_not_public

make_collection_featured

make_collection_not_featured

item_browse_sql

add_item_tag

Implied database hooks

Database hooks that begin with "before_" and "after_" are implied and exist for every model that is defined, including models defined by plugins. Below are just a few of the available before/after hooks. The available events are save, save_form, delete, insert, update, and validate.

[before|after]_[event]_[record]

after_save_item

  1. Item $item

before_save_item

  1. Item $item

before_save_form_item

  1. Item $item
  2. ArrayObject $post

after_save_form_item

  1. (object) $record
  2. ArrayObject $post

before_delete_item

  1. Item $item

after_delete_item

  1. Item $item

before_insert_item

  1. Item $item

after_insert_item

  1. Item $item

before_update_item

  1. Item $item

after_update_item

  1. Item $item

before_validate_item

  1. Item $item

after_validate_item

  1. Item $item

Miscellaneous Hooks

show_itemtype

browse_itemtypes

browse_items

browse_tags

browse_collections

browse_users

show_item

show_user

show_collection

Filters

Filters are like plugin hooks except they are used to modify existing data in Omeka rather than add new behaviors.

An example of a filter: 

add_filter('admin_navigation_main', 'my_plugin_admin_navigation');
function my_plugin_admin_navigation($tabs)
{
  $tabs['Foobar'] = uri('foobar');
  return $tabs;
}

Note a few things from this example: The data to be filtered is always received as the first argument to the callback. That data must then be returned by the function in order for the filter to work properly. In this example, 'admin_navigation_main' is the name of the filter corresponding to the top-level navigation for the admin theme, and $tabs is a predefined array of navigation elements. This example will add a link to the admin navigation with the text 'Foobar', and the URI that is generated will be something like /omeka-site/admin/foobar.

General Filters

define_response_contexts

Filters the array of response contexts as passed to Zend Framework's ContextSwitch helper

define_action_contexts

filters the array of action contexts as passed to Zend Framework's ContextSwitch::addActionContexts()

html_escape

any content to escape for html entities

display_settings_* (option name, i.e. "site_title")

setting/option values displayed by the settings() helper function

Admin Theme Filters

admin_navigation_main

top-level navigation on the admin theme

admin_navigation_settings

side bar navigation on the settings page of the admin theme

admin_navigation_tags

secondary navigation on the admin tags page

admin_items_form_tabs

content of the tabs for the items form. Content takes the form of an array where key = name of the tab, value = HTML content for the tab

admin_navigation_items_browse

secondary nav on the admin/items/browse page

Public Theme Filters

public_navigation_main

top-level nav on the public theme, where public_nav_main() is called.

Miscellaneous Filters

array('Display', 'Item', 'Element Set Name', 'Element Name')

Customize the display of element texts for a particular element. This only applies to metadata rendered by the item() helper function. All element texts of this particular element are affected.

Passed arguments:

  1. $text (string): the text.
  2. $item (object): the Item record that applies to the element text.
  3. $elementText (object): the specific ElementText record.

Return: The customized element text.

array('Form', 'Item|File', 'Element Set Name', 'Element Name')

Customize the form input for a particular element. This only applies to forms generated by the display_form_input_for_element() helper function.

Passed arguments:

  1. $html (string): an empty string.
  2. $inputNameStem (string): the stem of the input name, e.g. "Elements[63][0]". Remember to append "[text]" or "[html]" to the stem to complete it.
  3. $value (string): the value of the input.
  4. $options (array): the other attributes of the form input.
  5. $record (object): the Item, File, or other record that applies to the element text.
  6. $element (object): the element text's Element record.

Return: The form input HTML.

array('Save', 'Item|File', 'Element Set Name', 'Element Name')

Customize element texts for a particular element before validating and saving a record. This is helpful if you want to prepare form data for validation automatically, limiting the possibility of a validation error.

Passed arguments:

  1. $elementText (string): The element text to modify.
  2. $record (object): the Item, File, or other record that applies to the element text.
  3. $element (object): the element text's Element record.

array('Validate', 'Item|File', 'Element Set Name', 'Element Name')

Perform a custom validation on a particular element. You must return boolean true or false.

Passed arguments:

  1. $isValid (boolean): the current value indicating whether or not the element text has validated.
  2. $textValue (string): the string value that needs to be validated
  3. $record (object): the Item, File, or other record that applies to the element text.
  4. $element (object): the element text's Element record.

Return: true|false.

Retrieved from "http://omeka.org/codex/Plugin_API"