Docs For Class midcom_helper

Description

This class is a generic toolbar class, that is used mainly within AIS to render all toolbars in an uniform way. 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 acciociative array with the following elements:

 $item = Array (
     MIDCOM_TOOLBAR_URL =&gt; $url,
     MIDCOM_TOOLBAR_LABEL =&gt; $label,
     MIDCOM_TOOLBAR_HELPTEXT =&gt; $helptext,
     MIDCOM_TOOLBAR_ICON =&gt; $icon,
     MIDCOM_TOOLBAR_ENABLED =&gt; $enabled,
     [MIDCOM_TOOLBAR_OPTIONS] =&gt; array $options
 );

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 orignal 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 supress this feature.

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

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

The toolbar gets rendered as an unordered list, letting you define the CSS id and/or class tags of the list itself. The AIS 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:

 <ul [class="$class"] [id="$id"]>
   <li class="(enabled|disabled)">
     [<a href="$url" [title="$helptext"] [ $options as $key => $val ]>]
       [<img src="$calculated_image_url">]
       $label
     [</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 toolabr. Of course, the MidCOM AIS 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 toolbaritems. Here's a quick example to remove the underlining.

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

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

todo: Add usage example to this documentation

Located in /midcom/helper/toolbar.php (line 91)

Direct descendents

Class	Description
midcom_admin_content_toolbar	This class extends the main toolbar class so that it add the view page link where neccessary. It is a subclass, so that it can be easily disabled from components, in cases where no view page link is sensible.

Variable Summary

string $class_style

string $id_style

Array $items

Method Summary

midcom_helper_toolbar midcom_helper_toolbar ([string $class_style = 'midcom_toolbar'], [string $id_style = null])

void add_item (Array $item, [mixed $before = -1])

void disable_item (mixed $index)

void enable_item (mixed $index)

int get_index_from_url (string $url)

void move_item_down (mixed $index)

void move_item_up (mixed $index)

void remove_all_items ()

void remove_item (mixed $index)

string render ()

void update_item_url (mixed $index, string $url)

int _check_index (mixed $index)

Variables

string $class_style (line 107)

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

Set to null if non should be used.

string $id_style (line 99)

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

Set to null if non should be used.

Array $items (line 120)

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.

Methods

Constructor midcom_helper_toolbar (line 129)

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

midcom_helper_toolbar midcom_helper_toolbar ([string $class_style = 'midcom_toolbar'], [string $id_style = null])

string $class_style: The class style tag for the UL.
string $id_style: The id style tag for the UL.

add_item (line 155)

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. Alternativly, instead of specifying an index, you can specify an 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 an MidCOM Error.

void add_item (Array $item, [mixed $before = -1])

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

disable_item (line 302)

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

void disable_item (mixed $index)

mixed $index: The integer index or URL of the item to disable.

enable_item (line 291)

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

void enable_item (mixed $index)

mixed $index: The integer index or URL of the item to enable.

get_index_from_url (line 451)

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.

return: The index of the item or null, if not found.

int get_index_from_url (string $url)

string $url: The url to search in the list.

move_item_down (line 271)

Moves an item on place downwards in the list. This will only work, of course, if you are not working with the bottom element.

void move_item_down (mixed $index)

mixed $index: The integer index or URL of the item to move downwards.

move_item_up (line 250)

Moves an item on place upwards in the list. This will only work, of course, if you are not working with the top element.

void move_item_up (mixed $index)

mixed $index: The integer index or URL of the item to move upwards.

remove_all_items (line 239)

Clears the complete toolbar.

void remove_all_items ()

remove_item (line 217)

Removes a toolbar item based on its index or its URL

It will trigger a MidCOM Error upon an invalid index.

void remove_item (mixed $index)

mixed $index: The (integer) index or URL to remove.

render (line 346)

Renders the toolbar and returns it as a string.

return: The rendered toolbar.

string render ()

Redefined in descendants as:

midcom_admin_content_toolbar::render() : Renders the toolbar.

update_item_url (line 320)

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

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

void update_item_url (mixed $index, string $url)

mixed $index: The integer index or URL of the item to update.
string $url: The new URL to set.

_check_index (line 477)

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.

return: The valid index (possibly translated from the URL).
access: private

int _check_index (mixed $index)

mixed $index: The integer index or URL to check