List - Documentation

Constructor

new List(props)

Data connected to Elements using a template.

Source:

List.js, line 32

Properties:

Name	Type	Attributes	Default	Description
`$dom`	Element \| jQuery			The container for rendered elements.
`$tmpl`	Element \| jQuery			The template for a single item.
`selector`	string	<optional>	`"li"`	The query selector for rendered items.

A list is a kind of duil.Group that connects data to Elements similar to an HTML template, except it doesn't require a special syntax.

You may use raw DOM nodes or jQuery-like objects interchangeably with this class.

Example

var myList = duil.List({
  $dom: $('<ul id="my-list"><li></li></ul>'),
  selector: 'li'
});

myList.set({data: [1, 2, 3]});
// => <ul id="my-list"><li>1</li><li>2</li><li>3</li></ul>

Parameters:

Name	Type	Description
`props`	Object	The initial properties of the widget.

Extends

duil.Group

Methods

init() → {duil.Widget}

Initialize the widget.

Source:

Widget.js, line 74

Overrides:

duil.Group#init

This method is called when the widget is constructed. Instances will often override this method.

The default method simply fires init and returns the widget.

Common uses of the .init() method:

binding event handlers
triggering one-time operations (e.g., ajax requests)
initializing variables that are not available during construction

Example

var MyWidget = new duil.Widget({
  // @override
  init: function () {
    this.value = 42;
    return this;
  }
});

console.log(MyWidget.value);
// => 42

Fires:

duil#event:init

Returns:

The widget itself for chaining.

Type: duil.Widget

key(model, index) → {Object}

Get the view that corresponds to the given model.

Source:

Group.js, line 120

Inherited From:

duil.Group#key

This method is called during Group.duil.render to determine which view should be updated.

If this method returns null, a new view will be created.

By default, this method assumes that both models and views are in the same order. Alternatively, if they are in different orders, but have an id property in common, you can used duil.Group.KEY_BY_ID.

In general, you should not have to override this method unless your models are not in a guaranteed order and it is cheaper to map from models to views in some other way.

Parameters:

Name	Type	Description
`model`	*	The model whose view we want.
`index`	number	The index of the model.

Returns:

Returns the view or null if none is found.

Type: Object

create(model, index) → {Object}

Create a new view for a given model.

Source:

Group.js, line 129

Overrides:

duil.Group#create

Parameters:

Name	Type	Description
`model`	*	The model that needs a new view.
`index`	number	The index of the model.

Fires:

duil#event:create

Returns:

Returns the newly-created view.

Type: Object

update(view, model, index) → {Object}

Update a view to match its model.

Source:

Group.js, line 154

Overrides:

duil.Group#update

Parameters:

Name	Type	Description
`view`	Object	The view to update.
`model`	*	The model for the view.
`index`	number	The index of the model.

Fires:

duil#event:update

Returns:

Returns the now-updated view.

Type: Object

remove(view, index) → {duil.Group}

Remove the views that are no longer backed by a model.

Source:

Group.js, line 186

Overrides:

duil.Group#remove

This function is similar to the d3 concept of exit(). These are the views that no longer have data associated with them and should be removed. The defualt behavior is to simply remove them from the array of views.

You should override this method to perform the appropriate clean up action that disposes of the view.

Parameters:

Name	Type	Description
`view`	Object	The views to remove.
`index`	number	The index of the view.

Fires:

duil#event:remove

Returns:

Returns the group for chaining.

Type: duil.Group

render(changes) → {duil.Group}

Update the mapping between models and views.

Source:

Group.js, line 214

Inherited From:

duil.Group#render

If there are no changes, there's nothing to render.

Changes are merged into any pending changes and are added to a queue. If the number of changes is small, all changes are processed before returning. Otherwise, if enabled, rendering takes place over time.

Parameters:

Name	Type	Description
`changes`	Object \| number	The changes that occured to this widget or the number of the row whose change we're updating (in recursive mode).

Fires:

duil#event:render

Returns:

Returns the group for chaining.

Type: duil.Group

drain() → {duil.Group}

Remove an item from the queue and schedule future drain calls.

Source:

Group.js, line 279

Inherited From:

duil.Group#drain

Fires:

duil#event:render

Returns:

Return the group for chaining.

Type: duil.Group

set(props, forceopt) → {duil.Widget}

Update properties of the widget.

Source:

Widget.js, line 178

Inherited From:

duil.Widget#set

Update the widget's properties.

The keys props of the parameter can be dotted paths to lookup values in the widget.

The force parameter controls when .render() is called:

If true, always call .render() and fire change.
If false, never call .render() or fire change.
Otherwise (e.g. undefined), only call .render() (and fire change) when the properties are actually changed.

Example

var MyWidget = new duil.Widget({
  stats: { count: 42 }
});

// you can used dotted paths to refer to the field to change
MyWidget.set({'stats.count': MyWidget.stats.count + 1});
console.log(MyWidget.stats.count);
// => 43

Parameters:

Name	Type	Attributes	Description
`props`	Object		The new widget properties.
`force`	boolean	<optional>	Force calling `.render()` after property updates. Note that this also forces whether the `change` event is triggered regardless of whether any changes occur.

Fires:

duil#event:change

Returns:

Returns the widget itself for chaining.

Type: duil.Widget

on(type, handler) → {Widget}

Source:

Widget.js, line 230

Inherited From:

duil.Widget#on

The type parameter can be a comma-separated list of event names; the handler will be bound to all of the events given. There is also a special global event name *. Handlers registered to this event will receive every event that occurs on this object. In such cases where the same handler is receiving multiple event types, use the .type property of the event to determine which kind of event is being detected.

Basic Widget events are:

Example

var widget = new Widget();
widget.on('my-event-name', (e) => console.log(e.data));
widget.trigger('my-event-name', {value: 42});
// => {value: 42}

Parameters:

Name	Type	Description
`type`	string	The name of the event to listen to. Specify multiple events by separating them with a comma.
`handler`	function	The function to call when an event occurs.

Returns:

Returns the widget itself for chaining.

Type: Widget

off(typeopt, handleropt) → {Widget}

Remove an event handler from this widget.

Source:

Widget.js, line 254

Inherited From:

duil.Widget#off

Example

var widget = new Widget();
var handler = function (e) { console.log(e.data); };
widget.on('my-event,other-event', handler);
widget.off('my-event', handler); // still listening on other-event
widget.off('other-event'); // all handlers for other-event removed

Parameters:

Name	Type	Attributes	Default	Description
`type`	string	<optional>	`'*'`	The name of the event. Specify multiple events by separating them with a comma. By default, the handler is removed from all events.
`handler`	function	<optional>		The function that was used to respond to events. If omitted, all handlers for this event will be removed.

Returns:

Return the widget itself for chaining.

Type: Widget

trigger(type, dataopt) → {Widget}

Trigger an event on this widget.

Source:

Widget.js, line 281

Inherited From:

duil.Widget#trigger

Example

var widget = new Widget();
var handler = function (e) { console.log(e.type, e.data); };
widget.on('my-event,other-event', handler);
widget.trigger('my-event', 'only once');
// => "my-event" "only once"
widget.off('my-event,other-event', 'twice');
// => "my-event" "twice"
// => "my-event" "twice"

Parameters:

Name	Type	Attributes	Default	Description
`type`	string			The name of the event to trigger. Trigger multiple events by separating event names with a comma.
`data`	Object	<optional>	`{}`	Extra data to pass to the event.

Returns:

Returns the widget itself for chaining.

Type: Widget

invoke(parent, name, …args) → {*}

Invoke a method from another class in the context of this widget.

Source:

Widget.js, line 310

Inherited From:

duil.Widget#invoke

Example

var widget = new Widget({
  // @override
  init: function () {
    // do something unique to this widget here
    // now do whatever Widget.init does, in the context of this Widget
    return this.invoke(Widget, 'init');
  }
});

Parameters:

Name	Type	Attributes	Description
`parent`	Widget		The class with the method to invoke.
`name`	string		The name of the method to invoke.
`args`	*	<repeatable>	The arguments to pass to the method.

Returns:

Returns the result of invoking the method.

Type: *