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.
Property | Description |
---|---|
data | Either a array of JavaScript objects, or a Backbone Collection. |
[collector] | A function, which filters the dataset of the list, before rendering. The function gets the lists data collection as the first parameter and a boolean true/false if its a Backbone Collection as second parameter. The default collector function is:
|
[updateOn] | An array of event names - fired by a Backbone Collection - on which the list should be re-rendered. Default: |
[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
Heads up!
The attribute Notice: All rendered child elements get the CSS-Class Tip: You can pass a compiled underscore template to use it as item renderer! PRO Tip: You can return ONE modo.* element from the renderer method instead of a HTML string! |
[emptyRender] | This function is called when the list has no items to display (dataset is empty). |
[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:
|
[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 |
[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: |
[hideEffect] | The default hide effect for the element. See associated property description. Default: |
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.
Function parameter | Description |
---|---|
[limit] | Optional parameter to limit the amount of returned entries to the given number. |
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.
Function parameter | Description |
---|---|
dataset | The new dataset to be used. Can be an array, or a Backbone.Collection |
options | An options object. |
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.