Custom Sorting and Filtering

DataTable provides a built in mechanism for sorting columns, and the Paginator widget provides a means to filter the data by page number and results per page. When more complex sorting and filtering is required, a custom generateRequest may be needed, along with manually passing that generated request into DataSource's sendRequest method.

Sample Data:

CSS:

Markup:

<div id="genderRadioContainer">
	<p>Select a gender filter.</p>
	<input type="radio" name="gender" value="Both" checked>
	<input type="radio" name="gender" value="Female">
	<input type="radio" name="gender" value="Male">
</div>
<div id="stateSelectContainer">
	<p>Select states to compare.</p>
	<input type="button" class="menuButton" id="state1" value="State 1">
	<select id="state1Select">
		<option value="04000US01">Alabama</option>
		<option value="04000US02">Alaska</option>
		...
	</select>
	
	<input type="button" class="menuButton" id="state2" value="State 2">
	<select id="state2Select">
		<option value="04000US01">Alabama</option>
		<option value="04000US02">Alaska</option>
		...
	</select>
	
	<input type="button" class="menuButton" id="state3" value="State 3">
	<select id="state3Select">
		<option value="04000US01">Alabama</option>
		<option value="04000US02">Alaska</option>
		...
	</select>
</div>

Building the `generateRequest` Function

DataTable has a default generateRequest function. In order to create a custom query string, the generateRequest configuration setting must be overridden. Keep in mind that DataTable's column sort state needs to be taken into account, if using column sorting. This example does not use DataTable's built in column sorting. The comments in the code shows how to implement DataTable's column sorting.

requestBuilder: function (oState, oSelf) {
		/* We aren't initializing sort and dir variables. If you are
		using column sorting built into the DataTable, use this
		set of variable initializers.
		var sort, dir, startIndex, results; */
		
		var startIndex, results;
		
		oState = oState || {pagination: null, sortedBy: null};
        
		/* If using column sorting built into DataTable, these next two lines
		will properly set the current _sortedBy_ column and the _sortDirection_
		sort = (oState.sortedBy) ? oState.sortedBy.key : oSelf.getColumnSet().keys[0].getKey();
		dir = (oState.sortedBy && oState.sortedBy.dir === DataTable.CLASS_DESC) ? "desc" : "asc"; */
		
		startIndex = (oState.pagination) ? oState.pagination.recordOffset : 0;
		results = (oState.pagination) ? oState.pagination.rowsPerPage : null;
		
		return  "&results=" 	+ results +
				"&startIndex=" 	+ startIndex +
			    "&state[1]=" 	+ CS.settings.state1 +
			    "&state[2]=" 	+ CS.settings.state2 +
			    "&state[3]=" 	+ CS.settings.state3 +
			    "&gender=" 		+ CS.settings.gender;
	},

The custom generateRequest function, this.requestBuilder, is passed in to the generateRequest DataTable configuration setting.

Sending the Request

The external sorting and filtering controls will need to initiate a request for new data. DataSource's sendRequest method requires a request string (the custom query string) and a callback object. The custom generateRequest function will provide the request string.

The callback has four properties that are very important here.

success: There are four methods built into DataTable for handling the success and failure events. Please refer to Loading Data at Runtime for a list of the four methods and a description of each. It should suffice to say that, onDataReturnSetRows is what is required for this example, because we are using the Paginator widget.
failure: Please see the success property above... The same applies here.
argument: DataTable's state -- getState() -- is passed as the argument. If any changes to the Paginator UI need to be done, those changes should be reflected in the state object. If the page needs to be reset to 1, that needs to be manually set. It's going to be your job to keep the Paginator in synch with the DataTable when calling sendRequest manually.
scope: Pass in an instance of the DataTable.

fireDT: function (resetRecordOffset) {
        var oState = CS.myDataTable.getState(),
        	request,
        	oCallback;
    	
		/* We don't always want to reset the recordOffset.
		If we want the Paginator to be set to the first page,
		pass in a value of true to this method. Otherwise, pass in
		false or anything falsy and the paginator will remain at the
		page it was set at before.*/
        if (resetRecordOffset) {
        	oState.pagination.recordOffset = 0;
        }
		
		/* If the column sort direction needs to be updated, that may be done here.
		It is beyond the scope of this example, but the DataTable::sortColumn() method
		has code that can be used with some modification. */
        
		/*
		This example uses onDataReturnSetRows because that method
		will clear out the old data in the DataTable, making way for
		the new data.*/
		oCallback = {
		    success : CS.myDataTable.onDataReturnSetRows,
		    failure : CS.myDataTable.onDataReturnSetRows,
            argument : oState,
		    scope : CS.myDataTable
		};
        
		// Generate a query string
        request = CS.myDataTable.get("generateRequest")(oState, CS.myDataTable);
		
		// Fire off a request for new data.
		CS.myDataSource.sendRequest(request, oCallback);
	}

Handling the Response

Overriding DataTable's handleDataReturnPayload method allows the Paginator's totalRecords to be updated properly. That will enable the paginator to calculate how many pages of data there are. The bulk of the work is done for us automatically through the oCallback::success or oCallback::failure handlers set in the sendRequest method call.

Custom Sorting and Filtering

Building the generateRequest Function

Sending the Request

Handling the Response

Building the `generateRequest` Function