\midcom_helper_toolbar_host

This class is a host toolbar class.

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] = [ "style" => "text-decoration:none;"]; } This will add style="text-decoration:none;" to all the links in the toolbar.

Properties

Methods