v 1.1.3

modo.Toolbar

The modo toolbar can be used to create the classic application toolbars with groups of buttons to select tools from, or trigger certain actions.

The toolbar is treated as ONE modo element and has no real, accessable children. You can add and remove buttons via their given keys, but won't get a normal modo.Element interface for the unique buttons.

When a button is clicked, a event with the buttons key is fired on the toolbar element.

Buttons can be stacked into containers for visual separation. Its also possible to group buttons together logically, do get a radiobutton-like behaviour (for example to select a tool from a group of tools).

Constructor

modo.Toolbar(params)modo.Toolbar

The following list of parameters can be used in the params object, passed to the constructor. Parameters in [brackets] are optional.

PropertyDescription

[elements]

This attribute is used to set up the structure of the toolbar. You can create single buttons or directly stack them into groups.

Example:

elements: [
    {
        key: 'newDocument',
        disabled: true,
        className: 'newDocument',
        tooltip: 'Click to create a new Document',
        label: 'New Document'
    },
    [
        {
            key: 'tool1',
            label: 'Tool 1',
            group: 'tools'
        },
        {
            key: 'tool2',
            label: 'Tool 2',
            group: 'tools'
        }
    ]
]

Any property, except of key can be omitted. Notice that the two 'Tool' buttons are grouped together by stacking them into an array.

You cannot nest button groups.

[className]

A string with custom CSS classes to apply to the generated DOM element

[dataAttributes]

A object with attributes to assign to the generated DOM element. Omit the "data-" part. So for example {count: 1} becomes data-count="1" on the DOM element.

[el]

The jQuery enhanced DOM element to be generated. If nothing is set, a standard DIV container will be created. If you want to use a different DOM element, pass a jQuery generated DOM element to this parameter.

[showEffect]

The default show effect for the element. See associated property description. Default: null

[hideEffect]

The default hide effect for the element. See associated property description. Default: null

Properties

Inherited Properties from modo.Element

elObject

Contains the jQuery enhanced DOM Node of this modoJS element.

modoIdNumber

Contains a internally given, numeric ID for this element.

visibleBool

Will be set by .show() and .hide(). Access this property to check the current visibility of the element.

showEffectobject

Set a default show effect (like the options you can pass to the show() / hide() methods.

Example:

element.showEffect = {
    effect: 'slideDown',
    effectArgs: ['fast']
};

hideEffectobject

Define a default hide effect instead of a simple, instant hide.

Methods

add(obj)this

Adds a new button to the toolbar root. Pass an object like this:

{
    key: 'newDocument',
    disabled: true,
    className: 'newDocument',
    tooltip: 'Click to create a new Document',
    label: 'New Document',
    group: 'groupKey',
    data: {
        some: 'data'
    }
}

Any property, except key can be omitted.

To add a container, just pass an array to the function. The container may contain button objects.

addToContainer(containerIndex, obj)this

Works equally to add(), but adds the button to the container with the given index.

remove(key)this

Removes the button with the given key, no matter in which container it is stored. Will throw an exception if no element with the given key is found.

removeContainer(index)this

Removes the container with the given container index. Will throw an exception, if no container is found at that index. Notice: Buttons on the root level don't count to the index.

getElementByKey(key)$

Returns the jQuery enhanced DOM element of the button with the given key.

enableButton(key)this

Enables a toolbar button for user interaction.

disableButton(key)this

Disables a toolbar button for user interaction.

enableGroup(name)this

Enables all buttons of the given logical group.

disableGroup(name)this

Disables all buttons of the given logical group.

enableContainer(index)this

Enables all buttons inside the container with the given index.

disableContainer(index)this

Disables all buttons inside the container with the given index.

toggleButton(key)this

If the button with the given key is in a button group, it will be toggled. A previously toggled button from that group will be untoggled.

Inherited Methods from modo.Element

setFlexible([value])this

Pass either true or false to this value to make the element stretch inside a modo.FlexContainer element.

show(options)this

Make the connected DOM object visible and trigger the Backbone Event "show".

You can control the way the element is shown by passing an object of options.

Example:

element.show({
    effect: 'slideDown',
    effectArgs: ['fast']
});

hide()this

Make the connected DOM object invisible and trigger the Backbone Event "hide".

You can control the hide effect the same way as with the show() method.

addClass(classname, doPrefix)this

Will add another class name to the DOM element. The class name will be automatically prefixed (i.e. with mdo-) if doPrefix = true (default).

removeClass(classname, doPrefix)this

Will remove a class name from the DOM element. The class name will be automatically prefixed.

addClassTemporary(classname, timeout, doPrefix)this

Helps with adding a classname temporarily to the object. Just call this method and after the specified amount of time, the added class(es) will be removed.


Note: All modoJS Objects are extended with all methods of the Backbone.Events class.


Events

click

Will be fired on each click on ANY button. The listener function will get the click event as first attribute and the button key as second attribute.

click[key]

This is fired when a click on a certain button happens.

toggle[key]

Fired, when a toggle-able (grouped) button has been toggled.

untoggle[key]

Fired, when a toggle-able (grouped) button that has been toggled has now become untoggled, because another button from that group has been toggled.

grouptoggle[groupName]

Fired, when any toggle action has happened in the given group. The listener function gets the key of the toggled button as first attribute, the key of the previously toggled button as second attribute.

Inherited Events from modo.Element

show

Triggered, when the object has been displayed through show()

hide

Triggered, when the object has been hidden through hide()

CSS Classes

mdo-toolbar

Applied on the element itself.

mdo-toolbar-container

Applied on any container element that keeps buttons.

mdo-toolbar-container-empty

Applied on a container that doesn't contain any buttons.

mdo-toolbar-item

Applied on any toolbar button.

mdo-toolbar-item-[key]

Applied to any toolbar button, to style them uniquely.

Inherited CSS Classes from modo.Element

mdo-element

Basic class that will be applied to every element that extends modo.Element.

mdo-flexible

Will be applied to every modo element where setFlexible(true) has been called upon.

comments powered by Disqus