Dojo FAQ: How can I add filtering controls to dgrid?

As dgrid’s adoption continues to rise, one of the most common questions developers ask is how to add filtering controls. Unlike some grid implementations, dgrid does not include an out-of-the-box component implementing a user interface for filtering. This leaves some developers unsure of where to begin.

dgrid does not include a filtering module because it’s impossible to build a one-size-fits-all solution. Requirements for a filtering UI can vary widely, and advanced implementations may rely on features specific to a certain dojo/store implementation.

Creating a simple filtering interface is as easy as creating an HTML form, and updating the query property of the grid based on its input.

HTML:

<form id="filterForm">
	Filter by Last Name: <input type="text" name="filter">
	<button type="submit">Filter</button>
</form>
<div id="grid"></div>

JavaScript:

require([
	"dojo/dom",
	"dojo/on",
	"dojo/store/Memory",
	"dgrid/OnDemandGrid"
], function (dom, on, Memory, OnDemandGrid) {
	var form = dom.byId("filterForm"),
		store = new Memory({ data: [
			{ id: 1, firstName: "Bryan", lastName: "Forbes" },
			{ id: 2, firstName: "Kenneth", lastName: "Franqueiro" },
			{ id: 3, firstName: "Colin", lastName: "Snover" },
			{ id: 4, firstName: "Kris", lastName: "Zyp" }
		] }),
		grid = new OnDemandGrid({
			columns: {
				"firstName": "First Name",
				"lastName": "Last Name"
			},
			sort: "lastName",
			store: store
		}, "grid");
	
	on(form, "submit", function (event) {
		var value = form.elements.filter.value;

		// Filter lastName, matching against the input text
		grid.set("query", { lastName: value });

		// Since we're using a form, prevent normal submission
		event.preventDefault();
	});
});

The focal point of this example is the call to grid.set("query", ...). Supported by both OnDemandList and the Pagination extension, this instructs the grid to send the indicated query to the store’s query method.

Different stores support different types of query arguments; the most common format is an object containing key/value pairs, where the key indicates the field to filter by, and the value indicates what to match against. In this example, the Memory store will perform exact matches only. That doesn’t seem terribly useful, but we have a few other options, because Memory uses SimpleQueryEngine. We can update line 27 above as follows:

grid.set("query", { lastName: new RegExp(value, "i") });

This will perform a case-insensitive search for items containing the entered text anywhere within lastName. At the same time, this illustrates just how quickly a particular filtering solution can become specific to the store implementation the grid is paired with.

The simple API that dgrid provides is just the starting point — where to go from there is limited only by your imagination.