midcom.services.toolbars

1. MidCOM Toolbars Service
1. Benefit for component authors
2. Benefit for site authors
2. Component API
1. Node toolbar usage recommendations
2. View toolbar usage recommendations
3. Site API

MidCOM Toolbars Service

This document describes the MidCOM Toolbars Service as specified in mRFC 26.

Benefit for component authors

The main advantage for a component author is the unified, centralized way to build commands for the current user. They build upon the MidCOM Toolbars Helper classes introduced originally for AIS.

In addition, the MidCOM framework uses the toolbars (which are bound to specified objects) to add component independant options. Examples for this cover topic maintainance, ACL or Metadata hooks.

Benefit for site authors

Site authors have the advantage that they do not need to worry about toolbars for each component individually. Instead they have a central access point for each rendered where they draw the toolbar data from. This greatly simplifies the integration of administrative widgets on-site.

Component API

The Toolbars services is generally just a centralized access point for all toolbar related operations. It takes care of the context separation and the interfacing with the framework driven operation.

The framework provides you with convenience references to the toolbars applicable to the context you are currently working at. This covers the midcom_baseclasses_components_request and the midcom_baseclasses_components_handler baseclasses. Both provide authors with the two member variables $_node_toolbar and $_view_toolbar respecitivly.

Node toolbar usage recommendations

I recommend populating the node toolbar from the _on_handle callback of your main request class. The main reason for this is that this callback gets called unconditionally even when the framework uses handlers imported from other services instead of the component itself.

If you populate the node toolbar from the actual request handlers (which don't have an _on_handle callback, those items will vanish as soon as the user enters some topic maintainance (or similar) helper.

Example code, taken from net.nehmer.static:

/**
 * Populates the node toolbar depending on the users rights.
 *
 * @access protected
 */
function _populate_node_toolbar()
{
    if ($this->_content_topic->can_do('midgard:create'))
    {
        foreach (array_keys($this->_request_data['schemadb']) as $name)
        {
            $this->_node_toolbar->add_item(Array(
                MIDCOM_TOOLBAR_URL => "create/{$name}.html",
                MIDCOM_TOOLBAR_LABEL => sprintf
                (
                    $this->_l10n_midcom->get('create %s'),
                    $this->_request_data['schemadb'][$name]->description
                ),
                MIDCOM_TOOLBAR_ICON => 'stock-icons/16x16/new-text.png',
            ));
        }
    }

    if (   $this->_topic->can_do('midgard:update')
        && $this->_topic->can_do('midcom:component_config'))
    {
        $this->_node_toolbar->add_item(Array(
            MIDCOM_TOOLBAR_URL => 'config.html',
            MIDCOM_TOOLBAR_LABEL => $this->_l10n_midcom->get('component configuration'),
            MIDCOM_TOOLBAR_HELPTEXT => $this->_l10n_midcom->get('component configuration helptext'),
            MIDCOM_TOOLBAR_ICON => 'stock-icons/16x16/stock_folder-properties.png',
        ));
    }
}

/**
 * The handle callback populates the toolbars.
 */
function _on_handle($handler, $args)
{
    $this->_request_data['schemadb'] =
        midcom_helper_datamanager2_schema::load_database($this->_config->get('schemadb'));

    $this->_populate_node_toolbar();

    return true;
}

View toolbar usage recommendations

The view toolbar is used much like it was in the old AIS, mostly it is enough to move the AIS toolbar code to the on-site code.

Here, again an example from net.nehmer.static, taken from the view handler:

    if ($this->_article->can_do('midgard:update'))
    {   
        $this->_view_toolbar->add_item(Array(
            MIDCOM_TOOLBAR_URL => "edit/{$this->_article->guid}.html",
            MIDCOM_TOOLBAR_LABEL => $this->_l10n_midcom->get('edit'),
            MIDCOM_TOOLBAR_ICON => 'stock-icons/16x16/edit.png',
        ));
    }
    if ($this->_article->can_do('midgard:delete'))
    {   
        $this->_view_toolbar->add_item(Array(
            MIDCOM_TOOLBAR_URL => "delete/{$this->_article->guid}.html",
            MIDCOM_TOOLBAR_LABEL => $this->_l10n_midcom->get('delete'),
            MIDCOM_TOOLBAR_ICON => 'stock-icons/16x16/trash.png',
        ));
    }

Site API

Rendering the toolbars within your site is easy. The toolbars service provides you with interface methods which directly render the toolbar:

$_MIDCOM->toolbars->show_node_toolbar();
$_MIDCOM->toolbars->show_view_toolbar();

The CSS classes and IDs are configurable using the following MidCOM configuration options:

• toolbars_node_style_class defaults to "midcom_toolbar node_toolbar"
• toolbars_node_style_id defaults to ""
• toolbars_view_style_class defaults to midcom_toolbar view_toolbar
• toolbars_view_style_id defaults to ""
• toolbars_object_style_class defaults to midcom_toolbar object_toolbar