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 });