# Mojo.Widget.FilterList

## Namespace Detail

#### Overview

When your list is best navigated with a search field, particularly one where you would instantly filter the list as each character is typed into the field, you would want to use the FilterList widget. It is intended to display a variable length list of objects, which can be filtered through a call back function.

The widget has a text field displayed above a list, where the list is the result of applying the contents of the text field against some off-screen data source. The text field is hidden when empty, its initial state, but it is given focus in the scene so that any typing is captured in the field. As soon as the first character is entered, the framework displays the field and calls the specified filterFunction.

### Declaration

>     <div x-mojo-element="FilterList" id="listId" class="listClass" name="listName"></div>

Properties | Required | Value | Description
--- | --- | --- | ---
x-mojo-element | Required | FilterList | Declares the widget as type 'FilterList'.
id | Required | Any String | Identifies the widget element for use when instantiating or rendering.

### Events

>     Mojo.Event.listen(this.controller.get("filterlistId"), Mojo.Event.listTap, this.handleUpdate);

Event Type | Value | Event Handling
--- | --- | ---
Mojo.Event.listChange | {model:this.controller.model, item:dataObj, index: index + this.renderOffset, originalEvent:event} |
Mojo.Event.listTap | event.value or model.value |
Mojo.Event.listAdd |  |
Mojo.Event.listDelete | event.item event.index |
Mojo.Event.listReorder | event.item event.toIndex event.fromIndex |
Mojo.Event.filter | event.filterString |
Mojo.Event.filterImmediate | event.filterString |

### Instantiation

>     this.controller.setupWidget("filterlistId",
>       this.attributes = {
>           itemTemplate: "filterlistscene/static-list-entry",
>           listTemplate: "filterlistscene/static-list-container",
>           addItemLabel: $L("Add ..."),
>           swipeToDelete: true,
>           reorderable: true,
>           filterFunction: this.filterFunction.bind(this),
>           delay: 350,
>           emptyTemplate:"filterlist/emptylist"
>       },
>       this.model = {
>           disabled: false
>       }
>     );

### Attribute Properties

Attribute Property | Type | Required | Default | Description
--- | --- | --- | --- | ---
filterFunction | Function | Optional | None | Called to load items when the list is scrolled or filter changes. Function definition: filterFunction (filterString, listWidget, offset, count)
delay | Integer | Optional | 300 | Delay after entry before filter function is called (in ms)

The FilterList widget also includes all attributes available in the List widget.

### Model Properties

Model Property | Type | Required | Default | Description
--- | --- | --- | --- | ---
disabled | Boolean | Optional | False | If true, filter field is disabled.

### Methods

To invoke a method on a widget, use the scene controller's `get` method for the desired widget, and append `mojo` followed by the method.

Example:

>     this.controller.get('myWidget').mojo.getValue()

Method | Arguments | Description
--- | --- | ---
getList | none | Gets the List widget associated with this FilterList.
close | none | Closes the FilterField associated with this FilterList.
open | none | Opens the FilterField associated with this FilterList.
setCount | count (Integer) | Sets the count in the bubble in the FilterField associated with this FilterList.

The FilterList also includes all methods available in the List and FilterField widgets.