Omeka Developer Documentation¶

Record-centric¶

The design of Omeka 1.x tended to treat different database records as superficially very different, despite the fact they all inherit from the same class. Thus, we had functions item() alongside collection(), both of which performed very similar jobs of retrieving data from a record. Similarly, we had loop_items() and loop_collections(). That pattern extended into our plugins, e.g. simple_page() and loop_simple_pages(). This created excessive duplication of functionality.

In Omeka 2.0, we instead concentrated on the similarity across all records, designing single functions for similar tasks that work by either passing in a record or by passing in the name of the record type current in a view. For example, to retrieve the id from the current item in a view, use metadata('item', 'id'). For a collection: metadata('collection', 'id').

This requires some attention to the names of your models and how they are assigned to the view. The first parameter to metadata() will be made singular, with the assumption that the view object has a record assigned to that property name. Similarly, looping assumes a plural form, an sets the current record to the singular name.

Function Naming Conventions¶

To make our function names more consistent and easier to understand, we have introduced the following naming conventions.

• Functions that return an array or object begin with get_
• Functions that return a boolean being with is_ or has_
• Functions do not echo a string. Instead they return the string

Zend 2.0 Class Naming Conventions¶

In anticipation of an eventual move to using Zend 2.0, we have reorganized our directories and class names to conform with Zend 2.0 conventions. Thus, the classes representing records and the table for them are no longer in the same directory. Instead, there is a Table directory inside the directory containing the models. The name of the table class should be the model’s class name prefixed with Table_, e.g. Table_SimplePagesPage.

Omeka an Archive?¶

While archivists can (and many do) use Omeka as a presentation layer to their digital holdings, Omeka is not archival management software. To underscore this fact, we’ve removed all mention of the word “archive” in the Omeka codebase and filesystem. This will require at least two additional steps when upgrading from earlier versions to 2.0:

1. Rename the archive/files/ directory to /archive/original/:

   $ mv /path/to/omeka/archive/files/ /path/to/omeka/archive/original/
   

2. Rename the archive/ directory to files/:

   $ mv /path/to/omeka/archive/ /path/to/omeka/files/
   

Logging and Debugging¶

Developers of both themes and plugins will need to be aware of the following changes in Omeka’s .htaccess file and config.ini file in application/config. Compare your existing files to the new .htaccess.changeme and config.ini.changeme files

• .htaccess now includes an environment variable for development: # SetEnv APPLICATION_ENV development

• config.ini now includes a setting for the minimal level of error logging. The default level is WARN. DEBUG is the lowest level of priority, and will show all messages. _log allows you to set your a priority, and the setting in config.ini must be set appropriately for the messages to be saved.

  ; log.priority
  ; The minimum priority level of messages that should be logged.
  ; default: Zend_Log::WARN (Logs warnings and above)
  log.priority = Zend_Log::DEBUG
  

  Note

  debug uses DEBUG priority, so to see messages logged by that function you must set the log priorty to DEBUG in config.ini.

Upgrading Plugins¶

As you look through the lists of typical tasks below, you might also want to consult Best Practices for Plugin Development

Typical tasks you will need to do to upgrade your plugins for Omeka 2.0 are:

• Change the classes your controllers and models extend from.
  • Omeka_Controller_Action becomes Omeka_Controller_AbstractActionController
  • Omeka_Record becomes Omeka_Record_AbstractRecord
• Update any helper functions you use in hooks for filters.
• Change your hook callbacks to have an array passed in. Typically, the expected variable name passed in in version 1.5 (e.g. $user) becomes the key for the corresponding data in the array, e.g. $user = $args['user'];. See Updating Plugins for 2.0: Hooks and Filters
• Update any filters you use. The third argument must now be an array to fit with the standard above.
• Change the helper functions used in the views * All functions of the form loop_{record type}, like loop_items(), become loop("{record type}")
• Change usage of functions that previously echoed content. For example, <?php head(); ?> should now be <?php echo head(); ?>.

Updating Themes¶

The number of global functions has been cut nearly in half in Omeka 2.0. This will require many changes to your themes, but will also make the patterns of usage much easier to follow and much more consistent.

Here are a few of the basic tasks for upgrading.

• Change the various metadata-retrieval functions for different record types (e.g., item(), collection(), etc) to the generalized metadata function.

• Change the loop structure for the various record types (e.g., loop_items(), loop_collections, etc) to the generalized loop function. Note that the structure changes from:

  while(loop_items()):
  

  to:

  foreach(loop('items') as $item):
  

• Use get_records when getting sets of any record within a theme. get_items, get_tags, and get_collections are all replaced by get_records.

• Change the structure of any arrays passed to nav. nav now uses the Zend_Navigation component, which changes the way you need to specify the array of nav links. Zend has some more expansive documentation on the available options, but it’s pretty simple to convert the old label => url pairs to the new style:

  echo nav(array(
      array('label' => 'Browse All', 'uri' => url('items'))
      array('label' => 'Browse By Tag', 'uri' => url('items/tags'))
  ));
  

• Change other global functions that have changed. There is a complete list of old and new function names on our wiki.

• Update calls to hooks and filters (wherever you use fire_plugin_hook and apply_filters). Typically, the expected variable name passed in in version 1.5 (e.g. $user) becomes the key for the corresponding data in the array, e.g. $user = $args['user']; See Updating Plugins for 2.0: Hooks and Filters

Use Omeka_Plugin_AbstractPlugin¶

Omeka_Plugin_AbstractPlugin is here to ease common steps in setting up your plugin. See Understanding Omeka_Plugin_AbstractPlugin for details.

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¶

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 Working with the Admin Theme, 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']);
}

Responsive Design¶

The Omeka Admin theme uses Skeleton development kit for easy, responsive styles. Each page consists of a twelve-column grid, with sections’ columns defined by css classes. For example, a three column section would have the classes “three columns”.

The first two columns are dedicated to navigation, while the latter ten holds the main content. Plugin views are contained within ten columns, and plugin writers should look to the structure of other admin views for markup patterns.

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 the “Add Item” view. 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.

<section class="seven columns alpha" id="edit-form">

    <form method="post" enctype="multipart/form-data" id="item-form" action="">

    ...

    </form>

</section>

<section class="three columns omega">

...

</section>

For reference:

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

Building a Configuration Form for Your Plugin¶

Most of the page, including the save button and overall layout is built for you. You only need to supply the actual inputs to use. The following template will help you build your forms in a way that is consistent with the rest of Omeka:

<div class="field">
    <div class="two columns alpha">
        <label></label>
    </div>
    <div class="inputs five columns omega">
        <p class="explanation"></p>
        <div class="input-block">
            <input />
        </div>
    </div>
</div>

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

Intro¶

This style guide is for use in writing themes for Omeka 2.0+. It borrows heavily from the Github style guide. This style guide is a work in progress, so excuse our dust.

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.

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>

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;
             }
     
     }
     

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 layouts 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');
    }
}