v 1.1.3

modo.MultiPicker

If you need the user to choose a couple of options from a pool of given values, utilize a Multipicker element.

Every value from the pool can be only chosen once.

Constructor

modo.MultiPicker(params)modo.MultiPicker

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

PropertyDescription

elements

A Object, Array or Backbone Collection with elements to be used as a pool to pick from.

selected

Pass an array to define a set of pre-selected elements. The array must contain indexes when you use a array as pool, keys if you use a object as pool or ids/cids when you use a Backbone Collection.

[buttonLabel]

The label for the 'Add' button. Defaults to +

[selectedRender]

Render function for the selected items. The default function can handle Objects and Arrays containing strings. Implement your own when using a Backbone Collection with models.

[pickMenuRender]

Render function for the available items menu. The default function can handle Objects and Arrays containing strings. Implement your own when using a Backbone Collection with models.

[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

_settingsObject

Settings object, used by the element. This will be set by the element constructor and should not be changed manually.

_selectedListmodo.List

Reference to the modo.List element used by the MultiPicker.

_pickButtonmodo.Button

Reference to the modo.Button element used to open the Dropdown to pick elements.

_pickMenumodo.List

Reference to the modo.List element used to display a list of selectable elements to the user.

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

set(elements, [options])this

Pass an array of keys to set the selected items for this element.

This triggers the Backbone Events change and change:selected. If you want to avoid the triggering of the Events, pass {silent:true} as the options parameter.

get()array

Returns the keys of the currently selected items.

setElements(elements, [options])this

Sets a new pool of items for the user to pick from. Please note that all previously selected keys are discarded when you set a new item pool. Pass either an Array, Object, or instance of Backbone.Collection as a item pool.

This triggers the Backbone Events change and change:elements. If you want to avoid the triggering of the Events, pass {silent:true} as the options parameter.

getElements()mixed

Returns the previously set pool of items.

update()this

Will trigger a redraw of the element. Normally not necessary to be called manually.

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

Triggered when the elements selection and/or item pool has been changed through calls to set() or setElements() or user interaction.

change:selected

Fired, when the selected items have been changed.

change:elements

Fired, when the pool of selectable items have been changed.

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-multipicker

Applied to the UI element.

mdo-multipicker-selected

Applied to the list, containing the selected items.

mdo-multipicker-button

Applied to the button that opens the menu of available items to select.

mdo-multipicker-menu

Applied to the list, containing the selectable items.

mdo-multipicker-menu-container

Applied to the DIV surrounding both the pick-button and the pool list. This is necessary to display the pool list as a dropdown menu.

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