\midcom_helper_toolbar_node

This class is a node (topic) 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.

Summary

Methods
Properties
Constants
__construct()
bind_object()
get_approval_controls()
get_label()
set_label()
add_help_item()
add_item()
add_items()
add_item_to_index()
clean_item()
remove_item()
remove_all_items()
move_item_up()
move_item_down()
enable_item()
disable_item()
hide_item()
show_item()
update_item_url()
render()
get_index_from_url()
bind_to()
$id_style
$class_style
$items
$customdata
No constants found
No protected methods found
$label
N/A
set_url()
_generate_item_label()
_render_link_item()
get_item_attributes()
_render_post_item()
_check_index()
add_commands()
$topic
N/A

Properties

$id_style

$id_style : string

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

Set to null if none should be used.

Type

string

$class_style

$class_style : string

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

Set to null if none should be used.

Type

string

$items

$items : Array

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.

Type

Array

$customdata

$customdata : Array

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.

Type

Array

$label

$label : string

The toolbar's label

Type

string

Methods

__construct()

__construct(\midcom_db_topic  $topic) 

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

\midcom_db_topic $topic

get_approval_controls()

get_approval_controls(\midcom_core_dbaobject  $object,   $add_accesskey = false) 

Parameters

\midcom_core_dbaobject $object
$add_accesskey

get_label()

get_label() : string

Returns

string

set_label()

set_label(string  $label) 

Parameters

string $label

add_help_item()

add_help_item(string  $help_id, string  $component = null, string  $label = null, string  $anchor = null,   $before = -1) 

Add a help item to the toolbar.

Parameters

string $help_id

Name of the help file in component documentation directory.

string $component

Component to display the help from

string $label

Label for the help link

string $anchor

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

$before

add_item()

add_item(array  $item, mixed  $before = -1) 

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.

Parameters

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 a URL, an integer will insert it before a given index.

add_items()

add_items(array  $items, mixed  $before = -1) 

Convenience shortcut to add multiple buttons at the same item

Parameters

array $items

The items 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 a URL, an integer will insert it before a given index.

add_item_to_index()

add_item_to_index(array  $item, integer  $index) : boolean

Add 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

array $item
integer $index

toolbar item index.

Returns

boolean —

false if insert failed.

clean_item()

clean_item(array  $item) : array

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

Parameters

array $item

the item to be cleaned

Returns

array —

the cleaned item.

remove_item()

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.

Parameters

mixed $index

The (integer) index or URL to remove.

remove_all_items()

remove_all_items() 

Clears the complete toolbar.

move_item_up()

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

mixed $index

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

move_item_down()

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

mixed $index

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

enable_item()

enable_item(mixed  $index) 

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

Parameters

mixed $index

The integer index or URL of the item to enable.

disable_item()

disable_item(mixed  $index) 

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

Parameters

mixed $index

The integer index or URL of the item to disable.

hide_item()

hide_item(mixed  $index) 

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

Parameters

mixed $index

The integer index or URL of the item to hide.

show_item()

show_item(mixed  $index) 

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

Parameters

mixed $index

The integer index or URL of the item to show.

update_item_url()

update_item_url(mixed  $index, string  $url) 

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

Parameters

mixed $index

The integer index or URL of the item to update.

string $url

The new URL to set.

render()

render() : string

Renders the toolbar and returns it as a string.

Returns

string —

The rendered toolbar.

get_index_from_url()

get_index_from_url(string  $url) : integer

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

string $url

The url to search in the list.

Returns

integer —

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

bind_to()

bind_to(\midcom_core_dbaobject  $object) 

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

Parameters

\midcom_core_dbaobject $object

The DBA class instance to bind to.

set_url()

set_url(array  $item,   $url) 

Parameters

array $item
$url

_generate_item_label()

_generate_item_label(array  $item) : string

Generate a label for the item that includes its accesskey

Parameters

array $item

The item to label

Returns

string —

Item's label to display

_render_link_item()

_render_link_item(array  $item) : string

Render a regular a href.

.. based link target.

Parameters

array $item

The item to render

Returns

string —

The rendered item

get_item_attributes()

get_item_attributes(array  $item) 

Parameters

array $item

_render_post_item()

_render_post_item(array  $item) : string

Render a form based link target.

Parameters

array $item

The item to render

Returns

string —

The rendered item

_check_index()

_check_index(mixed  $index, boolean  $raise_error = true) : integer

Check an index for validity.

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

mixed $index

The integer index or URL to check

boolean $raise_error

Whether we should raise an error on missing item

Throws

\midcom_error

Returns

integer —

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

add_commands()

add_commands()