v 1.1.3

modo.DropDown

The modo dropdown enables the user to select an item from an Array or a Backbone Collection.

It utilizes a modo.List to render the dropdown list.

Constructor

modo.DropDown(params)modo.DropDown

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

PropertyDescription

data

Either a array of JavaScript objects, or a Backbone Collection.

[buttonRender]

A function, used to render the selected item inside the dropdown button.
Works the same way, as the itemRender function.

[selectedItem]

This will set the dropdown to a specific item from the dataset. If you passed a array as data, pass an array index as item. If you passed a Backbone Collection as data, pass a data id or cid.

[placeholder]

A placeholder to be displayed, when the dropdown is initialized without pre-selecting an item.

[collector]

A function, which filters the dataset of the list, before rendering. This is applied if the "data" parameter contains a Backbone Collection. The function gets the lists data collection as a parameter. The default collector function is:

function(collection){ 
    return collection.filter(function(){return true;})
}

[updateOn]

An array of event names - fired by a Backbone Collection - on which the list should be re-rendered. Default: ['add', 'change', 'remove', 'sort']

[itemRender]

The render function for a single list item. Gets passed the serialized JavaScript object as function argument. In case of a Backbone Collection as data source, the according Backbone Model is added to the object as the property _m. By default, the first property of the serialized object is rendered. The default function is:

function (d, elementIndex, objectKeys) {
    for (var key in d) {
        if(key === '_m') continue;
        break;
    }
    return '>div>' + d[key].toString() + '>/div>'
}

Heads up!
The attribute elementIndex contains the index of the currently rendered list element, starting with zero. objectKeys is only available when the data source is an object and will then contain an array with all object keys as strings.

Notice: All rendered child elements get the CSS-Class modo-list-item added, after they have been rendered.

Tip: You can pass a compiled underscore template to use it as item renderer!

[itemEvents]

Events for list items are attached, the same way like events can be bound to a Backbone View. When you are using a Backbone Collection as data source, your event handler functions get passed the captured event as first parameter and the according Backbone Model from the collection as second parameter. You can either attach events directly to a list item, or to child-elements inside the list item (i.e. to attach edit/remove buttons). Example:

{
    'click': function(e,m){
        alert('You have clicked on the item ' + m.get('title'));
    },
    'click .removebutton': function(e,i,m){
        e.stopPropagation(); //Important! Or click will be fired too.
        if(confirm('Should ' + m.get('title') + ' be deleted?')){
            m.destroy();
        }
    }
}

[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

valueBool

Can be used to retrieve the current check status of the object.

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(item, [options])this

Will set the DropDown to a specific item from the dataset.
If you passed an array as dataset, pass an array index as item attribute.
If you passed an object as dataset, pass the key as item attribute.
If you passed a Backbone Collection as dataset, pass a model id, or cid.

If the desired element is not found in the dataset, an error will be thrown.

As usual, pass {silent: true} to suppress any change events.

setDataset(dataset, [options])this

If you need to update or change the dataset of the DropDown element, use this method. The method tries to re-select the previously selected element, so you may want to call myDropDown.set(null) before setting a new dataset that contains different elements.

get()mixed

Will return the index/key/id of the currently selected element.

getData()mixed

Will return the data value of the currently selected element. This cann be a string/integer/Backbone.Model or whatever items your dataset contains.

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 a new element has either been chosen manually, or through set().

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

Applied to the modo element.

mdo-dropdown-button

Applied to the button that toggles the dropdown list.

mdo-dropdown-list

Applied to the list element.

mdo-dropdown-dropped

Applied to the modo element when the dropdown button has been pressed and the list should be visible.

mdo-dropdown-selected

Applied to the currently selected element in the dropdown list. Mainly used for keyboard navigation.

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