dojox/mobile/FilteredListMixin (version 1.10)

Summary

Mixin for filtered lists.

This mixin adds filtering capabilities to all dojox/mobile list widgets: dojox/mobile/RoundRectList and any of its subclasses (RoundRectStoreList, RoundRectDataList, EdgeToEdgeList, EdgeToEdgeStoreList, EdgeToEdgeDataList). When mixing this class into a list widget, the list items are dynamically filtered depending on the filtering string that the user enters in a dojox/mobile/SearchBox.

This mixin supports the following use-cases: 1. For user's convenience, by simply mixing this class into a list widget the mixin creates a dojox/mobile/SearchBox and a dojox/mobile/ScrollableView. The list is placed inside the ScrollableView and the SearchBox, which allows filtering the list, is placed on top of the ScrollableView. 2. Alternatively, the user can create (and style) the instance of dojox/mobile/SearchBox, and specify its id using the property filterBoxRef of this mixin. This allows placing the SearchBox anywhere in the DOM, while the mixin takes care of the necessary glue to ensure the list is filtered according to the filter criteria entered in the SearchBox.

The filtering works for lists backed by a store (dojo/store or dojo/data), as well as for lists not backed by a store. When filtering a list backed by a store containing hierarchical data (data items that are children of a parent data item), the store must support recursive search queries such that the filtering can match child items.

For configuration purposes, the instance of dojox/mobile/SearchBox can be retrieved using the method getFilterBox(). If a dojox/mobile/ScrollableView is created by this mixin, it can be retrieved using getScrollableView().

See the dojox/mobile/FilteredListMixin reference documentation for more information.

Examples

Example 1

<!-- Markup use-case: -->
<!-- SearchBox and ScrollableView created by the mixin. -->
<!-- Filtered EdgeToEdgeStoreList created in markup. -->
<div data-dojo-type="dojox/mobile/View">
    <h1 data-dojo-type="dojox/mobile/Heading" data-dojo-props="fixed: 'top'">Some heading</h1>
    <ul data-dojo-type="dojox/mobile/EdgeToEdgeStoreList"
        data-dojo-mixins="dojox/mobile/FilteredListMixin"
        data-dojo-props="placeHolder: 'Search', store: myStore"></ul>
</div>

Example 2

<!-- Markup use-case: -->
<!-- SearchBox and ScrollableView created by the mixin. -->
<!-- Filtered RoundRectList created in markup. --> 
<div data-dojo-type="dojox/mobile/View">
    <h1 data-dojo-type="dojox/mobile/Heading" data-dojo-props="fixed: 'top'">Some heading</h1>
    <ul id="list" data-dojo-type="dojox/mobile/RoundRectList"
        data-dojo-mixins="dojox/mobile/FilteredListMixin"
        data-dojo-props="placeHolder: 'Search'">
        <li data-dojo-type="dojox/mobile/ListItem">Item 1</li>
        <li data-dojo-type="dojox/mobile/ListItem">Item 2</li>
        ...
    </ul>
</div>

Example 3

// Programmatic use-case:
// SearchBox and ScrollableView created by the mixin.
// Filtered EdgeToEdgeStoreList created programmatically.
require(["dojo/_base/declare", "dojo/ready", "dojox/mobile", "dojox/mobile/EdgeToEdgeStoreList", 
        "dojox/mobile/FilteredListMixin", ...], function(declare, ready, registry, ...){
    ready(function(){
        var listWidget =
            new declare([EdgeToEdgeStoreList, FilteredListMixin])(
                {placeHolder: 'Search', store: myStore, "filteredList"});
        listWidget.startup();
    });
});
...
<div id="view" data-dojo-type="dojox/mobile/View">
    <h1 data-dojo-type="dojox/mobile/Heading" data-dojo-props="fixed: 'top'">Some heading</h1>
    <div id="filteredList">
</div>

Example 4

<!-- Markup use-case: -->
<!-- SearchBox and ScrollableView provided by the user. -->
<!-- Filtered EdgeToEdgeDataList created in markup. --> 
<div data-dojo-type="dojox/mobile/View">
    <h1 data-dojo-type="dojox/mobile/Heading" data-dojo-props="fixed: 'top'">Some heading</h1>
    <input id="filterBox" data-dojo-type="dojox/mobile/SearchBox" type="search"
        class="mblFilteredEdgeToEdgeListSearchBox">     
    <div data-dojo-type="dojox/mobile/ScrollableView">
        <ul data-dojo-type="dojox/mobile/EdgeToEdgeDataList" 
            data-dojo-mixins="dojox/mobile/FilteredListMixin"
            data-dojo-props="filterBoxRef: 'filterBox', placeHolder: 'Search', store: myStore"></ul>
    </div>
</div>

Example 5

// Programmatic use-case:
// SearchBox and ScrollableView provided by the user.
// Filtered EdgeToEdgeStoreList created programmatically.
require(["dojo/_base/declare", "dojo/ready", "dijit/registry", "dojox/mobile",
        "dojox/mobile/EdgeToEdgeStoreList", "dojox/mobile/FilteredListMixin",
        "dojox/mobile/ScrollableView", ...], function(declare, ready, registry, ...){
    ready(function(){
        var view = registry.byId("scrollableView");
        var listWidget =
            new declare([EdgeToEdgeStoreList, FilteredListMixin])(
                {id:"list", filterBoxRef: 'filterBox', placeHolder: 'Search', store: myStore});
        listWidget.placeAt(view.containerNode);
        listWidget.startup();
    });
});
...
<div data-dojo-type="dojox/mobile/View">
    <h1 data-dojo-type="dojox/mobile/Heading" data-dojo-props="fixed: 'top'">Some heading</h1>
    <input id="filterBox" data-dojo-type="dojox/mobile/SearchBox" type="search"
        class="mblFilteredEdgeToEdgeListSearchBox">     
    <div id="scrollableView" data-dojo-type="dojox/mobile/ScrollableView">
</div>

Property Summary

  • _createdFilterBoxThe instance of dojox/mobile/SearchBox created by this mixin, or null if none has been created.
  • _createdScrollableViewThe instance of dojox/mobile/ScrollableView created by this mixin, if any.
  • _filterBoxThe instance of dojox/mobile/SearchBox used by this mixin.
  • filterBoxRefThe reference for the search box allowing to enter the filtering criteria.
  • filterBoxVisibleA flag which allows to show or hide the dojox/mobile/SearchBox associated with the list.
  • placeHolderDefines a hint to help users fill out the input field (as defined in HTML 5) of the dojox/mobile/SearchBox.

Method Summary

Event Summary

  • _onFilter(results,query,options) Internal handler for filtering events.
  • onFilter(results,query,options) User-defined function to handle filter actions.

Properties

_createdFilterBox
Defined by: dojox/mobile/FilteredListMixin

The instance of dojox/mobile/SearchBox created by this mixin, or null if none has been created. Stored for being able to destroy it together with the list widget.

_createdScrollableView
Defined by: dojox/mobile/FilteredListMixin

The instance of dojox/mobile/ScrollableView created by this mixin, if any. Stored for getScrollableView() and for being able to destroy it together with the list widget.

_filterBox
Defined by: dojox/mobile/FilteredListMixin

The instance of dojox/mobile/SearchBox used by this mixin. Stored for getFilterBox().

filterBoxRef
Defined by: dojox/mobile/FilteredListMixin

The reference for the search box allowing to enter the filtering criteria. Only used at construction time: - If unspecified, the mixin creates a dojox/mobile/SearchBox and a dojox/mobile/ScrollableView. The list is placed inside the ScrollableView and the SearchBox, wrapped in a DIV, is placed on top of the ScrollableView. - If the string is the id of a widget which is an instance of dojox/mobile/SearchBox or a subclass, the mixin uses this SearchBox for filtering the list. - If the id is specified but does not reference a dojox/mobile/SearchBox or subclass, an error is thrown.

filterBoxVisible
Defined by: dojox/mobile/FilteredListMixin

A flag which allows to show or hide the dojox/mobile/SearchBox associated with the list.

placeHolder
Defined by: dojox/mobile/FilteredListMixin

Defines a hint to help users fill out the input field (as defined in HTML 5) of the dojox/mobile/SearchBox. This should only contain plain text (no HTML markup). When the SearchBox is provided by the user (not created by this mixin), its placeHolder property takes precedence.

Methods

_createStore(initStoreFunction)
Defined by dojox/mobile/FilteredListMixin

Creates the store.

This method is used when the list is not backed by a store. In this case, a store is created and filled with items containing the text of the list items.

Parameter Type Description
initStoreFunction undefined
_initStore()
Defined by dojox/mobile/FilteredListMixin

Initializes the store.

_setFilterBoxVisibleAttr(visible)
Defined by dojox/mobile/FilteredListMixin
Parameter Type Description
visible Boolean
_setPlaceHolderAttr(placeHolder)
Defined by dojox/mobile/FilteredListMixin
Parameter Type Description
placeHolder String
destroy(preserveDom)
Defined by dojox/mobile/FilteredListMixin

Destroys the widget. If the list has created dojox/mobile/SearchBox or dojox/mobile/ScrollableView widgets, these widgets are also destroyed.

Parameter Type Description
preserveDom Boolean
Optional

If true, this method will leave the original DOM structure alone.
getFilterBox()
Defined by dojox/mobile/FilteredListMixin

Returns the dojox/mobile/SearchBox widget used for entering the filtering criteria. If an instance has been referenced at construction time using the property filterBoxRef, this instance is returned. Otherwise, returns the instance created by the mixin. This function allows the user to get the instance of SearchBox in order to customize its parameters.

Returns:undefined
getScrollableView()
Defined by dojox/mobile/FilteredListMixin

Returns the instance of dojox/mobile/ScrollableView created by this mixin, or null if none has been created. The mixin creates a ScrollableView if and only if the property filterBoxRef is unspecified. This function allows the user to get the instance of ScrollableView in order to customize its parameters.

Returns:undefined
startup()
Defined by dojox/mobile/FilteredListMixin

Events

_onFilter(results,query,options)
Defined by: dojox/mobile/FilteredListMixin

Internal handler for filtering events.

Parameter Type Description
results undefined
query undefined
options undefined

Examples

Example 1

<!-- Markup use-case: -->
<!-- SearchBox and ScrollableView created by the mixin. -->
<!-- Filtered EdgeToEdgeStoreList created in markup. -->
<div data-dojo-type="dojox/mobile/View">
    <h1 data-dojo-type="dojox/mobile/Heading" data-dojo-props="fixed: 'top'">Some heading</h1>
    <ul data-dojo-type="dojox/mobile/EdgeToEdgeStoreList"
        data-dojo-mixins="dojox/mobile/FilteredListMixin"
        data-dojo-props="placeHolder: 'Search', store: myStore"></ul>
</div>

Example 2

<!-- Markup use-case: -->
<!-- SearchBox and ScrollableView created by the mixin. -->
<!-- Filtered RoundRectList created in markup. --> 
<div data-dojo-type="dojox/mobile/View">
    <h1 data-dojo-type="dojox/mobile/Heading" data-dojo-props="fixed: 'top'">Some heading</h1>
    <ul id="list" data-dojo-type="dojox/mobile/RoundRectList"
        data-dojo-mixins="dojox/mobile/FilteredListMixin"
        data-dojo-props="placeHolder: 'Search'">
        <li data-dojo-type="dojox/mobile/ListItem">Item 1</li>
        <li data-dojo-type="dojox/mobile/ListItem">Item 2</li>
        ...
    </ul>
</div>

Example 3

// Programmatic use-case:
// SearchBox and ScrollableView created by the mixin.
// Filtered EdgeToEdgeStoreList created programmatically.
require(["dojo/_base/declare", "dojo/ready", "dojox/mobile", "dojox/mobile/EdgeToEdgeStoreList", 
        "dojox/mobile/FilteredListMixin", ...], function(declare, ready, registry, ...){
    ready(function(){
        var listWidget =
            new declare([EdgeToEdgeStoreList, FilteredListMixin])(
                {placeHolder: 'Search', store: myStore, "filteredList"});
        listWidget.startup();
    });
});
...
<div id="view" data-dojo-type="dojox/mobile/View">
    <h1 data-dojo-type="dojox/mobile/Heading" data-dojo-props="fixed: 'top'">Some heading</h1>
    <div id="filteredList">
</div>

Example 4

<!-- Markup use-case: -->
<!-- SearchBox and ScrollableView provided by the user. -->
<!-- Filtered EdgeToEdgeDataList created in markup. --> 
<div data-dojo-type="dojox/mobile/View">
    <h1 data-dojo-type="dojox/mobile/Heading" data-dojo-props="fixed: 'top'">Some heading</h1>
    <input id="filterBox" data-dojo-type="dojox/mobile/SearchBox" type="search"
        class="mblFilteredEdgeToEdgeListSearchBox">     
    <div data-dojo-type="dojox/mobile/ScrollableView">
        <ul data-dojo-type="dojox/mobile/EdgeToEdgeDataList" 
            data-dojo-mixins="dojox/mobile/FilteredListMixin"
            data-dojo-props="filterBoxRef: 'filterBox', placeHolder: 'Search', store: myStore"></ul>
    </div>
</div>

Example 5

// Programmatic use-case:
// SearchBox and ScrollableView provided by the user.
// Filtered EdgeToEdgeStoreList created programmatically.
require(["dojo/_base/declare", "dojo/ready", "dijit/registry", "dojox/mobile",
        "dojox/mobile/EdgeToEdgeStoreList", "dojox/mobile/FilteredListMixin",
        "dojox/mobile/ScrollableView", ...], function(declare, ready, registry, ...){
    ready(function(){
        var view = registry.byId("scrollableView");
        var listWidget =
            new declare([EdgeToEdgeStoreList, FilteredListMixin])(
                {id:"list", filterBoxRef: 'filterBox', placeHolder: 'Search', store: myStore});
        listWidget.placeAt(view.containerNode);
        listWidget.startup();
    });
});
...
<div data-dojo-type="dojox/mobile/View">
    <h1 data-dojo-type="dojox/mobile/Heading" data-dojo-props="fixed: 'top'">Some heading</h1>
    <input id="filterBox" data-dojo-type="dojox/mobile/SearchBox" type="search"
        class="mblFilteredEdgeToEdgeListSearchBox">     
    <div id="scrollableView" data-dojo-type="dojox/mobile/ScrollableView">
</div>
onFilter(results,query,options)
Defined by: dojox/mobile/FilteredListMixin

User-defined function to handle filter actions. If the function returns false, the filtering is cancelled.

Parameter Type Description
results undefined
query undefined
options undefined

Examples

Example 1

<!-- Markup use-case: -->
<!-- SearchBox and ScrollableView created by the mixin. -->
<!-- Filtered EdgeToEdgeStoreList created in markup. -->
<div data-dojo-type="dojox/mobile/View">
    <h1 data-dojo-type="dojox/mobile/Heading" data-dojo-props="fixed: 'top'">Some heading</h1>
    <ul data-dojo-type="dojox/mobile/EdgeToEdgeStoreList"
        data-dojo-mixins="dojox/mobile/FilteredListMixin"
        data-dojo-props="placeHolder: 'Search', store: myStore"></ul>
</div>

Example 2

<!-- Markup use-case: -->
<!-- SearchBox and ScrollableView created by the mixin. -->
<!-- Filtered RoundRectList created in markup. --> 
<div data-dojo-type="dojox/mobile/View">
    <h1 data-dojo-type="dojox/mobile/Heading" data-dojo-props="fixed: 'top'">Some heading</h1>
    <ul id="list" data-dojo-type="dojox/mobile/RoundRectList"
        data-dojo-mixins="dojox/mobile/FilteredListMixin"
        data-dojo-props="placeHolder: 'Search'">
        <li data-dojo-type="dojox/mobile/ListItem">Item 1</li>
        <li data-dojo-type="dojox/mobile/ListItem">Item 2</li>
        ...
    </ul>
</div>

Example 3

// Programmatic use-case:
// SearchBox and ScrollableView created by the mixin.
// Filtered EdgeToEdgeStoreList created programmatically.
require(["dojo/_base/declare", "dojo/ready", "dojox/mobile", "dojox/mobile/EdgeToEdgeStoreList", 
        "dojox/mobile/FilteredListMixin", ...], function(declare, ready, registry, ...){
    ready(function(){
        var listWidget =
            new declare([EdgeToEdgeStoreList, FilteredListMixin])(
                {placeHolder: 'Search', store: myStore, "filteredList"});
        listWidget.startup();
    });
});
...
<div id="view" data-dojo-type="dojox/mobile/View">
    <h1 data-dojo-type="dojox/mobile/Heading" data-dojo-props="fixed: 'top'">Some heading</h1>
    <div id="filteredList">
</div>

Example 4

<!-- Markup use-case: -->
<!-- SearchBox and ScrollableView provided by the user. -->
<!-- Filtered EdgeToEdgeDataList created in markup. --> 
<div data-dojo-type="dojox/mobile/View">
    <h1 data-dojo-type="dojox/mobile/Heading" data-dojo-props="fixed: 'top'">Some heading</h1>
    <input id="filterBox" data-dojo-type="dojox/mobile/SearchBox" type="search"
        class="mblFilteredEdgeToEdgeListSearchBox">     
    <div data-dojo-type="dojox/mobile/ScrollableView">
        <ul data-dojo-type="dojox/mobile/EdgeToEdgeDataList" 
            data-dojo-mixins="dojox/mobile/FilteredListMixin"
            data-dojo-props="filterBoxRef: 'filterBox', placeHolder: 'Search', store: myStore"></ul>
    </div>
</div>

Example 5

// Programmatic use-case:
// SearchBox and ScrollableView provided by the user.
// Filtered EdgeToEdgeStoreList created programmatically.
require(["dojo/_base/declare", "dojo/ready", "dijit/registry", "dojox/mobile",
        "dojox/mobile/EdgeToEdgeStoreList", "dojox/mobile/FilteredListMixin",
        "dojox/mobile/ScrollableView", ...], function(declare, ready, registry, ...){
    ready(function(){
        var view = registry.byId("scrollableView");
        var listWidget =
            new declare([EdgeToEdgeStoreList, FilteredListMixin])(
                {id:"list", filterBoxRef: 'filterBox', placeHolder: 'Search', store: myStore});
        listWidget.placeAt(view.containerNode);
        listWidget.startup();
    });
});
...
<div data-dojo-type="dojox/mobile/View">
    <h1 data-dojo-type="dojox/mobile/Heading" data-dojo-props="fixed: 'top'">Some heading</h1>
    <input id="filterBox" data-dojo-type="dojox/mobile/SearchBox" type="search"
        class="mblFilteredEdgeToEdgeListSearchBox">     
    <div id="scrollableView" data-dojo-type="dojox/mobile/ScrollableView">
</div>
Error in the documentation? Can’t find what you are looking for? Let us know!