Version 8, last updated by fonny at 23 Mar 23:16 UTC

Adding Toolbars

The toolbar has been modelled against the HTML5 menu/toolbar specification to ensure as much forward compatibility with HTML5 as possible. We have adopted the concept of toolbar commands (formerly buttons). See :

Changes

The toolbar is now part of the controller package and is directly linked to a controller. You can use KControllerToolbarAbstract::getController() to retrieve the linked controller for this toolbar. This allows you to gain access to the model and view objects. Which is useful if your toolbar needs model state to decide how to render itself.
A toolbar is now also object array of KControllerToolbarCommand objects. Which means that you can easily iterate over it. Each command is stored by it's name. Which also means that the name of the command needs to be unique. You can use the KObjectArray API's to manipulate the toolbar.
A command object (KControllerToolbarCommand) extends from KConfig and holds specific parameters. A command requires a name, the config options passed are optional.
You can add command to the toolbar using the KControllerToolbar::addCommand() there is also a special KControllerToolbar::addSeperator() to deal with seperators. Api's here are modeled against the Java swing JToolbar class.
The toolbar title are now also set to default values by the ComDefaultControllerToolbarDefault. The generates meaning full defaults.

Specialisation

You can no longer specialise your toolbar through your views. A view doesn't know about the toolbar. Instead you need to specialise them through the toolbar object itself. For example see : https://nooku.assembla.com/code/nooku-server/subversion/nodes/trunk/code/administrator/components/com_articles/controllers/toolbars/articles.php?rev=1771

If you need to define special parameters for your toolbar command you can do so by creating a _command[Name] function in your specialised toolbar object and in this function you can set the command object. Example :

protected function _commandPublish(KControllerToolbarCommand $command)
{
    $command->append(array(
        'attribs'  => array(
            'data-action' => 'edit',
            'data-data'   => '{state:1}'
        )
    ));
}

This approach replaces the custom button classes that we had previously. I changed this to reduce overhead. It didn't make sense to create and load a whole now object through the factory just to set two parameters.

Rendering

The toolbar is being rendered by the new ComDefaultTemplateHelperToolbar in the administrator. (In the site application a default toolbar rendered hasn't implemented yet.) This helper is being called directly by ComDefaultDispatcher, see : https://nooku.assembla.com/code/nooku-framework/subversion/nodes/trunk/code/administrator/components/com_default/dispatcher.php?rev=3502#ln98
The toolbar behavior has been completely moved to Koowa.js with the addition of the Koowa.Controller.Form and Koowa.Controller.Grid classes. Both implemented specific behavior for the toolbar.

By completely decoupling the behavior of the toolbar from it's data and rendering, the toolbar can be very easy be customised, either by extended the javascript behavior, or by changing the way a toolbar is rendered.

the following may be out of date (17 Jun 11)

1. Working with toolbars in the front end

1.1 Make sure MooTools is loaded.

The toolbar buttons rely on MooTools for their javascript. If you are working in the back-end, then MooTools will already be loaded in your template. However, when you are working in the front end you will want to make sure that MooTools is loading. To load MooTools simply add the following to your template:

<?= @helper('behavior.mootools'); ?>

2. Modifying your toolbar

2.1 Loading your toolbars

To load a default toolbar for your front end form add the following:

<?= KService::get('com://site/foo.toolbar.view')->render(); ?>

where foo = your component and view = the view you are loading the toolbar for. This will then load a default toolbar for plural (new,cancel) or singular views (save, apply, cancel).

2.2 Modifying the buttons for your toolbar

To change the buttons you can either append to the default buttons or you can clear the buttons and add a new set of buttons.

Append a delete button:

<?= KService::get('com://site/prjtracker.toolbar.form')->append('delete')->render(); ?>

Clear the toolbar and add a delete button:

<?= KService::get('com::/site/prjtracker.toolbar.form')->reset()->append('delete')->render(); ?>

You can find all the default buttons currently in Nooku at: [joomla root]/libraries/koowa/toolbar/button

Nooku Framework