Plugin Use Cases/Add Custom Theme Helper Functions

The following use case leads you through the creation of a plugin that adds custom theme helper functions. When a plugin is activated in Omeka, any PHP functions within it are available throughout all of Omeka, including your themes. By creating a custom theme helper function you can separate PHP logic from your theme, or avoid having to edit the same text in multiple places of your site by just sharing one function.

Files You'll Create in this Use Case

  • MyCustomThemeHelpers/ (folder)
    • plugin.ini
    • plugin.php

Use Case Steps

1. Create a new plugin folder with consideration given to its name, as well as an INI file to describe it create a php.ini file to describe your plugin. Of course, you'll also need to create a plugin.php file.

2. The plugin.php file is where you'll add any custom theme helper functions. This can be any unique php function, although it's standard for plugin writers to namespace their plugin functions with the name of their plugin. For example, the foo() function in my plugin will have the name my_custom_theme_helpers_foo() since this you're developing the MyCustomThemeHelpers plugin. This will avoid conflicts within Omeka's core, as well as with other plugins that may already have a foo() function.

Paste the following example code into your plugin.php file:

<?php
my_custom_theme_helpers_foo() {
/* any php code could be executed within this function
 * if called by a theme.
 */
 echo "foo!";
}
?>

The rest of the contents of this basic plugin are up to you. Save the files, upload them, and activate.. and you're all set! By including a reference to this helper function in your theme, you can run its code. It's very easy to take this example, and use it in conjunction with a plugin hook to Append HTML to Pages on the Admin Panel or with any other theme hook.

Note

While this use case demonstrates how to add custom theme helpers, it's also possible (and often preferred) to add custom theme helpers to a theme itself. The advantage to creating a separate plugin is that you can easily switch themes without having to remove code that's baked into them. Ultimately, the decision of where your custom theme helpers 'live' is up to you as the developer or site administrator.