JavaScript DataSource Filtering

Shield UI DataSource provides a robust, fully-featured mechanism for filtering data locally on the client-side. To setup filtering during initialization, set the filter option:

var ds = new shield.DataSource( {
	data: [/*...*/],
	filter: { path: "age", filter: "eq", value: 27 }
});
ds.read().then(function () {
	var dataView = ds.view;
	//dataView contains the filtered data
});

To modify filter options after the control has been initialized, set the filter property of the DataSource:

ds.filter = { path: "name", filter: "starts", value: "M" }
ds.read().then(function () {
	var dataView = ds.view;
	//dataView contains the newly filtered data
});

The above code snippets both set a single filter expression. Each filter expression is a JavaScript object containing three fields:
path - a string of the form "property.subproperty", specifying the path to the property to filter by.
filter - the name of a predefined filter function to use.
value - the literal value to filter by. In case a custom filter function is specified,this field is omitted.

Following is the set of predefined filter functions:

"eq" - equal (aliases: "equal", "equals", "==")
"neq" - not equal (aliases: "ne", "doesnotequal", "notequal", "notequals", "!=")
"con" - contains (aliases: "contains")
"notcon" - does not contain (aliases: "doesnotcontain", "notcontains")
"starts" - string starts with (aliases: "startswith")
"ends" - string ends with (aliases: "endswith")
"gt" - greater than (aliases: "greaterthan", ">")
"lt" - less than (aliases: "lessthan", " "gte" - greater than or equal (aliases: "ge", "greaterthanorequal", ">=")
"lte" - less than or equal (aliases: "le", "lessthanorequal", " "isnull" - is null (aliases: "null")
"notnull" - is not null (aliases: "isnotnull")

If a custom filtering mechanism is required, Shield UI DataSource supports custom filter functions specified in place of filter expression objects:

var ds = new shield.DataSource( {
	data: [/*...*/],
	filter: function (dataItem) {
		//custom filter function
		return dataItem.age > 27 && dataItem.lastName.chartAt(0) === "C"
	}
});
ds.read().then(function () {
	var dataView = ds.view;
	//dataView contains the custom filtered data
});

By default, the Shield UI DataSource filters data locally on the client-side. However, server-side filtering is also supported. If the DataSource is configured for remote web service binding and the DataSource.remote.operations array contains "filter", the component will not do any client-side filtering and instead pass the current filtering option as a parameter to the remote.read.data() method, which can be used for generating the server-side request, as shown below:

var ds = shield.DataSource.create({
    remote: {
        operations: ["filter"],
        read: {
            type: "GET",
            url: "/api/books",
            dataType: "json",
            data: function (params) {
                var queryParams = {};

                // filter
                if (params.filter && params.filter.length > 0) {
                    queryParams["filter"] = [];
                    $.each(params.filter, function(i, item) {
                        queryParams["filter"].push(item.path + "," + 
                            item.filter + "," + item.value);
                    });
                }

                return queryParams;
            }
        }
    },
    // initial filter setting
    filter: [{ path: "Type", filter: "eq", value: "eBook" }],
    schema: {
        fields: {
            Title: { path: "Title", type: String },
            Description: { path: "Description", type: String },
            Type: { path: "Type", type: String }
        }
    }
});

Shield UI DataSource supports a combination of multiple filter expressions (a compound filter expression) along with the logical "and" / "or" operations between them. To provide a compound filter expression, use a JavaScript object with a single field named "and" or "or" to specify the logical operator. The field must contain a JavaScript array with other filter expressions. These can be simple or compound, thus allowing for the logical nesting of multiple filter expressions into a single compound expression:

var ds = new shield.DataSource( {
	data: [/*...*/],
	// a compound filter expression containing a combination of a simple
	// and another compound expression, specifying the selection of
	// all data items with "category" field greater than or equal to 2
	// and all data items with either "age" less than 40 or
    // "retired" equal to false
	filter: {
		and: [
            { path: "category", filter: ">=", value: 2 },
            {
                or: [
                    { path: "age", filter: "<", value: 40 },
                    { path: "retired", filter: "eq", value: false }
                ]
            }
        ]
	}
});
ds.read().then(function () {
	var dataView = ds.view;
	//dataView contains the data with compound filter applied
});