There are significant changes moving from Omeka 1.5 to Omeka 2.0. Principles of Omeka 2.0 offers an overall guide to the principles, both for theme developers and plugin developers.
Here, you will find a skeleton of typical tasks that will be required to migrate your code. Consult the reference section for code details.
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:
Rename the archive/files/ directory to /archive/original/:
$ mv /path/to/omeka/archive/files/ /path/to/omeka/archive/original/
Rename the archive/ directory to files/:
$ mv /path/to/omeka/archive/ /path/to/omeka/files/
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.
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:
The abstract class records extend from is now Omeka_Record_AbstractRecord, not Omeka_Record
The following callbacks have been removed, along with their associated plugin hooks:
A boolean insert argument for the beforeSave and afterSave callbacks replaces the insert/update hooks.
The saveForm and forceSave methods are removed. Use Omeka_Record_AbstractRecord::save instead.
Omeka_Acl is removed. All references to Omeka_Acl should be to Zend_Acl instead.
loadRoleList, loadResourceList, and loadAllowList were Omeka-specific methods, and are now gone. Now, just directly make individual calls to addRole(), addResource(), and allow(). You no longer need to use loadResourceList() to define the privileges for each resource.
checkUserPermission is also gone. Use isAllowed instead:
$acl->isAllowed(current_user(), 'Resource', 'privilege');
Many methods that were previously directly called on a Controller are now controller helpers instead.
The database wrapper methods findById(), getTable('TableName'), getDb() are removed in favor of the Db helper:
// old: $record = $this->findById();
$record = $this->_helper->db->findById();
// old: $element = $this->getTable('Element')->find($elementId);
$element = $this->_helper->db->getTable('Element')->find($elementId);
// old: $db = $this->getDb();
$db = $this->_helper->db->getDb();
The Db helper is also now used to set the default model name. The _modelClass property is removed in favor of setDefaultModelName from the Db helper:
// 1.x
public function init()
{
$this->_modelClass = 'MyModel';
}
// 2.0
public function init()
{
$this->_helper->db->setDefaultModelName('MyModel');
}
The flash, flashSuccess, and flashError methods are removed in favor of the FlashMessenger helper:
$this->_helper->flashMessenger('A neutral message');
$this->_helper->flashMessenger('A success message!', 'success');
$this->_helper->flashMessenger('An error message.', 'error');
Omeka_Context is removed. Resources are instead available directly through Zend_Registry or through the bootstrap object:
$acl = Zend_Registry::get('bootstrap')->getResource('Acl');
Many new CSS classes are available and should be used to ensure a consistent look and feel across Omeka plugins. It will be helpful to become familiar with them. For example, this is the new code structure to use if you need to create inputs yourself:
<div class="field">
<div class="two columns alpha">
<label for="some_input" class="required">Some Input Label</label>
</div>
<div class="inputs five columns omega">
<input type="text" name="some_input">
</div>
</div>
Admin theme now displays an <h1> with the title you set for the page. You can remove those from your admin views.
Use new save panel features. For ease of use in the most common cases, the Omeka_Form_Admin is available.
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