This class is a generic toolbar class.

It supports enabling and disabling of buttons, icons and hover-helptexts (currently rendered using TITLE tags).

A single button in the toolbar is represented using an associative array with the following elements:

$item = Array (
    [MIDCOM_TOOLBAR_URL] => $url,
    [MIDCOM_TOOLBAR_LABEL] => $label,
    [MIDCOM_TOOLBAR_HELPTEXT] => $helptext,
    [MIDCOM_TOOLBAR_ICON] => $icon,
    [MIDCOM_TOOLBAR_ENABLED] => $enabled,
    [MIDCOM_TOOLBAR_HIDDEN] => $hidden
    [MIDCOM_TOOLBAR_OPTIONS] => array $options,
    [MIDCOM_TOOLBAR_SUBMENU] => midcom_helper_toolbar $submenu,
    [MIDCOM_TOOLBAR_ACCESSKEY] => (char) 'a',
    [MIDCOM_TOOLBAR_POST] => true,
    [MIDCOM_TOOLBAR_POST_HIDDENARGS] => array $args,
);

The URL parameter can be interpreted in three different ways: If it is a relative URL (not starting with 'http[s]://' or at least a '/') it will be interpreted relative to the current Anchor Prefix as defined in the active MidCOM context. Otherwise, the URL is used as-is. Note, that the Anchor-Prefix is appended immediately when the item is added, not when the toolbar is rendered.

The original URL (before prepending anything) is stored internally; so in all places where you reference an element by-URL, you can use the original URL if you wish (actually, both URLs are recognized during the translation into an id).

The label is the text shown as the button, the helptext is used as TITLE value to the anchor, and will be shown when hovering over the link therefore. Set it to null, to suppress this feature (this is the default).

The icon is a relative URL within the static MidCOM tree, for example 'stock-icons/16x16/attach.png'. Set it to null, to suppress the display of an icon (this is the default)

By default, as shown below, the toolbar system renders a standard Hyperlink. If you set MIDCOM_TOOLBAR_POST to true however, a form is used instead. This is important if you want to provide operations directly behind the toolbar entries - you'd run into problems with HTTP Link Prefetching otherwise. It is also useful if you want to pass complex operations to the URL target, as the option MIDCOM_TOOLBAR_POST_HIDDENARGS allows you to add HIDDEN variables to the form. These arguments will be automatically run through htmlspecialchars when rendering. By default, standard links will be rendered, POST versions will only be used if explicitly requested.

Note, that while this should prevent link prefetching on the POST entries, this is a big should. Due to its lack of standardization, it is strongly recommended to check for a POST request when processing such toolbar targets, using something like this:

if ($_SERVER['REQUEST_METHOD'] != 'post')
{
    throw new midcom_error_forbidden('Only POST requests are allowed here.');
}

The enabled boolean flag is set to true (the default) if the link should be clickable, or to false otherwise.

The hidden boolean flag is very similar to the enabled one: Instead of having unclickable links, it just hides the toolbar button entirely. This is useful for access control checks, where you want to completely hide items without access. The difference from just not adding the corresponding variable is that you can have a consistent set of toolbar options in a "template" which you just need to tweak by setting this flag. (Note, that there is no explicit access control checks in the toolbar helper itself, as this would mean that the corresponding content objects need to be passed into the toolbar, which is not feasible with the large number of toolbars in use in NAP for example.)

The midcom_toolbar_submenu can be used to create nested submenus by adding a pointer to a new toolbar object.

The toolbar gets rendered as an unordered list, letting you define the CSS id and/or class tags of the list itself. The default class for example used the well-known horizontal-UL approach to transform this into a real toolbar. The output of the draw call therefore looks like this:

The accesskey option is used to assign an accesskey to the toolbar item. It will be rendered in the toolbar text as either underlining the key or stated in parentheses behind the text.

<ul [class="$class"] [id="$id"]>
  <li class="(enabled|disabled)">
    [<a href="$url" [title="$helptext"] [ $options as $key => $val ]>]
      [<img src="$calculated_image_url">]
      $label
     [new submenu here]
    [</a>]
  </li>
</ul>

Both class and id can be null, indicating no style should be selected. By default, the class will use "midcom_toolbar" and no id style, which will yield a traditional MidCOM toolbar. Of course, the style sheet must be loaded to support this. Note, that this style assumes 16x16 height icons in its toolbar rendering. Larger or smaller icons will look ugly in the layout.

The options array. You can use the options array to make simple changes to the toolbar items. Here's a quick example to remove the underlining.

foreach ($toolbar->items as $index => $item) {
    $toolbar->items[$index][MIDCOM_TOOLBAR_OPTIONS] = array( "style" => "text-decoration:none;");
}

This will add style="text-decoration:none;" to all the links in the toolbar.

package midcom.helper

 Methods

__construct (string $class_style, string $id_style)

Basic constructor, initializes the class and sets defaults for the CSS style if omitted.

Note that the styles can be changed after construction by updating the id_style and class_style members.

Parameters

$class_style

stringThe class style tag for the UL.

$id_style

stringThe id style tag for the UL.

add_help_item (string $help_id, string $component, string $label, string $anchor, $before)

This function will add a help item to the toolbar.

Parameters

$help_id

stringName of the help file in component documentation directory.

$component

stringComponent to display the help from

$label

stringLabel for the help link

$anchor

stringAnchor ("a name" or "id" in HTML page) to link to

$before

add_item (array $item, mixed $before)

This function will add an item to the toolbar.

Set before to the index of the element before which you want to insert the item or use -1 if you want to append an item. Alternatively, instead of specifying an index, you can specify a URL instead.

This member will process the URL and append the anchor prefix in case the URL is a relative one.

Invalid positions will result in a MidCOM Error.

see \midcom_helper_toolbar::get_index_from_url()
see \midcom_helper_toolbar::_check_index()
see \midcom_helper_toolbar::clean_item()

Parameters

$item

arrayThe item to add.

$before

mixedThe index before which the item should be inserted. Use -1 for appending at the end, use a string to insert it before a URL, an integer will insert it before a given index.

add_item_to_index (array $item, int $index)

This function adds an item to another item by either adding the item to the MIDCOM_TOOLBAR_SUBMENU or creating a new subtoolbar and adding the item there.

Parameters

$item

arrayitem

$index

inttoolbar itemindex.

Returns

booleanfalse if insert failed.

bind_to (\DBAObject $object)

Binds this toolbar instance to a DBA content object using the MidCOM toolbar service.
see \midcom_services_toolbars

Parameters

$object

\DBAObject&$object The DBA class instance to bind to.

clean_item (array $item)

Clean up an item that is added, making sure that the item has all the needed options and indexes.

Parameters

$item

arraythe item to be cleaned

Returns

arraythe cleaned item.

disable_item (mixed $index)

Set's an item's enabled flag to false.

Parameters

$index

mixedThe integer index or URL of the item to disable.

enable_item (mixed $index)

Set's an item's enabled flag to true.

Parameters

$index

mixedThe integer index or URL of the item to enable.

get_index_from_url (string $url)

This function will traverse all available items and return the first element whose URL matches the value passed to the function.

Note, that if two items point to the same URL, only the first one will be reported.

Parameters

$url

stringThe url to search in the list.

Returns

intThe index of the item or null, if not found.

hide_item (mixed $index)

Set's an item's hidden flag to true.

Parameters

$index

mixedThe integer index or URL of the item to hide.

move_item_down (mixed $index)

Moves an item on place downwards in the list.

This will only work, of course, if you are not working with the bottom element.

Parameters

$index

mixedThe integer index or URL of the item to move downwards.

move_item_up (mixed $index)

Moves an item on place upwards in the list.

This will only work, of course, if you are not working with the top element.

Parameters

$index

mixedThe integer index or URL of the item to move upwards.

remove_all_items ()

Clears the complete toolbar.

remove_item (mixed $index)

Removes a toolbar item based on its index or its URL

It will trigger a MidCOM Error upon an invalid index.

see \midcom_helper_toolbar::get_index_from_url()
see \midcom_helper_toolbar::_check_index()

Parameters

$index

mixedThe (integer) index or URL to remove.

render ()

Renders the toolbar and returns it as a string.

Returns

stringThe rendered toolbar.

show_item (mixed $index)

Set's an item's hidden flag to false.

Parameters

$index

mixedThe integer index or URL of the item to show.

update_item_url (mixed $index, string $url)

Updates an items URL using the same rules as in add_item.

You should avoid updating a URL directly unless you are prepared to check for the possibly necessary anchor_prefix yourself.

see \midcom_helper_toolbar::get_index_from_url()
see \midcom_helper_toolbar::_check_index()
see \midcom_helper_toolbar::add_item()

Parameters

$index

mixedThe integer index or URL of the item to update.

$url

stringThe new URL to set.

_check_index (mixed $index, boolean $raise_error)

Private helper function which checks an index for validity.

Upon any error, a MidCOM Error is triggered.

It will automatically convert a string-based URL into an Index (if possible); if the URL can't be found, it will also trigger an error. The translated URL is returned by the function.

Parameters

$index

mixedThe integer index or URL to check

$raise_error

booleanWhether we should raise an error on missing item

Returns

int$index The valid index (possibly translated from the URL) or null on missing index.

_generate_item_label (array $item)

Helper function, generates a label for the item that includes its accesskey

Parameters

$item

arrayThe item to label

Returns

stringItem's label to display

_render_post_item (array $item)

Helper function, renders a form based link target.

Parameters

$item

arrayThe item to render

Returns

stringThe rendered item

 Properties

 

string $class_style

The CSS class-Style rule that should be used for the toolbar.

Set to null if non should be used.

 

Array $customdata

Allow our users to add arbitrary data to the toolbar.

This is for example used to track which items have been added to a toolbar when it is possible that the adders are called repeatedly.

The entries should be namespaced according to the usual MidCOM Namespacing rules.

 

string $id_style

The CSS ID-Style rule that should be used for the toolbar.

Set to null if non should be used.

 

Array $items

The items in the toolbar.

The array consists of Arrays outlined in the class introduction. You can modify existing items in this collection but you should use the class methods to add or delete existing items. Also note that relative URLs are processed upon the invocation of add_item(), if you change URL manually, you have to ensure a valid URL by yourself or use update_item_url, which is recommended.