Omeka Developer Documentation¶

The basics¶

There are a few things that any plugin must contain: the plugin folder, the plugin INI file, and the main plugin PHP file.

[info]
name = "Foo"
author = "My Name"
description = "Does this, that, and the other thing."
version = "1.0"
license = "GPLv3"
link = "http://example.com/my-plugin"
support_link = "http://example.com/my-plugin/support"
omeka_minimum_version = "2.0"
omeka_target_version = "2.2"
required_plugins = "ExhibitBuilder,SimplePages"
optional_plugins = "Bar,Baz"

Method Naming Conventions¶

Method names must be in camelCase (e.g., getItem()).

For private or protected methods, prefix the method name with underscore (_).

See also the Zend Framework Coding Standards.

Maintain expected behaviors in Omeka¶

Omeka defines some hooks that operate on every record. For example, Omeka’s Omeka_Record_AbstractRecord::save method fires hooks before and after saving. In most cases, you don’t need to override it, but if you do, make sure you include $this->runCallbacks('beforeSave', $callbackArgs); and $this->runCallbacks('afterSave', $callbackArgs); where appropriate.

Similarly, whenever you override methods from abstract classes in Omeka, make sure that you have studied the parent methods’ code to include all the expected callback. This will allow other developers to work with the expected behaviors of the objects.

Also, if you use any non-standard routing in your plugin, you must override Omeka_Record_AbstractRecord::getRecordUrl so that it returns the correct url to the record. Compare the getRecordUrl() method on the SimplePagesPage model in the “Simple Pages” plugin.

Database changes¶

Omeka 2.0 switched MySQL database engines from MyISAM to InnoDB. We recommend that you set all plugin tables to InnoDB. Existing plugins may alter their tables during the upgrade hook:

public function hookUpgrade($args)
{
    if (version_compare($args['old_version'], $newPluginVersion, '<')) {
        // Change the storage engine to InnoDB.
        $sql = "ALTER TABLE {$this->_db->TableName} ENGINE = INNODB";
        $this->_db->query($sql);
    }
}

Record API¶

We’ve made some major changes to the record API. The following internal callbacks have been removed:

• beforeSaveForm
• afterSaveForm
• beforeInsert
• afterInsert
• beforeUpdate
• afterUpdate
• beforeValidate
• afterValidate

As such, the following plugin hooks have been removed, where “*” is “record” or a specific record name (e.g. “item”, “collection”):

• before_save_form_*
• after_save_form_*
• before_insert_*
• after_insert_*
• before_update_*
• after_update_*
• before_validate_*
• after_validate_*

By removing these callbacks we give you full control over the timing of execution. Any logic that’s currently in the SaveForm, Insert, and Update callbacks should be moved to beforeSave() and afterSave(). Any logic that’s currently in the Validate callbacks should be moved to _validate(). For example:

// Note the order of execution.
public function beforeSave($args)
{
    if ($args['insert']) {
        // Do something before record insert. Equivalent to beforeInsert.
    } else {
        // Do something before record update. Equivalent to beforeUpdate.
    }

    // Do something before every record save.

    if ($args['post']) {
        // Do something with the POST data. Equivalent to beforeSaveForm.
    }
}

// Note the order of execution.
public function afterSave($args)
{
    if ($args['insert']) {
        // Do something after record insert. Equivalent to afterInsert.
    } else {
        // Do something after record update. Equivalent to afterUpdate.
    }

    // Do something after every record save.

    if ($args['post']) {
        // Do something with the POST data. Equivalent to afterSaveForm.
    }
}

Note that the signature of the beforeSave() and afterSave() has changed to beforeSave($args) and afterSave($args), with no type specified for $args. To adhere to strict standards, existing beforeSave and afterSave methods should reflect that change.

Another change is that Omeka_Record_AbstractRecord::saveForm() has been merged into save(). Using save() to handle a form in your controller can be done like this:

public function editAction()
{
    // Check if the form was submitted.
    if ($this->getRequest()->isPost()) {
        // Set the POST data to the record.
        $record->setPostData($_POST);
        // Save the record. Passing false prevents thrown exceptions.
        if ($record->save(false)) {
            $successMessage = $this->_getEditSuccessMessage($record);
            if ($successMessage) {
                $this->_helper->flashMessenger($successMessage, 'success');
            }
            $this->_redirectAfterEdit($record);
        // Flash an error if the record does not validate.
        } else {
            $this->_helper->flashMessenger($record->getErrors());
        }
    }
}

Use View Helpers instead of global functions¶

View helpers are preferred alternatives to global theming functions. They provide a convenient interface (called directly from the view object) to logic and/or markup that’s commonly used in view scripts. If you find yourself using global functions or static methods to support your views, consider using view helpers instead.

First, you must add your view helper directory path to the stack during plugin initialization:

public function hookInitialize()
{
    get_view()->addHelperPath(dirname(__FILE__) . '/views/helpers', 'PluginName_View_Helper_');
}

Replace PluginName with your plugin’s name. The helpers/ directory may be anywhere in your plugin’s directory structure, but we recommend that you place it in the views/ directory for consistency.

Then create your view helper file in the helpers/ directory (named something like ViewHelperName.php) and in that file write your view helper class:

class PluginName_View_Helper_ViewHelperName extends Zend_View_Helper_Abstract
{
    public function viewHelperName($arg1, $arg2)
    {
        // Build markup.
        return $markup;
    }
}

Note the use of UpperCamelCase and lowerCamelCase. The viewHelperName() method can accept any number of arguments and should return something, most often markup. You may add __construct() to the class if the helper needs a one-time setup (e.g. to assign class properties). The constructor will not be called on subsequent calls to the helper.

Now you can call your view helper directly in your view script like so:

<p><?php echo $this->viewHelperName() ?></p>

Use View Partials¶

View partials let you separate out parts of long or complicated views into separate files. For example, if you have a browse view that allows different ordering, it is best to use view partials to separate the code for the different orderings to be in different partials. For example:

<?php if (isset($_GET['view']) && $_GET['view'] == 'hierarchy'): ?>
    <?php echo $this->partial('index/browse-hierarchy.php', array('simplePages' => get_simple_pages_for_loop())); ?>
<?php else: ?>
    <?php echo $this->partial('index/browse-list.php', array('simplePages' => get_simple_pages_for_loop())); ?>
<?php endif; ?>

When using hooks that add markup to views, such as admin_items_show, consider using partials instead of outputting markup directly in the callback.

Use Jobs instead of Processes¶

We highly recommend that all processes that may run longer than a typical web process are sent to a job. The job will mediate the process, reducing the chance of timeout and memory usage errors that can happen even with the best written code. To run a job just write a class that contains the code to run, like so:

class YourJob extends Omeka_Job_AbstractJob
{
    public function perform()
    {
        // code to run
    }
}

You have two options on how to run the code: default and long-running. The default way is intended to run processes that, though are more processor-intensive than the typical web process, are usually not in danger of timing out. You can run these processes like so:

Zend_Registry::get('bootstrap')->getResource('jobs')->send('YourJob');

Your other option is intended for processes that will most likely result in a timeout error if run as a normal web script. Processes that import thousands of records or convert hundreds of images are examples of such processes. You can run these processes like so:

Zend_Registry::get('bootstrap')->getResource('jobs')->sendLongRunning('YourJob');

It’s important to note that nothing that uses the job system should assume or require synchronicity with the web process. If your process has to be synchronous, it shouldn’t be a job.

Load Resources for Jobs At Will¶

In previous versions, long running processes were fired directly through a background process via ProcessDispatcher::startProcess(), which loaded resources (e.g. Db, Option, Pluginbroker) in phases. Phased loading is now removed in favor of loading resources when needed.

When using the background process adapter for your jobs (typically used for long running jobs), the following resources are pre-loaded for you: Autoloader, Config, Db, Options, Pluginbroker, Plugins, Jobs, Storage, Mail. If you need other resources, load them like so in your job:

Zend_Registry::get('bootstrap')->bootstrap('YourResource');

Setting Up Your Plugin’s Config Page¶

You can provide a configuration page that will be linked from the Plugins page. Upon installing or upgrading a plugin that has a configuration form, Omeka redirects the user to the configuration page.

You provide the markup for your configuration form by using the config_form hook. Plugins often just require or include a config_form.php file, but any form of output will work. That hook is also the best place to read the current value of any options or other data that needs to be set on the form.

Omeka will provide a framework for most of the page for you: the page heading, the <form> element and the submit button are all provided and you do not need to write them.

To get form elements styled in a way that is consistent with the rest of the Omeka admin interface, you just need to use a simple set of CSS classes:

<div class="field">
    <div class="two columns alpha">
        <?php echo get_view()->formLabel('some-element', __('Some Element')); ?>
    </div>
    <div class="inputs five columns omega">
        <p class="explanation">
            <?php echo __('Any explanatory text about the form element.'); ?>
        </p>
        <?php echo get_view()->formInput('some-element', $someElementValue); ?>
    </div>
</div>

The submitted data will be sent back in a POST, and you can use the config hook to handle that data and actually update the options or other settings.

Building Forms in Admin¶

Omeka 2.0 admin interface works with modern CSS and design practices, including responsive design. Omeka 2.0 therefore also includes a Omeka_Form_Admin class to help you quickly and easily build simple forms. It should be suitable for building basic add/edit forms. The SimplePages plugin makes uses it, can can offer a good example of usage.

It is best to put your form-building logic into your controller, e.g. in a _getForm() method. The Omeka_Form_Admin class works basically as follows.

If you are editing an existing record, instantiate it like so: $form = new Omeka_Form_Admin(array('record'=>$record);

If the form is for a record (which is typically the case), pass the record as one of the options. Additionally, if you want a link to the record’s public page on the admin side, pass 'hasPublicPage'=>true as an option:

$options = array('record'=>$record, 'hasPublicPage'=>true);

Other options available for Omeka_Form_Admin are:

string type

Often, this will be the record type (e.g. ‘simple_pages_page’), but can be anything. Hooks for the save panel follow the type that you give. See admin_<type>_panel_buttons and admin_<type>_panel_fields.

string editGroupCssClass

Change the CSS classes for the ‘main’ edit area. This should rarely be necessary.

string saveGroupCssClass

Change the CSS classes for the save panel. This should rarely be necessary.

To add your form elements to the main editing area, use Omeka_Form_Admin::addElementToEditGroup. You can either pass in a Zend_Form_Element you have already built, or pass in the parameters to build the element as if you were creating one. For example, creating a text input looks like this:

$form->addElementToEditGroup(
    'text', 'title',
    array(
        'id'=>'simple-pages-title',
        'size'  => 40,
        'value' => metadata($page, 'title'),
        'label' => 'Title',
        'description' => 'The title of the page (required).',
        'required' => true
    )
);

The first argument specifies the element type (text, textarea, etc.). The second gives the name to be used on the element in the form. The third gives a keyed array of various attributes for the element, as well as a label and a description.

If you build the Zend_Form_Element yourself, you can simply pass that in as the first parameter and leave the rest empty.

In some cases, it makes sense to add an element directly to the save panel on the right. This should be reserved for small, peripheral data, such as whether a record is public or featured, if the model implements those features.

Doing so works similarly, using the Omeka_Form_Admin::addElementToSaveGroup method:

$form->addElementToSaveGroup(
    'checkbox', 'is_published',
    array(
        'id' => 'simple_pages_is_published',
        'values' => array(1, 0),
        'checked' => metadata($page, 'is_published'),
        'label' => 'Publish this page?',
        'description' => 'Checking this box will make the page public and it will appear in Simple Page navigation.'
    )
);

As with addElementToEditGroup(), you can build the element yourself and pass it as the first parameter.

For more complex form requiring tabs and a variety of sections, you’ll want to familiarize yourself with Understanding the Admin CSS.

See also workingwiththeadmintheme, which includes more details of how the HTML is constructed, and the CSS classes involved.

Search¶

Omeka 2.0 allows any record to be full-text searchable, not just items, but also files, collections, exhibits, etc. This includes records implemented by your plugin.

Individual record indexing and bulk-indexing will only work on record types that have been registered via the new search_record_types filter:

public function filterSearchRecordTypes($searchableRecordTypes)
{
    // Register the name of your record class. The key should be the name
    // of the record class; the value should be the human readable and
    // internationalized version of the record type.
    $searchableRecordTypes['YourRecord'] = __('Your Record');
    return $searchableRecordTypes;
}

Follow this template to make your record searchable:

class YourRecord extends Omeka_Record_AbstractRecord
{
    // Add the search mixin during _initializeMixins() and after any mixins
    // that can add search text, such as Mixin_ElementText. Doing this
    // tells Omeka that you want this record to be searchable.
    protected function _initializeMixins()
    {
        // Add the search mixin.
        $this->_mixins[] = new Mixin_Search($this);
    }

    // Use the afterSave() hook to set the record's search text data.
    protected function afterSave($args)
    {
        // A record's search text is public by default, but there are times
        // when this is not desired, e.g. when an item is marked as
        // private. Make a check to see if the record is public or private.
        if ($private) {
            // Setting the search text to private makes it invisible to
            // most users.
            $this->setSearchTextPrivate();
        }

        // Set the record's title. This will be used to identify the record
        // in the search results.
        $this->setSearchTextTitle($recordTitle);

        // Set the record's search text. Records that implement the
        // Mixin_ElementText mixin during _initializeMixins() will
        // automatically have all element texts added. Note that you
        // can add multiple search texts, which simply appends them.
        $this->addSearchText($recordTitle);
        $this->addSearchText($recordText);
    }

    // The search results need a route to the record show page, so build
    // a routing array here. You can also assemble the URL yourself using
    // the URL view helper and return the entire URL as a string.
    public function getRecordUrl($action)
    {
        if ('your-show-action' == $action) {
            return $yourCustomRecordShowUrl;
        }
        return array(
            'module' => 'your-module',
            'controller' => 'your-controller',
            'action' => $action,
            'id' => $this->id,
        );
    }
}

Once this is done you should enable the new search record type and re-index all records in your admin interface, under Settings > Search.

Customizing Search Type¶

Omeka now comes with three search query types: keyword (full text), boolean, and exact match. Full text and boolean use MySQL’s native full text engine, while exact match searches for all strings identical to the query.

Plugin authors may customize the type of search by implementing the search_query_types filter. For example, if you want to implement a “ends with” query type that searches for records that contain at least one word that ends with a string:

public function filterSearchQueryTypes($queryTypes)
{
    // Accept an array and return an array.
    function your_search_query_types_callback($queryTypes)
    {
        // Register the name of your custom query type. The key should be
        // the type's GET query value; the values should be the human
        // readable and internationalized version of the query type.
        $queryTypes['ends_with'] = __('Ends with');
        return $queryTypes;
    }
}

Then you must modify the search SQL using the search_sql hook, like so:

public function hookSearchSql($args)
{
    $params = $args['params'];
    if ('ends_with' == $params['query_type']) {
        $select = $args['select'];
        // Make sure to reset the existing WHERE clause.
        $select->reset(Zend_Db_Select::WHERE);
        $select->where('`text` REGEXP ?', $params['query'] . '[[:>:]]');
    }
}

Remember that you’re searching against an aggregate of all texts associated with a record, not structured data about the record.

Basics¶

Omeka_Db_Table is part of the Model part of Model-View-Controller in Omeka. It provides the methods for querying the database and returning results as Omeka_Record_AbstractRecord objects. The most frequently used methods in this class are Omeka_Db_Table::findBy and Omeka_Db_Table::find

Omeka_Db_Table::find simply returns a single record by the id passed in.

Omeka_Db_Table::findBy returns an array of records that match the criteria passed in with the $param argument. When creating your subclasses of Omeka_Db_Table, you will want to understand first how to build filters for queries using Omeka_Db_Table::findBy.

Omeka_Db_Table::findBy works by manipulating a Omeka_Db_Select object, which simplifies the process fo building simple SQL queries.

Filtering Queries¶

Omeka_Db_Table::findBy calls method Omeka_Db_Table::applySearchFilters. It takes a $select argument, and a $params argument. By default, this method simply checks the $params array passed in, looking for keys that match column names. For each match, a WHERE clause is generated.

Sometimes, though, it makes sense to add more complex logic. For example, you might want to filter a query by conditions on joining another table, or you might need to call a method in your subclass to process the data passed in the value of the parameter key. In such cases, Omeka has moved toward a pattern of using filterBy* methods.

In this pattern, you build more complex logic for adding a WHERE clause by passing in the $select object, and the value that you want to work with. Table_Collection offers a good example.

public function filterByPublic($select, $isPublic)
{
    $isPublic = (bool) $isPublic; // this makes sure that empty strings and unset parameters are false

    //Force a preview of the public collections
    if ($isPublic) {
        $select->where('collections.public = 1');
    } else {
        $select->where('collections.public = 0');
    }
}

This method does a little double-checking on the value passed in for whether the collection has been marked public, then applies the appropriate WHERE clause to the $select object.

In Table_Collection::applySearchFilters, we see the following to call it:

if(array_key_exists('public', $params)) {
    $this->filterByPublic($select, $params['public']);
}

Forms¶

Within the main content, Omeka forms typically take up seven columns, and leave the last three for a save panel that follows the user down the page. The following is an example of markup from a typical admin form. The “alpha” class signifies the first set of columns within a set, and “omega” signifies the last set of columns. These classes modify the left and right margins respectively.

<form method="post" enctype="multipart/form-data" action="">
    <section class="seven columns alpha">
        <!-- The main body of the form -->
    </section>
    <section class="three columns omega">
        <div id="save" class="panel>
            <!-- Submit button(s) and other small controls -->
        </div>
    </section>
</form>

For reference:

• Official Skeleton website
• Build a Responsive, Mobile-Friendly Web Page With Skeleton (For a more detailed guide on understanding and using Skeleton.)

Basics¶

The admin editing screen generally consist of two areas, the ‘main’ area and the ‘save panel’, which includes the save and delete buttons, as well as miscellaneous buttons and sometimes some form elements. Omeka_Form_Admin is meant to make building those areas in a way that keeps the look and feel as the rest of the admin theme as easy as possible for most kinds of forms. It does this by creating a DisplayGroup for each of the two areas, styling them appropriately, and letting you add your form elements to them.

It is generally best to put the logic for building your form inside a method of your controller, e.g. in _getForm($record). You then add it to your add and edit views the usual way: $this->view->form = $this->_getForm($record). Generally, extending Omeka_Form_Admin is not necessary.

Create the form like so:

protected function _getForm($record)
{

    $formOptions = array('type' => 'my_type', 'hasPublicPage'=>true);
    if($record && $record->exists()) {
        $formOptions['record'] = $record;
    }

    $form = new Omeka_Form_Admin($formOptions);

    // build the form elements

    return $form;
}

The form option type is required. Typically, this is the name of your record type (e.g., ‘item’). Hooks into the save panel are based on this type. See admin_<type>_panel_buttons, admin_<type>_panel_fields, and admin_<type>_form

hasPublicPage is a flag to determine whether a link to the record’s public page should be created in the save panel. Defaults to false.

Building the main edit area¶

The ‘main’ content area is where the primary parts of your form go: text inputs, most select dropdowns, etc.

Use the Omeka_Form_Admin::addElementToEditGroup to add your elements to the main edit area:

Building the save panel¶

The save and delete buttons will the automatically added to the save panel. Some true form elements also make more sense in this area than in the main editing area. Often, data that is entered via a simple checkbox is a good candidate for having the form element here. Whether a page is public or not is a good example.

$form->addElementToSaveGroup('checkbox', 'is_published',
                array('id' => 'my_plugin_is_published',
                        'values' => array(1, 0),
                        'checked' => metadata($record, 'is_published'),
                        'label' => 'Publish this page?',
                        'description' => 'Checking this box will make the page public.'
                ));

Examples¶

$form->addElement('textarea', 'description', array(
    'label' => __('Description'),
    'description' => __('My record description'),
    'rows' => 10
));

$form->addElement('text', 'user_email', array(
    'label' => __('Email'),
    'description' => __("Prefered email address of the person submitting the record"),
    'validators' => array('EmailAddress'),
    'required' => true
));

For a more extended example, see the IndexController::_getForm() method in the SimplePages plugin, bundled with Omeka.

See Also¶

• Omeka_Form
• Omeka_Form_Admin
• Understanding Omeka_Form_Admin

Overriding default templates¶

Omeka has a set of default template files that all themes use, and override when the desired page structure is different from the default.

The default theme files are in the folder /application/views/scripts in your Omeka installation. Subfolders correspond to the pages that are seen along url patterns. For example, the page displayed at {YourOmekaSite}/items/show is produced by the file in /application/views/scripts/items/show.php.

Themes might or might not override these files. The default theme, for example, has an items directory that overrides two of the default templates: random-featured.php and show.php

items/
    random-featured.php
    show.php

If you want to modify a file in a theme, the first place to look is in the theme’s own directories. But notice that that will only work if the theme has overridden the default template. In many cases, then, you will need to copy the default template files into the theme, taking care to maintain the directory structure.

So, for example, imagine wanting to modify the show page for items, the browse page for items, and the show page for collections in the default theme.

The /items/show.php file is easy, since the default theme already includes it.

For the browse page for items, we need to copy /application/views/scripts/items/browse.php to /default/items/browse.php

For the browse page for collections, we need to first create the directory: /default/collections

Then we can copy /application/views/scripts/collections/browse.php to /default/collections/browse.php

The result in the default theme will look like:

items/
   random-featured.php
   browse.php
   show.php
collections/
   browse.php

Configuration¶

When setting up the Compass configuration for a theme, the settings should be as follows:

http_path = "/"
css_dir = "/"
sass_dir = "sass"
images_dir = "images"
javascripts_dir = "javascripts"
output_style = :expanded
line_comments = false

When using Git, make sure you include a .gitignore in the root of your theme folder. The most common inclusions are:

.DS_Store
.sass-cache/

Organization¶

As such, the /css directory of an Omeka theme should follow the following structure:

|- css
|--- sass
|    |--- _base.scss
|    |--- _normalize.scss
|    |--- _print.scss
|    |--- _screen.scss
|    |--- style.scss
|--- config.rb
|--- style.css

Group your styles using commented headings and include a table of contents. Here is an example of a table of contents:

/*
Table of Contents
=================
-- General HTML Elements
----- Headings
----- Form Elements
-- Global Classes
-- Navigation
----- Pagination
-- Header
-- Footer
-- Content
*/

An example of a section heading:

/* !---------- Header ---------- */

Use the /* style of comments for headings you want to appear in the .css file. For Sass-only sections, such as the variables set in _bass.scss, use the // commenting syntax. The ! at the beginning of the header helps bookmark sections for theme writers using the Coda web editor.

General styles¶

• Use 4 spaces for indentation. Do not use tabs.
• Use spaces after : when writing property declarations.
• Put spaces before { in rule declarations.
• Use hex color codes #000 unless using rgba.

Overriding thumbnails in themes¶

The fallback thumbnails are simply theme assets, so they can be overridden by a theme just including its own image in the same location. The default fallbacks are located in application/views/scripts/images and are PNG images with names starting with fallback-. fallback-file.png is present in all Omeka versions, and Omeka 2.2 adds fallback-audio.png, fallback-video.png and fallback-image.png.

In a theme, you can just put your own versions of those files in the theme’s images folder. The default images are 200x200 pixel square PNGs.

Adding new fallback thumbnails¶

In addition to just overriding the existing thumbnails, you can also add new fallbacks with a plugin.

The function add_file_fallback_image is used to add a new fallback image for a given MIME type or type family. The first argument is the MIME type the fallback will apply to, and the second is the name of the image to use. The image name is internally passed to img. The plugin should place the actual fallback image in its views/shared/images folder.

The fallback will only be used for files lacking thumbnails that match the MIME type (or family) you pass. The “family” is the part of the MIME type before the slash, “image” for “image/jpeg” for example.

The call to add_file_fallback_image should be made in the plugin’s initialize hook.

Showing thumbnails for records¶

Instead of the existing functions which are different for every type of record that can have a thumbnail, the new representative file system has just one helper function: record_image. record_image works just like file_image or item_image, but it will work for any type of record that has a representative file.

So, a theme can use this same function across the views for any number of record types, and can even use it on views where multiple different record types may appear.

To directly use the existing functions that work on Files, you can also call the Omeka_Record_AbstractRecord::getFile method on the record, which will return the File object for the representative file. You can pass that File to helpers like file_markup.

Using representative files in plugin records¶

Plugins can also add representative file support to their own records. These records will then work with record_image, so the plugin’s views can use that function to show thumbnails. Thumbnails will also show when those records appear in search results and any other places already using record_image.

To have a representative files for its instances, a Record subclass must override Omeka_Record_AbstractRecord::getFile. getFile takes no arguments, and the record simply has to return a File object from it. Records can use any strategy they want to select a representative file.

For example, Omeka’s own records use a variety of strategies:

• Files return $this, since they “represent” themselves
• Items return their first attached File
• Collections select an item in the collection, preferring featured items, and return that item’s first File
• Exhibits return the attached File that appears earliest in the exhibit

Configuring a derivative strategy¶

You switch derivative strategies and set their options through the configuration file, application/config/config.ini. All the file derivative settings go under the key fileDerivatives.

To set the strategy Omeka will use when creating derivatives, use the fileDerivatives.strategy setting. The value of the setting should be the name of the strategy class you want to use. This class must implement Omeka_File_Derivative_StrategyInterface. You can swtich between the different strategies provided by Omeka, like ExternalImageMagick and Imagick, or switch to a new strategy of your own or one provided by a plugin. The string given must be the full name of the class.

Beyond just switching the entire strategy, you can also configure settings for each strategy through the config file. The key fileDerivatives.strategyOptions lets you specify named options that will be passed to the current strategy. For example, both the built-in Omeka strategies support an option gravity, which sets which part of an image will be kept when cropping for a square thumbnail. A site administrator would change this setting with one line in the config:

fileDerivatives.strategyOptions.gravity = "north"

Creating a new strategy¶

Derivative strategies are classes implementing Omeka_File_Derivative_StrategyInterface. The interface has one main entry point, the method createImage. createImage is called by Omeka once per derivative type (thumbnail, square thumbnail, fullsize) per file uploaded, and receives as arguments the source and destination file paths, the type of image being created, the configured size constraint, and the MIME type of the file.

createImage simply returns a boolean true/false value. If the return value is true, Omeka expects that a new derivative file will have been created at the destination path. A return value of false indicates that the derivative process failed and there is no derivative to upload. The strategy can use any means, including PHP libraries or extensions, or even shell calls, to create the new derivative, so long as it ends up in the correct location. Using the MIME type parameter and/or the source path, a strategy could even use totally different procedures for making derivatives for different kinds of files.

The interface also requires setOptions and getOptions methods, so Omeka can inject the settings from the site’s configuration file (see above). You can implement these simple methods yourself, or you can extend from Omeka_File_Derivative_AbstractStrategy, which provides those methods for you, but still leaves createImage as an abstract for you to override. The AbstractStrategy class also provides a convenience method, getOption, for getting a specific named option with a fallback or default value.

A strategy simply needs to be located in a location Omeka can autoload from to be available for the adiminstrator to select it in the config file. In a plugin this means the class should live in the libraries folder, at a path conforming to PSR-0.

Text¶

For most plugins and themes, making user-facing text translatable will be the lion’s share of the internationalization work. All text strings that are presented to the user and are not editable by the user should be translated. This includes obvious suspects like text in paragraphs and other visible HTML elements, but also less obvious places like the <title> element or title and alt attributes.

Omeka uses one function for enabling text translation, the __ (double-underscore) function. Anything that needs to be translated must be passed through the double-underscore function.

<p>Some text.</p>

<p><?php echo __('Some text.'); ?></p>

<?php
echo head(array(
    'title' => 'Page Title'
));
?>

<?php
echo head(array(
    'title' => __('Page Title')
));
?>

<?php
echo "The site contains $numItems items.";
?>

<?php
echo __('The site contains %s items.', $numItems);
?>

<?php
echo "Added $file to $item.";
?>

<?php
echo __('Added %s$1 to %s$2.', $file, $item);
?>

Dates and times¶

The other major thing you will often want to display differently for different for different locales are dates and times. Omeka comes pre-packaged with date formats for various locales already.

Where translations run through one function, the double-underscore function, dates and times similarly work with one function: format_date. format_date automatically selects the right format based on the site’s configured locale.

format_date takes two parameters. The first is the time you want to display. The second, which is optional, is the format you want to use. If you don’t pick a format, the default is an appropriate format for displaying a date.

Preparing Translation Files¶

Omeka reads translations from .mo files produced with GNU gettext. There are three steps to the process. After the basic work described above is complete, you will need to

1. Create a template file that includes all of the strings to translate
2. Create .po files that contain the actual translations
3. Compile .mo files that Omeka will use

The guide for these tasks below follows the practices used by the Omeka dev team. There are other tools and approaches that can accomplish the same tasks. The tool we use are

• ant build utility (along with a build.xml file described below)
• Transifex client (requires Python)
• podebug (requires Python)

# Translation for the Simple Pages plugin for Omeka.
# Copyright (C) 2011 Roy Rosenzweig Center for History and New Media
# This file is distributed under the same license as the Omeka package.
# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
#
#, fuzzy
msgid ""
msgstr ""
"Project-Id-Version: SimplePages\n"
"Report-Msgid-Bugs-To: http://github.com/omeka/plugin-SimplePages/issues\n"
"POT-Creation-Date: 2012-01-09 21:49-0500\n"
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
"Language-Team: LANGUAGE <LL@li.org>\n"
"Language: \n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"

msgid "allowed"
msgstr ""

msgid "required"
msgstr ""

<?xml version="1.0" encoding="UTF-8"?>
<project name="SimplePages" basedir=".">
    <property name="lang.dir" location="languages" />
    <property name="core.pot" location="../../application/languages/Omeka.pot" />
    <target name="update-pot" description="Update the translation template.">
        <property name="pot.file" location="${lang.dir}/template.pot"/>
        <property name="pot.base" location="${lang.dir}/template.base.pot"/>
        <tempfile property="pot.temp" suffix=".pot"/>
        <tempfile property="pot.duplicates" suffix="-duplicates.pot" />
        <copy file="${pot.base}" tofile="${pot.temp}"/>
        <apply executable="xgettext" relative="true" parallel="true" verbose="true">
            <arg value="--language=php"/>
            <arg value="--from-code=utf-8"/>
            <arg value="--keyword=__"/>
            <arg value="--flag=__:1:pass-php-format"/>
            <arg value="--add-comments=/"/>
            <arg value="--omit-header"/>
            <arg value="--join-existing"/>
            <arg value="-o"/>
            <arg file="${pot.temp}"/>
            <fileset dir="." includes="**/*.php **/*.phtml"
                excludes="tests/"/>
        </apply>
        <exec executable="msgcomm">
            <arg value="--omit-header" />
            <arg value="-o" />
            <arg file="${pot.duplicates}" />
            <arg file="${pot.temp}" />
            <arg file="${core.pot}" />
        </exec>
        <exec executable="msgcomm">
            <arg value="--unique" />
            <arg value="-o" />
            <arg file="${pot.temp}" />
            <arg file="${pot.temp}" />
            <arg file="${pot.duplicates}" />
        </exec>
        <move file="${pot.temp}" tofile="${pot.file}"/>
        <delete file="${pot.duplicates}" quiet="true" />
    </target>

    <target name="build-mo" description="Build the MO translation files.">
        <apply executable="msgfmt" dest="${lang.dir}" verbose="true">
            <arg value="-o"/>
            <targetfile />
            <srcfile />
            <fileset dir="${lang.dir}" includes="*.po"/>
            <mapper type="glob" from="*.po" to="*.mo"/>
        </apply>
    </target>
</project>

Placing layouts within your plugin¶

The new Exhibit Builder layouts use the same “views” system as other Omeka pages and views.

In any plugin (including the Exhibit Builder itself), layout views go in the path views/shared/exhibit_layouts.

Registering a new layout¶

Exhibit Builder provides a filter named exhibit_layouts. To add a new layout, you must hook into this filter and add some information about your new layout. You need to decide three things:

• ID: an internal name for the layout and the name of the layout folder
• Name: the admin user-facing name for the layout
• Description: the admin user-facing description of the layout

The ID is the key into the array of layouts, and the name and description are keys in an internal array. A filter implementation looks like this:

public function filterExhibitLayouts($layouts) {
    $layouts['new-layout'] = array(
        'name' => 'New Layout',
        'description' => 'A new layout.'
    );
    return $layouts;
}

Basic structure of an exhibit layout¶

Each layout has its own folder under the path mentioned above. The folder name is the layout’s ID, which will be used internally by the Exhibit Builder to find and store the layouts picked by the user. An ID is simply a text string, and the convention is that layout IDs be ASCII, lowercase, and hyphen-separated: sample-layout, not SampleLayout or SampleLayout.

Inside the layout folder, there are several files with predefined names that the Exhibit Builder will look for:

form.php

The PHP view file for the admin-side display of a form for the user to configure attachments, text, and options for a single block with this layout.

layout.php

The PHP view file for the public-side display of a single block with this layout.

layout.css

A CSS stylesheet that is automatically loaded when this layout is used on a public page.

layout.png

A PNG preview image for the layout. This image is displayed on the admin side when the user is selecting the layout to use. To fit with the images for the other layouts, the image should be 260 pixels wide by 140 pixels tall.

Your views can reference and use other files with names of your choosing, but the ones specified above are required and must be at the given locations.

The layout form – form.php¶

The page block that the layout is being used on is accesible in the form.php view as $block. This block object is passed to the form helpers and is used when form entries are created manually.

echo $this->exhibitFormAttachments($block);

echo $this->exhibitFormText($block);

$formStem = $block->getFormStem();

$options = $block->getOptions();

echo $this->formText($formStem . '[options][some-option]', @options['some-option']);

The layout view – layout.php¶

The layout view has four variables assigned to it.

$attachments

An array of the attachment objects for items the user has attached to this block.

$text

A string, containing the HTML text the user entered for this block. This text is filtered and can be output directly.

$options

An array of the options the user selected for this block.

$index

An integer, the index within the page of the current block.

foreach ($attachments as $attachment):
    echo $this->exhibitAttachment($attachment);
endforeach;

echo $this->exhibitAttachmentGallery($attachments);

foreach ($attachments as $attachment):
    $item = $attachment->getItem();
    $file = $attachment->getFile();
endforeach;

Layout style - layout.css¶

The layout.css file is automatically loaded when the layout is used on a page. Any given page can contain many different layouts simultaneously, so you need to take some care that you don’t write styles that will interfere with other layouts.

To help with keeping styles separate, Exhibit Builder automatically wraps your layout output in a div with the class layout-<your layout id. In general, styles in layout.css should start with that class selector as the first component of every selector.

Including extra assets¶

Some scripts, styles or other content can be included directly in layout.php. But, some content may need to be placed in the <head>, or may only be included in the page once. For these scenarios, Exhibit Builder provides a hook to add content to the head for exhibit pages. Note: layout.css is automatically included, so you don’t need to write anything to include it.

The hook is called exhibit_builder_page_head. It sends two arguments, the View object $view, and $layouts, a keyed array of the layouts in use on the page being shown. You can check for your layout ID in the keys of $layouts and include whatever content your layout needs:

public function hookExhibitBuilderPageHead($args) {
    if (array_key_exists('my-layout', $args['layouts'])) {
        queue_js_file('my-script');
    }
}

Adding a new shortcode¶

Shortcodes are added through the add_shortcode function. The function takes only two arguments: the name of the shortcode (what the user will type at the beginning of the shortcode) and a callback. A plugin adding a shortcode should call add_shortcode in its initialize hook.

The callback will be called whenever a shortcode is encountered in text, and is responsible for returning the markup that will actually be rendered on the page in place of the shortcode. Two parameters are passed to the callback. The first is an array of the arguments the user included in the shortcode (i.e. [my_shortcode arg1="value 1" arg2="value 2"] results in array('arg1' => 'value 1', 'arg2' => 'value 2') as the first parameter). The second argument is an Omeka_View instance, to simplify calling view helpers or reading data from the view.

So, in all, a plugin can add a shortcode with very little code:

class MyPlugin extends Omeka_PluginAbstractPlugin
{
    protected $_hooks = array('initialize');

    public function hookInitialize()
    {
        add_shortcode('my_shortcode', array($this, 'shortcode'));
    }

    public function shortcode($args, $view)
    {
        return 'This is a very simple shortcode.';
    }
}

Supporting shortcodes in user input¶

The flipside of adding new shortcodes is supporting shortcode replacement in text input by the user. To support shortcodes, you only need to pass the text through the shortcodes view helper.

Assuming $text is some text input by the user, you barely need to change your code that would have normally output the text:

/* No shortcode support: */
echo $text;

/* Shortcode support: */
echo $this->shortcodes($text);

You can also use the shortcodes helper on static text:

echo $this->shortcodes('[my_shortcode]');

Problem¶

When paging item by item using the next and previous buttons, Omeka calls the next item in the database by its ID, not by the order that you have searched or sorted prior to viewing the individual items.

Solution¶

My solution requires some changes to each theme.

1. Create a custom.php file to hold the new navigation function. The custom.php should be at the theme’s root (ex: /APP_DIRECTORY/themes/default/custom.php):

   function custom_paging()
   {
   //Starts a conditional statement that determines a search has been run
       if (isset($_SERVER['QUERY_STRING'])) {
   
           // Sets the current item ID to the variable $current
           $current = metadata('item', 'id');
   
           //Break the query into an array
           parse_str($_SERVER['QUERY_STRING'], $queryarray);
   
           //Items don't need the page level
           unset($queryarray['page']);
   
           $itemIds = array();
           $list = array();
           if (isset($queryarray['query'])) {
                   //We only want to browse previous and next for Items
                   $queryarray['record_types'] = array('Item');
                   //Get an array of the texts from the query.
                   $textlist = get_db()->getTable('SearchText')->findBy($queryarray);
                   //Loop through the texts ans populate the ids and records.
                   foreach ($textlist as $value) {
                           $itemIds[] = $value->record_id;
                           $record = get_record_by_id($value['record_type'], $value['record_id']);
                           $list[] = $record;
                   }
           }
           elseif (isset($queryarray['advanced'])) {
                   if (!array_key_exists('sort_field', $queryarray))
                   {
                           $queryarray['sort_field'] = 'added';
                           $queryarray['sort_dir'] = 'd';
                   }
                   //Get an array of the items from the query.
                   $list = get_db()->getTable('Item')->findBy($queryarray);
                   foreach ($list as $value) {
                           $itemIds[] = $value->id;
                           $list[] = $value;
                   }
           }
           //Browsing all items in general
           else
           {
                   if (!array_key_exists('sort_field', $queryarray))
                   {
                           $queryarray['sort_field'] = 'added';
                           $queryarray['sort_dir'] = 'd';
                   }
                   $list = get_db()->getTable('Item')->findBy($queryarray);
                   foreach ($list as $value) {
                           $itemIds[] = $value->id;
                   }
           }
   
           //Update the query string without the page and with the sort_fields
           $updatedquery = http_build_query($queryarray);
           $updatedquery = preg_replace('/%5B[0-9]+%5D/simU', '%5B%5D', $updatedquery);
   
           // Find where we currently are in the result set
           $key = array_search($current, $itemIds);
   
           // If we aren't at the beginning, print a Previous link
           if ($key > 0) {
               $previousItem = $list[$key - 1];
               $previousUrl = record_url($previousItem, 'show') . '?' . $updatedquery;
                   $text = __('← Previous Item');
               echo '<li id="previous-item" class="previous"><a href="' . html_escape($previousUrl) . '">' . $text . '</a></li>';
           }
   
           // If we aren't at the end, print a Next link
           if ($key >= 0 && $key < (count($list) - 1)) {
               $nextItem = $list[$key + 1];
               $nextUrl = record_url($nextItem, 'show') . '?' . $updatedquery;
                   $text = __("Next Item &rarr;");
                   echo '<li id="next-item" class="next"><a href="' . html_escape($nextUrl) . '">' . $text . '</a></li>';
           }
       } else {
           // If a search was not run, then the normal next/previous navigation is displayed.
           echo '<li id="previous-item" class="previous">'.link_to_previous_item_show().'</li>';
           echo '<li id="next-item" class="next">'.link_to_next_item_show().'</li>';
       }
   }
   

2. Make sure the query parameters are being passed: In the items/browse.php class, replace the line:

   <h2><?php echo link_to_item(metadata('item', array('Dublin Core', 'Title')), array('class'=>'permalink')); ?></h2>
   

with the following to pass the query and sorting parameters:

if(isset($_SERVER['QUERY_STRING']) && !empty($_SERVER['QUERY_STRING']))
{

    $searchlink = record_url('item').'?' . $_SERVER['QUERY_STRING'];

    echo '<h2><a href="'.$searchlink.'">'. metadata('item', array('Dublin Core','Title')).'</a></h2>';
}

else
{
    echo '<h2>'.link_to_item(metadata('item', array('Dublin Core','Title')), array('class'=>'permalink')).'</h2>';
}

3. Have the links changed to use the new custom code from custom.php: In the items/show.php class, replace the lines:

   <li id="previous-item" class="previous"><?php echo link_to_previous_item_show(); ?></li>
   
   <li id="next-item" class="next"><?php echo link_to_next_item_show(); ?></li>
   

with:

<?php custom_paging(); ?>

4. Make a copy of the application/views/scripts/search/index.php and place it under the THEME/search directory (create one if it isn’t already there).

5. To preserve the query and sort parameters: In search/index.php, replace the line:

   <td><a href="<?php echo record_url($record, 'show'); ?>"><?php echo $searchText['title'] ? $searchText['title'] : '[Unknown]'; ?></a></td>
   

with:

<?php

if(isset($_SERVER['QUERY_STRING']) && !empty($_SERVER['QUERY_STRING']))
{
        $searchlink = record_url($record, 'show').'?' . $_SERVER['QUERY_STRING'];

?>



        <td><a href="<?php echo $searchlink; ?>"><?php echo $searchText['title'] ? $searchText['title'] : '[Unknown]'; ?></a></td>

<?php
}
else
{

?>

        <td><a href="<?php echo record_url($record, 'show'); ?>"><?php echo $searchText['title'] ? $searchText['title'] : '[Unknown]'; ?></a></td>
<?php

}

?>

6. To make custom_paging work for items within an Exhibit (and sort by DC Date):

   • Add the following before //Browsing all items in general in Step 1.

   • Replace YOUR_SLUG_HERE with the slug for your Exhibit.

   • Replace YOUR_EXHIBIT_ID_HERE with your Exhibit ID.

   • Do this for each of your Exhibits.:

     //Browsing exhibit YOUR_EXHIBIT_ID_HERE items
     elseif (strpos($_SERVER['HTTP_REFERER'],'exhibits/show/YOUR_SLUG_HERE') != false) {
             $exhibit_query = "search=&advanced[0][element_id]=&advanced[0][type]=&advanced[0][terms]=&range=&collection=&type=&user=&public=&featured=&exhibit=YOUR_EXHIBIT_ID_HERE&submit_search=Search&sort_field=Dublin+Core%2CDate";
             parse_str($exhibit_query, $queryarray);
             unset($queryarray['page']);
     
             if (!array_key_exists('sort_field', $queryarray))
             {
                     $queryarray['sort_field'] = 'added';
                     $queryarray['sort_dir'] = 'd';
             }
             //Get an array of the items from the query.
             $list = get_db()->getTable('Item')->findBy($queryarray);
             foreach ($list as $value) {
                     $itemIds[] = $value->id;
                     $list[] = $value;
             }
     
     }