modo.List

A modo List generates lists from data sets. It can be either used by passing an array of objects as the data parameter, or a Backbone Collection.

modo.List elements are interactive. You can listen to events on the single list items and directly work with the list items dataset in the event callback.

Constructor

modo.List(params)modo.List

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

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

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

{
    'click': function(e,i,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();
        }
    }
}

Properties

lengthNumber

Provides access to the number of elements being rendered by the list.

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

get([limit])Array

This returns the lists filtered dataset in the same format as Backbones toJSON() method.

Note: This returns the dataset, the list itself works with, so in case a Backbone Collection is used as data source, the collector function defined in the constructor will be applied, first.

getFocusedIndex()Number

Returns the index of the currently focused item, if any.

getItemByKey(key)jQuery

Returns the jQuery-enhanced DOM element for a specific data key (array index, or Backbone.Collection id).

set(dataset, [options])this

Replaces the current dataset of the element and triggers a update.

update([options])this

This causes the lists HTML to be re-generated. Will be automatically called when a Backbone Collection is used as a data source and it emits one of the events, registered by passing updateOn to the constructor. This will trigger the Backbone Event "update".

focus()this

Sets the keyboard focus to the element. This means the user can select items from the list with his arrow keys. This needs the modo.keyListener to be loaded and will enable it. The list will put the keyListener in a scoped state to exclusively consume the key press events of the cursor buttons.

blur()this

Removes the keyboard focus from the element and also removes the scope from the keyListener.

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

update

Will be triggered when the update() function has been called (automatically, or manually).

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

Applied on the list element itself.

mdo-list-item

Applied to every single list-item element. This class is also automatically applied on list elements, generated by the itemRender function, defined in the element constructor.

mdo-list-empty-element

Applied on the element that is displayed when no elements are found in the data source. This element is only visible when generated from the emptyRender function, defined in the elements constructor.

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.