Understanding Omeka_Form_Admin

Omeka_Form_Admin is designed to make it easier for most plugins to conform to the look and feel of Omeka’s admin interface. In most, but not all, cases, this class will let you easily construct your form. More complex forms might require building the form from scratch.

Like the rest of Omeka, it relies heavily on Zend’s form elements. Read Understanding Form Elements for a primer.

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.'
                ));