v 1.1.3

modo.ToggleGroup

The Toggle Group is a special type of container which can only contain elements of type modo.ToggleButton. There can be only one toggled Button in a Toggle Group at a time. If you toggle another (by script or user-interaction), the previously toggled button gets un-toggled.

Constructor

modo.ToggleGroup(params)modo.ToggleGroup

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

PropertyDescription

[untoggle]

Should always one element be toggled, or can all elements be untoggled? default: false

[elements]

Pass an array with key:value pairs in here, to create toggle buttons upon creation.

Example:

{
    "key1": "Label 1",
    "key2": "Label 2"
}

[selectedItem]

Pre-define, which key should be selected upon creation. Only use this when using the elements attribute.

[collection]

Pass a Backbone.Collection in here, to create the buttons from. The IDs of the contained Backbone.Models will be used as key, whereas the Model property defined with the pluck attribute will be used as button label.

[pluck]

Required when passing in a Backbone.Collection. This string defines, which Model property should be used as button label.

[updateOn]

Only has an effect, when using the collection attribute. This controls at which collection events the element should re-create its buttons. Default: add change remove sort

[layout]

Define here, if contained elements should be layed out in Block (modo.Container.NORMAL) or Inline-Block (modo.Container.INLINE) mode, by default. Default: modo.Container.NORMAL

[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.Container

Methods

add(obj)this

Use this function to add one or more modo.ToggleButton elements to the container. Will trigger the Backbone Event "add".

Heads up! The add function cannot be used like add() of a modo.Container or modo.FlexContainer. Elements added to a ToggleGroup need to recieve a key, which identifies each element inside the group.

To add one or more elements to the ToggleGroup, create them beforehand and pass them to the .add() function inside a object:

my_example_toggle_group.add({
    key1: myFirstToggleButton,
    key2: anotherToggleButton
});

Short-Hand Usage The add function can be used in short-hand mode. Pass a JavaScript object of strings to the function, to generate ToggleButtons automatically. Example:

{
    button1: 'My first button',
    button2: 'My second button'
}

This way you are not able to attach custom classes or event listeners on construction time.

remove(key)this

This will remove an element from the container. Either pass its key (string), or an array of keys to remove.

get()string

Returns the currently selected key of the group.

getElements()object

Returns the object that contains references to all contained elements.

getElementByKey(key)modo.ToggleButton

Returns the reference to the button element with the given id, if it exists.

set(key)this

Will toggle the button with the given key. This triggers the Backbone Event change.

Inherited Methods from modo.Container

add(element, ..., [options])this

Use this function to add one or more modo / jQuery / DOM elements to the container. Will trigger the Backbone Event "add", unless {silent: true} is passed as option object.

remove(element, ..., [options])this

This will remove one or more elements from the container. Either pass a modo element here, to get it removed from the container, or pass a jQuery selector to remove a DOM element.

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

change(key)

Triggered, when a user clicked on one of the contained modo.ToggleButtons, the selection has been changed by calling set(key) on the group, or by calling .set(true) on one of the contained ToggleButton elements.

add(child_element)

Triggered, when a child has been added through add()

Event ParameterDescription

child_element

A JavaScript object with both the elements key, and the element. Example: {key:element}

remove(child_element)

Triggered, when a child has been removed through remove()

Event ParameterDescription

child_element

A JavaScript object with both the elements key, and the element. Example: {key:element}

Inherited Events from modo.Container

add

Triggered, when a child has been added through add()

Event ParameterDescription

childElement

Can be either a modo element, a jQuery enhanced DOM object, or a DOM object

remove

Triggered, when a child has been removed through remove()

CSS Classes

mdo-togglegroup

Applied on the element.

Inherited CSS Classes from modo.Container

mdo-container

Applied to the modo element.

mdo-container-layout-normal

Applied when horizontal container layout is configured.

mdo-container-layout-inline

Applied when vertical container layout is configured.

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