Blog Archive

Home
Open Source

For those of you who may not know, DataTables.Net is a fantastic jQuery plug-in that creates a data grid presentation and offers support for filtering and server-side paging solutions. Yep, define an endpoint web service, pump down your data and you are good to go. But the cool kids these days are into the No-SQL thing, and one of the great entries into the document based database arena is RavenDB. With Raven, you define your domain objects and just store them in the database, as Raven will do it’s magic and persist your objects as documents. Have a List<Customer> to store, give it to Raven and it will create one document of the customers and store it in JSON format.

This post will show you how to combine the front end goodness of DataTables with the back end magic of RavenDB. The goal is to provide:

  • The ability to define a single class for that indexes data.
  • Control how what data is selected by define the columns, sort order and paging size in Javascript. In other words, DataTables will tell the server what it wants to pull back
  • Provide support for filtering properties with a single search field, ala Google style.
  • Above all, save you time, make you a hero in front of your fans. :)

For the Impatient, Here’s the End Product

There’s a lot ground that we’ll cover but for those who want to see the light at the end of the tunnel here what the end solution will look like. You may want to download the solution first so you can follow along in the code. First, your web service or controller will have the following:


[HttpPost]
public JsonResult GetTenants(string jsonAOData)
{
   var tenantPager = new DataTablesPager<Tenant, Tenant_Search>(DocumentStore);
   var results = tenantPager.PrepAOData(jsonAOData)
                 .FilterFormattedList();

   return Json(results);
}

// The core method that is used to get the data is in DataTablesPager.cs
public List Filter(int pageSize, int pageIndex, string[] terms)
{
   var targetList = new List();
   RavenQueryStatistics stats;

   using(var session = docStore.OpenSession())
   {
      if (terms[0].Length > 0)
      {
         targetList = session.Query<DataTablesReduceResult, TIndexCreator>()
                               .Customize(x => x.WaitForNonStaleResults())
                               .SearchMultiple(x => x.QueryFields, string.Join(" ", terms), 
                                                options: SearchOptions.And)
                               .Statistics(out stats)
                               .Skip(pageIndex)
                               .Take(pageSize)
                               .As()
                               .ToList();

         this.totalDisplayResults = stats.TotalResults;

         session.Query<DataTablesReduceResult, TIndexCreator>()
                 .Statistics(out stats)
                 .As()
                 .ToList();
         this.totalResults = stats.TotalResults;
}
// Code reduced for reading purposes.

Take note of the Generics on the constructor – Tenant is your domain object, Tenant_Search is the class that Raven will use to create the index for retrieving the data, as well as defining what properties you can filter on the object. We’ll cover indexing shortly along with some RavenDB background.

Your Javascript will be the following:



var otable;

$(document).ready(function(){
   otable = $("#tenantTable").dataTable({
               "bProcessing": true,
               "bSort": true,
               "sPaginationType": "full_numbers",
               "aoColumnDefs": [
               { "sName": "Name", "aTargets": [0], "bSortable": true, "bSearchable": true },
               { "sName": "Agent", "aTargets": [1], "bSortable": true, "bSearchable": true },
               { "sName": "Center", "aTargets": [2], "bSortable": true, "bSearchable": true },
               { "sName": "StartDate", "aTargets": [3], "bSortable": true, "bSearchable": true },
               { "sName": "EndDate", "aTargets": [4], "bSortable": true, "bSearchable": true },
               { "sName": "DealAmount", "aTargets": [4], "bSortable": true, "bSearchable": true }
               ],
               "oLanguage": {
               "sSearch": "Search all columns:"
            },
               "aaSorting": [[1, "asc"]],
               "iDisplayLength": 7,
               "bServerSide": true,
               "sAjaxSource": "GetTenants",
               "fnServerData": function (sSource, aoData, fnCallback) {

                      var jsonAOData = JSON.stringify(aoData);

                     $.ajax({
                       //dataType: 'json',
                       contentType: "application/json; charset=utf-8",
                       type: "POST",
                       url: sSource,
                       data: "{jsonAOData : '" + jsonAOData + "'}",
                       success: function (msg) {
                         fnCallback(msg);
                       },
                       error: function (XMLHttpRequest, textStatus, errorThrown) {
                         alert(XMLHttpRequest.status);
                         alert(XMLHttpRequest.responseText);

                       }
                     });
         }
   });

   otable.fnSetFilteringDelay(1000);
});

It’s actually longer than the .Net stuff!!! We’ll cover what this means as well.

Getting Data and Providing Search with RavenDB

This post assumes that you have installed RavenDB, can connect to it, know how to store your objects, and that you can perform queries with LINQ. There are some good tutorials such as Rob Ashton’s video introduction to Raven, as well as a brief overview by Sensei (me). We’re going to focus on Raven’s inherent full-text search capability and rely on Raven’s built in paging mechanism to help us achieve our goals. While there is great capability that Raven provides, it is not SQL, and much of what you know about LINQ and LINQ to SQL will help you as well as paint you into a corner at the same. We’ll cover those aspects too.

First off, RavenDB is built on top of the search engine Lucene.Net. It is a schema-less database so up front we will need to identify what how we want to fetch data, as they indexes provide super fast data retrieval. Raven Indexes reduce the need to devote huge cpu cycles to processing a query, as the index is built from the documents and processed as a background operation. This operation is asynchronous and is performed by Lucene. Without this approach, any query force a complete scan of all documents. A miserably slow scan. With indexes define up front, Raven will work quitely to keep the indexes up to date when new documents are created. So why is this important? Well, what you think are doing in LINQ:


var search = "Bonus";
var steps = session.Query()
                    .Customize(x => x.WaitForNonStaleResults())
                    .Where(x => x.State.StartsWith(search) || x.WorkflowName.StartsWith(search))
                    .ToList();

 

is really translated to Lucene syntax. So what we get in the end is State:Bonus OR WorkflowName:Bonus. While it is simple to write a query that includes all the properties of an object, if you had an object with 15 properties would you really want to create a monster statement with a ton of ||’s? Hell no! If you look in the TestSuite project of the source code there is a few example of using pure LINQ queries. Check out the method “CanFilterAccrossAllStringProperties” and you will see where things were headed.

We want to be like Fonzie, and what was Fonzie? Correctomundo – he’s cool. A good solution would be to know what properties a domain object had, and perform a filter against those properties. In other words, it would really helpful if we could write some code that would look like this:


var propertyFilterSteps = session.Query()
                                 .Customize(x => x.WaitForNonStaleResults())
                                 .Where(AllStringPropertiesFilter(search,
                                      "Answer,AnsweredBy,
                                      Id,Participants,WorkflowName,WorkflowType,"))
                                 .ToList();

Here we are using a Expression<Func<T>> to pass in a delimited list of property names and with a little LINQ query against the class Step, we can generate a Lambda to process of filter. This is in the test method “CanFilterAccrossAllStringProperties”. It worked great until we needed to include DateTime properties. The code is included in the project, so you look at it there.

So how do we achieve the goal of have a single text box driven search that will query across all type of properties, and when you type “Spock 2010″ will query the properties that you specify for both values of “Spock” and “2010″? Let’s go back to Raven as you can specify an index query by mapping what properties you want to be included in the index and how you want Raven / Lucene to parse the text for matching values in that index. Raven provides a class called “AbstractIndexCreationTask” where you define a Map / Reduce function to create your index. In other words you are picking which properties are included in the index. You can define the output of the Map to anything that you wish. This is held in a class that we’ll name ReduceResult and we will query against the properties of that class. We want to tell Raven to take the significant properties and index them in a format that we can match our terms against. So we will create the following index that will allows us to filter for any term. This is found in Step_Search.cs in the Index folder


public class Step_Search : AbstractIndexCreationTask<Step, Step_Search.ReduceResult>
{
	public class ReduceResult
	{
		public string[] QueryFields { get; set; }

	// ... code eliminated for reading purpose
	}

	public Step_Search()
	{
		Map = steps =>
		from step in steps
		select new
		{
			QueryFields = new [] { step.State, step.Answer, step.AnsweredBy, step.WorkflowName,
			step.Created.ToShortDateString(), step.Created.Year.ToString(),
			step.Created.Month.ToString() + "/" + step.Created.Year.ToString()},
			DateCreated = step.Created,
			WorkflowName = step.WorkflowName,
			State = step.State
		};

	Indexes.Add(x => x.QueryFields, FieldIndexing.Analyzed);

// ... more code eliminated for reading purposes

So what we have done is create an index that has an array of strings. This array holds the text of our properties that we will match against. Raven has a method called Search that will perform a “StartsWith” style match against each object in the array. The call is .Search(x => x.QueryFields, “string to be searched”). If you take a look at the index we have done some additional things with dates: for one, we create a string representation in ShortDate format. So when the user knows the exact date they can enter it and the Pager will match it. But we want to make things as easy possible, so we have created string representations in mm/yyyy format so it’s easy for the users to filter if they only know the month and year of the item they are looking for. “I think it was April last year …”. This is a big for those users who don’t recall exact details, as it allows them to quickly discover what they are looking for.

One last thing before we move on to making this work with DataTables. Raven provides the search method that works with the IRavenQueryable collection. Take a look at the DataTablesPager.Filter method and you will see a SearchMultiple method. This is put in place to perform a search for multiple terms. In other words it will search for “Spock” and then chain a search for “2010″ against the IRavenQueryable. Phillip Haydon came up with this approach that works with partial matches, as it will give Lucene the right syntax. Otherwise you end up with weird results because you feed Lucene “spoc 201″ and because of the tokens Lucene creates with the text analyzer it will not pick up what you need. Phillip’s brilliant approach bridges this gap by using an extension method to perform the chaining of search terms. This is found in the class RavenExtensionMethods.cs, and it basically tokenizes the search string, creates an array and an individual call to the Search() method for member of the array. It allows us to perform advanced filtering such as partial matches like “spoc 201″. Try this out in the Tenant.aspx page of the WebDemo solution are you’ll see how it works.

Outta Breath Yet? Let’s Talk DataTables.Net!!!

Breathing hard yet? Good! There’s more to do – how does this work with DataTables.Net? DataTables uses the following parameters when processing server-side data:

Sent to the server:

Type Name Info
int iDisplayStart Display start point
int iDisplayLength Number of records to display
int iColumns Number of columns being displayed (useful for getting individual column search info)
string sSearch Global search field
boolean bEscapeRegex Global search is regex or not
boolean bSortable_(int) Indicator for if a column is flagged as sortable or not on the client-side
boolean bSearchable_(int) Indicator for if a column is flagged as searchable or not on the client-side
string sSearch_(int) Individual column filter
boolean bEscapeRegex_(int) Individual column filter is regex or not
int iSortingCols Number of columns to sort on
int iSortCol_(int) Column being sorted on (you will need to decode this number for your database)
string sSortDir_(int) Direction to be sorted – “desc” or “asc”. Note that the prefix for this variable is wrong in 1.5.x where iSortDir_(int) was used)
string sEcho Information for DataTables to use for rendering

Reply from the server

In reply to each request for information that DataTables makes to the server, it expects to get a well formed JSON object with the following parameters.

Type Name Info
int iTotalRecords Total records, before filtering (i.e. the total number of records in the database)
int iTotalDisplayRecords Total records, after filtering (i.e. the total number of records after filtering has been applied – not just the number of records being returned in this result set)
string sEcho An unaltered copy of sEcho sent from the client side. This parameter will change with each draw (it is basically a draw count) – so it is important that this is implemented. Note that it strongly recommended for security reasons that you ‘cast’ this parameter to an integer in order to prevent Cross Site Scripting (XSS) attacks.
string sColumns Optional – this is a string of column names, comma separated (used in combination with sName) which will allow DataTables to reorder data on the client-side if required for display
array array mixed aaData The data in a 2D array

DataTables will POST an AOData object. The class DataTablesPager.cs will handle parsing this object with the method PrepAOData. It’s responsible for determining what properties we are querying, how the data will be sorted, paging size, as well as including any terms for filtering. Because we have used generics, PrepAOData doesn’t care what object in your domain you are using as it is designed to read the properties and match those properties against the list of data items that DataTables has sent up to our application on the server. Again, our goal is to let DataTables dictate what to look for, and as long as we did our work when we created the index we should have great flexibility.

Let’s look at the Javascript again:

"aoColumnDefs": [
{ "sName": "Name", "aTargets": [0], "bSortable": true, "bSearchable": true },
{ "sName": "Agent", "aTargets": [1], "bSortable": true, "bSearchable": true },
{ "sName": "Center", "aTargets": [2], "bSortable": true, "bSearchable": true },
{ "sName": "StartDate", "aTargets": [3], "bSortable": true, "bSearchable": true },
{ "sName": "EndDate", "aTargets": [4], "bSortable": true, "bSearchable": true },
{ "sName": "DealAmount", "aTargets": [4], "bSortable": true, "bSearchable": true }
],

In the server side application we have Tenant_Search.cs that has created an index with the properties Name, Agent, Center, StartDate, EndDate and DealAmount. The Javascript above is DataTables way of saying “Hey, server, give me information back in the form of an array of value pairs and by they way, here are the data columns to use when you get me my stuff.” On the server side, we don’t care what the order of columns in the grid will be as the server assumes that DataTables will take care of that. And indeed, DataTables is supplying the request in the sName value pair. The server fetches it, spits it back to the browser and DataTables munches it. You can change the Javascript and leave your server application alone as long as you stick to using the fields you included in your index. Just like Fonzie, be cool.

But even cooler is the fact that Raven will handle paging for us: it has a built in limit of return up to 128 documents at a slice. Given that it’s retrieval speed is very fast this will work very well for us. If you look at the Raven console for each page that you retrieve you will see a very low time for the fetches. Remember, there is very little processing for the query as it is the index that has already performed the heavy lifting. For an example of this the page Tenants.aspx in WebDemo solution will page and filter 13,000 + documents. It is lightning fast.

Has Your Head Exploded Yet?

This is a lot to digest. Source code is here, along with the means to create 13,000 documents that you can use for testing. Please note that you will be required to pull down the Raven assemblies/packages via NuGet. Otherwise the download would be about 36 MB. Work for responding to sorting request has been started and hopefully you’ll want to see how that’s is solved in future post. But what we have accomplished is a very robust and easy way to display data from our document database, with low effort on the back end application.

Play with the code. The only way we make this better is to critique constructively, adapt to better ideas and grow! Some of the failed experiments have been included in the test so you can see how things have progressed. They marked as failures so you can focus on testing the DataTablesPager class. These failures are interesting though, and can provide insight to how the solution was arrived at. Also, the first time you fire up the web site that Global.ascx page will look for the test records and create them. This takes some time so if you want the wait those sections are marked for you so you comment them out and do what you need to. Enjoy.

Some gifts just keep on giving, and many times things can just take on a momentum that grow beyond your expectation. Bob Sherwood wrote to Sensei and pointed out that DataTables.net supports multiple column sorting. All you do is hold down the shift key and click on any second or third column and DataTables will add that column to sort criteria. “Well, how come it doesn’t work with the server side solution?” Talk about the sound of one hand clapping. How about that for a flub! Sensei didn’t think of that! Then panic set in – would this introduce new complexity to the DataTablePager solution, making it too difficult to maintain a clean implementation? After some long thought it seemed that a solution could be neatly added. Before reading, you should download the latest code to follow along.

How DataTables.Net Communicates Which Columns Are Involved in a Sort

If you recall, DataTables.Net uses a structure called aoData to communicate to the server what columns are needed, the page size, and whether a column is a data element or a client side custom column. We covered that in the last DataTablePager post. aoData also has a convention for sorting:

bSortColumn_X=ColumnPosition

In our example we are working with the following columns:

,Name,Agent,Center,,CenterId,DealAmount

where column 0 is a custom client side column, column 1 is Name (a mere data column), column 2 is Center (another data column), column 3 is a custom client side column, and the remaining columns are just data columns.

If we are sorting just by Name, then aoData will contain the following:

bSortColumn_0=1

When we wish to sort by Center, then by Name we get the following in aoData”

bSortColumn_0=2

bSortColumn_1=1

In other words, the first column we want to sort by is in position 2 (Center) and the second column(Name) is in position 1. We’ll want to record this some where so that we can pass this to our order routine. aoData passes all column information to us on the server, but we’ll have to parse through the columns and check to see if one or many of the columns is actually involved in a sort request and as we do we’ll need to preserve the order of that column of data in the sort.

SearchAndSortable Class to the Rescue

You’ll recall that we have a class called SearchAndSortable that defines how the column is used by the client. Since we iterate over all the columns in aoData it makes sense that we should take this opportunity to see if any column is involved in a sort and store that information in SearchAndSortable as well. The new code for the class looks like this:


public class SearchAndSortable
{
	public string Name { get; set; }
	public int ColumnIndex { get; set; }
	public bool IsSearchable { get; set; }
	public bool IsSortable { get; set; }
	public PropertyInfo Property{ get; set; }
	public int SortOrder { get; set; }
	public bool IsCurrentlySorted { get; set; }
	public string SortDirection { get; set; }

	public SearchAndSortable(string name, int columnIndex, bool isSearchable,
								bool isSortable)
	{
		this.Name = name;
		this.ColumnIndex = columnIndex;
		this.IsSearchable = isSearchable;
		this.IsSortable = IsSortable;
	}

	public SearchAndSortable() : this(string.Empty, 0, true, true) { }
}


There are 3 new additions:

IsCurrentlySorted - is this column included in the sort request.

SortDirection - “asc” or “desc” for ascending and descending.

SortOrder - the order of the column in the sort request. Is it the first or second column in a multicolumn sort.

As we walk through the column definitions, we’ll look to see if each column is involved in a sort and record what direction – ascending or descending – is required. From our previous post you’ll remember that the method PrepAOData is where we parse our column definitions. Here is the new code:


// Sort columns
this.sortKeyPrefix = aoDataList.Where(x => x.Name.StartsWith(INDIVIDUAL_SORT_KEY_PREFIX))
								.Select(x => x.Value)
								.ToList();

// Column list
var cols = aoDataList.Where(x => x.Name == "sColumns"
							& string.IsNullOrEmpty(x.Value) == false)
						.SingleOrDefault();

if(cols == null)
{
	this.columns = new List();
}
else
{
	this.columns = cols.Value
	.Split(',')
	.ToList();
}

// What column is searchable and / or sortable
// What properties from T is identified by the columns
var properties = typeof(T).GetProperties();
int i = 0;

// Search and store all properties from T
this.columns.ForEach(col =>
{
	if (string.IsNullOrEmpty(col) == false)
	{
		var searchable = new SearchAndSortable(col, i, false, false);
		var searchItem = aoDataList.Where(x => x.Name == BSEARCHABLE + i.ToString())
									.ToList();
		searchable.IsSearchable = (searchItem[0].Value == "False") ? false : true;
		searchable.Property = properties.Where(x => x.Name == col)
										.SingleOrDefault();

		searchAndSortables.Add(searchable);
	}

	i++;
});

// Sort
searchAndSortables.ForEach(sortable => {
							var sort = aoDataList.Where(x => x.Name == BSORTABLE + sortable.ColumnIndex.ToString())
				.ToList();
sortable.IsSortable = (sort[0].Value == "False") ? false : true;
sortable.SortOrder = -1;

// Is this item amongst currently sorted columns?
int order = 0;
this.sortKeyPrefix.ForEach(keyPrefix => {
	if (sortable.ColumnIndex == Convert.ToInt32(keyPrefix))
	{
		sortable.IsCurrentlySorted = true;

		// Is this the primary sort column or secondary?
		sortable.SortOrder = order;

		// Ascending or Descending?
		var ascDesc = aoDataList.Where(x => x.Name == "sSortDir_" + order)
								.SingleOrDefault();
		if(ascDesc != null)
		{
			sortable.SortDirection = ascDesc.Value;
		}
	}

	order++;
	});
});

To sum up, we’ll traverse all of the columns listed in sColumns. For each column we’ll grab the PorpertyInfo from our underlying object of type T. This gives only those properties that will be displayed in the grid on the client. If the column is marked as searchable, we indicate that by setting the IsSearchable property on the SearchAndSortable class. This happens starting at line 28 through 43.

Next we need to determine what we can sort, and will traverse the new list of SearchAndSortables we created. DataTables will tell us what if the column can be sorted by with following convention:

bSortable_ColNumber = True

So if the column Center were to be “sortable” aoData would contain:

bSortable_1 = True

We record the sortable state as shown on line 49 in the code listing.

Now that we know whether we can sort on this column, we have to look through the sort request and see if the column is actually involved in a sort. We do that by looking at what DataTables.Net sent to us from the client. Again the convention is to send bSortColumn_0=1 to indicate that the first column for the sort in the second item listed in sColumns property. aoData will contain many bSortColum’s so we’ll walk through each one and record the order that column should take in the sort. That occurs at line 55 where we match the column index with the bSortColumn_x value.

We’ll also determine what the sort direction – ascending or descending – should be. At line 63 we get the direction of the sort and record this value in the SearchAndSortable.

When the method PrepAOData is completed, we have a complete map of all columns and what columns are being sorted, as well as their respective sort direction. All of this was sent to us from the client and we are storing this configuration for later use.

Performing the Sort

[gigya src="http://listen.grooveshark.com/songWidget.swf" width="204" height="40" flashvars="hostname=cowbell.grooveshark.com&widgetID=23379337&style=water&p=0" allowScriptAccess="always" wmode="window" ](Home stretch so play the song!!)

If you can picture what we have so far we just basically created a collection of column names, their respective PropertyInfo’s and have recorded which of these properties are involved in a sort. At this stage we should be able to query this collection and get back those properties and the order that the sort applies.

You may already be aware that you can have a compound sort statement in LINQ with the following statement:


var sortedCustomers = customer.OrderBy(x => x.LastName)
                              .ThenBy(x => x.FirstName);

The trick is to run through all the properties and create that compound statement. Remember when we recorded the position of the sort as an integer? This makes it easy for us to sort out the messy scenarios where the second column is the first column of a sort. SearchAndSortable.SortOrder takes care of this for us. Just get the data order by SortOrder in descending order and you’re good to go. So that code would look like the following:


var sorted = this.searchAndSortables.Where(x => x.IsCurrentlySorted == true)
.OrderBy(x => x.SortOrder)
.ToList();

sorted.ForEach(sort => {
    records = records.OrderBy(sort.Name, sort.SortDirection,
                         (sort.SortOrder == 0) ? true : false);
});

On line 6 in the code above we are calling our extension method OrderBy in Extensions.cs. We pass the property name, the sort direction, and whether this is the first column of the sort. This last piece is important as it will create either “OrderBy” or the “ThenBy” for us. When it’s the first column, you guessed it we get “OrderBy”. Sensei found this magic on a StackOverflow post by Marc Gravell and others.

Here is the entire method ApplySort from DataTablePager.cs, and note how we still check for the initial display of the data grid and default to the first column that is sortable.


private IQueryable ApplySort(IQueryable records)
{
	var sorted = this.searchAndSortables.Where(x => x.IsCurrentlySorted == true)
										.OrderBy(x => x.SortOrder)
										.ToList();

	// Are we at initialization of grid with no column selected?
	if (sorted.Count == 0)
	{
		string firstSortColumn = this.sortKeyPrefix.First();
		int firstColumn = int.Parse(firstSortColumn);

		string sortDirection = "asc";
		sortDirection = this.aoDataList.Where(x => x.Name == INDIVIDUAL_SORT_DIRECTION_KEY_PREFIX + "0")
										.Single()
										.Value
										.ToLower();

		if (string.IsNullOrEmpty(sortDirection))
		{
		sortDirection = "asc";
		}

		// Initial display will set order to first column - column 0
		// When column 0 is not sortable, find first column that is
		var sortable = this.searchAndSortables.Where(x => x.ColumnIndex == firstColumn)
											.SingleOrDefault();
		if (sortable == null)
		{
			sortable = this.searchAndSortables.First(x => x.IsSortable);
		}

		return records.OrderBy(sortable.Name, sortDirection, true);
	}
	else
	{
		// Traverse all columns selected for sort
		sorted.ForEach(sort => {
		records = records.OrderBy(sort.Name, sort.SortDirection,
		(sort.SortOrder == 0) ? true : false);
		});

		return records;
	}
}

It’s All in the Setup

Test it out. Hold down the shift key and select a second column and WHAMO – multiple column sorts! Hold down the shift key and click the same column twice and KAH-BLAMO multiple column sort with descending order on the second column!!!

The really cool thing is that our process on the server is being directed by DataTables.net on the client. And even awseomer is that you have zero configuration on the server. Most awesome-est is that this will work with all of your domain objects, because we have used generics we can apply this to any class in our domain. So what are you doing to do with all that time you just got back?

ImageOn the quest to provide a rich user interface experience on his current project, Sensei has been experimenting with KnockoutJS by Steve Sanderson.  If you haven’t reviewed it’s capabilities yet  it would be well worth your while.  Not only has Steve put together a great series of tutorials, but he has been dog fooding it with Knockout.  The entire documentation and tutorial set is completed used Knockout.  Another fine source is Knockmeout.net by Ryan Niemeyer.  Ryan is extremely active on StackOverflow answering questions regarding Knockout, and also has a fine blog that offers very important insight on developing with this framework.

KnockoutJS is a great way to re-organize your client side code.  The goal of  this post is not to teach you KnocoutJS; rather, Sensei wants to point out other benefits – and a few pitfalls – to adopting its use.  In years past, it’s been difficult to avoid writing spaghetti code in Javascript.  Knockout forces you to adopt a new pattern of thought for organizing your UI implementation.  The result is a more maintainable code base.  In the past you may have written code similar to what Sensei use to write.  Take for example assigning a click event to a button or href in order to remove a record from a table:

&lt;table&gt;
  &lt;thead&gt;&lt;/thead&gt;
  &lt;tbody&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;a onclick=&quot;deleteRecord(1); return false;&quot; href=&quot;#&quot;&gt;Customer One&lt;/a&gt;&lt;/td&gt;
      &lt;td&gt;1313 Galaxy Way&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;a onclick=&quot;deleteRecord(2); return false;&quot; href=&quot;#&quot;&gt;Customer Two&lt;/a&gt;&lt;/td&gt;
      &lt;td&gt;27 Mockingbird Lane&lt;/td&gt;
    &lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;

&lt;script type=&quot;text/javascript&quot;&gt;
function deleteRecord(id){
  //  Do some delete activities ...
}
&lt;/script&gt;

You might even went as far as to assign the onclick event like so:

$(document).ready(function(){
  $(&quot;tr a&quot;).on('click', function(){
    //  find the customer id and call the delete record
  });
});

The proposition offered by Knockout is much different.  Many others much more conversant in design patterns and development than Sensei can offer better technical reasons why you sound use Knockout.  Sensei likes the fact that it makes thinking about your code much simpler.  As in:

 
<td><a data-bind="click: deleteRecord($data)" href="#">Customer One</a></td>

Yep, you have code mixed in with your mark up, but so what.  You can hunt down what’s going on, switch to your external js file to review what deleteRecord is supposed to do.  It’s as simple as that.  Speaking of js files, Knockout forces you to have a more disciplined approach organizing your javascript.  Here is what the supporting javascript could look like:

var CustomerRecord = function(id, name){
  //  The items you want to appear in UI are wrapped with ko.observable
  this.id = ko.observable(id);
  this.name = ko.observable(name);
}

var ViewModel = function(){
var self = this;
  //  For our demo let's create two customer records.  Normally you'll get Json from the server
  self.customers = ko.observableArray([
    new CustomerRecord(1, &quot;Vandelay Industries&quot;),
    new CustomerRecord(2, &quot;Wiley Acme Associates&quot;)
  ]);

  self.deleteRecord = function(data){
    //  Simply remove the item that matches data from the array
    self.customers.remove(data);
  }
}

var vm = new ViewModel();
ko.applyBindings(vm);

That’s it.  Include this file with your markup and that’s all you have to do.  The html will change too.   Knockout will allow you to produce our table by employing the following syntax:

<tbody data-bind=”foreach: customers”>
<tr>
<td><a href=”#” data-bind=”click:  deleteRecord($data)”><span data-bind=”text: id”></span></a></td>
<td><span data-bind=’text: name”></span></td>
<tr>
</tbody>

These Aren’t the Voids You’re Looking For

So we’re all touchy feely because we have organization to our Javascript and that’s a good thing.  Here’s some distressing news – while Knockout is a great framework, getting the hang of it can be really hard.  Part of the reason is Javascript itself.  Because it’s a scripting language, you end up with strange scenarios where you have a property that appear to have the same name but different values.  You see, one of the first rules of using Knockout is that observables ARE METHODS.  You have to access them with (), as in customer.name(), and not customer.name.  In other words, in order for you to assign values to an observable you must:


customer.name(&quot;Vandelay Industries&quot;);

//  Don't do this - you create another property!!

customer.name = &quot;Vandelay Industries&quot;;

What? Actually, as you probably have surmised, you get .name() and .name, and this causes great confusion when you are debugging your application in Firebug.  Imagine you can see that customer.name has a value when you hit a breakpoint, but its not what you’re looking for.  Sensei developed a tactic to help verify that he’s not insane, and it works simply.  When in doubt, go the console in Firebug and access your observable via the ViewModel; so in our case you could issue:

vm.customer.name();

When name() doesn’t match your expectation you’ve most likely added a property with a typo.  Check with

vm.customer.name;

It sounds silly, but you can easily spend a half hour insisting that you’re doing the right thing, but you really confusing a property with a method.  Furthermore, observable arrays can also be a source of frustration:

// This is not the length of the observable array. It will always be zero!!!
vm.customers.length == 0;

// You get the length with this syntax
vm.customers().length;

Knock ‘em inta tamarra, Rocky

Had Sensei known the two tips before starting he would have save a lot of time.  There are many others, and they are best described by Ryan Niemeyer in his post 10 things to know about Knockout from day one.  Read this post slowly.  It will save you a lot of headache.  You may familiar with jQuery and Javascript, but Knockout introduces subtle differences that will catch you off guard.  That’s not a bad thing, it’s just different than what you may be used to.  Ryan also makes great use of JS Fiddle and answers most of his StackOverflow questions by using examples.  Those examples are in many cases easier to learn from than the tutorial since the scope is narrower than the instruction that Steve Sanderson gives.  It really allows you play along as you learn.

ImageOn the quest to provide a rich user interface experience on his current project, Sensei has been experimenting with KnockoutJS by Steve Sanderson.  If you haven’t reviewed it’s capabilities yet  it would be well worth your while.  Not only has Steve put together a great series of tutorials, but he has been dog fooding it with Knockout.  The entire documentation and tutorial set is completed used Knockout.  Another fine source is Knockmeout.net by Ryan Niemeyer.  Ryan is extremely active on StackOverflow answering questions regarding Knockout, and also has a fine blog that offers very important insight on developing with this framework.

KnockoutJS is a great way to re-organize your client side code.  The goal of  this post is not to teach you KnocoutJS; rather, Sensei wants to point out other benefits – and a few pitfalls – to adopting its use.  In years past, it’s been difficult to avoid writing spaghetti code in Javascript.  Knockout forces you to adopt a new pattern of thought for organizing your UI implementation.  The result is a more maintainable code base.  In the past you may have written code similar to what Sensei use to write.  Take for example assigning a click event to a button or href in order to remove a record from a table:

&lt;table&gt;
  &lt;thead&gt;&lt;/thead&gt;
  &lt;tbody&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;a onclick=&quot;deleteRecord(1); return false;&quot; href=&quot;#&quot;&gt;Customer One&lt;/a&gt;&lt;/td&gt;
      &lt;td&gt;1313 Galaxy Way&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;a onclick=&quot;deleteRecord(2); return false;&quot; href=&quot;#&quot;&gt;Customer Two&lt;/a&gt;&lt;/td&gt;
      &lt;td&gt;27 Mockingbird Lane&lt;/td&gt;
    &lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;

&lt;script type=&quot;text/javascript&quot;&gt;
function deleteRecord(id){
  //  Do some delete activities ...
}
&lt;/script&gt;

You might even went as far as to assign the onclick event like so:

$(document).ready(function(){
  $(&quot;tr a&quot;).on('click', function(){
    //  find the customer id and call the delete record
  });
});

The proposition offered by Knockout is much different.  Many others much more conversant in design patterns and development than Sensei can offer better technical reasons why you sound use Knockout.  Sensei likes the fact that it makes thinking about your code much simpler.  As in:

 
<td><a data-bind="click: deleteRecord($data)" href="#">Customer One</a></td>

Yep, you have code mixed in with your mark up, but so what.  You can hunt down what’s going on, switch to your external js file to review what deleteRecord is supposed to do.  It’s as simple as that.  Speaking of js files, Knockout forces you to have a more disciplined approach organizing your javascript.  Here is what the supporting javascript could look like:

var CustomerRecord = function(id, name){
  //  The items you want to appear in UI are wrapped with ko.observable
  this.id = ko.observable(id);
  this.name = ko.observable(name);
}

var ViewModel = function(){
var self = this;
  //  For our demo let's create two customer records.  Normally you'll get Json from the server
  self.customers = ko.observableArray([
    new CustomerRecord(1, &quot;Vandelay Industries&quot;),
    new CustomerRecord(2, &quot;Wiley Acme Associates&quot;)
  ]);

  self.deleteRecord = function(data){
    //  Simply remove the item that matches data from the array
    self.customers.remove(data);
  }
}

var vm = new ViewModel();
ko.applyBindings(vm);

That’s it.  Include this file with your markup and that’s all you have to do.  The html will change too.   Knockout will allow you to produce our table by employing the following syntax:

<tbody data-bind=”foreach: customers”>
<tr>
<td><a href=”#” data-bind=”click:  deleteRecord($data)”><span data-bind=”text: id”></span></a></td>
<td><span data-bind=’text: name”></span></td>
<tr>
</tbody>

These Aren’t the Voids You’re Looking For

So we’re all touchy feely because we have organization to our Javascript and that’s a good thing.  Here’s some distressing news – while Knockout is a great framework, getting the hang of it can be really hard.  Part of the reason is Javascript itself.  Because it’s a scripting language, you end up with strange scenarios where you have a property that appear to have the same name but different values.  You see, one of the first rules of using Knockout is that observables ARE METHODS.  You have to access them with (), as in customer.name(), and not customer.name.  In other words, in order for you to assign values to an observable you must:


customer.name(&quot;Vandelay Industries&quot;);

//  Don't do this - you create another property!!

customer.name = &quot;Vandelay Industries&quot;;

What? Actually, as you probably have surmised, you get .name() and .name, and this causes great confusion when you are debugging your application in Firebug.  Imagine you can see that customer.name has a value when you hit a breakpoint, but its not what you’re looking for.  Sensei developed a tactic to help verify that he’s not insane, and it works simply.  When in doubt, go the console in Firebug and access your observable via the ViewModel; so in our case you could issue:

vm.customer.name();

When name() doesn’t match your expectation you’ve most likely added a property with a typo.  Check with

vm.customer.name;

It sounds silly, but you can easily spend a half hour insisting that you’re doing the right thing, but you really confusing a property with a method.  Furthermore, observable arrays can also be a source of frustration:

// This is not the length of the observable array. It will always be zero!!!
vm.customers.length == 0;

// You get the length with this syntax
vm.customers().length;

Knock ‘em inta tamarra, Rocky

Had Sensei known the two tips before starting he would have save a lot of time.  There are many others, and they are best described by Ryan Niemeyer in his post 10 things to know about Knockout from day one.  Read this post slowly.  It will save you a lot of headache.  You may familiar with jQuery and Javascript, but Knockout introduces subtle differences that will catch you off guard.  That’s not a bad thing, it’s just different than what you may be used to.  Ryan also makes great use of JS Fiddle and answers most of his StackOverflow questions by using examples.  Those examples are in many cases easier to learn from than the tutorial since the scope is narrower than the instruction that Steve Sanderson gives.  It really allows you play along as you learn.

This post focuses on getting started with RavenDB, so we’ll set aside our focus on workflows for a bit.  It’s included in the ApprovaFlow series as it is an important part of the workflow framework we’re building.  To follow along you might want to get the source code.

RavenDB is a document database that provides a flexible means for storing object graphs.  As you’ll see a document database presents you with a different set of challenges than you are normally presented when using a traditional relational database.

The storage “unit” in RavenDB is a schema-less JSON document.  This takes the form of:  Because you are working with documents you now have the flexibility to define documents differently; that is, you can support variations to your data without have to re-craft your data model each time you want to add a new property to a class.  You can adopt a “star” pattern for SQL as depicted here, but querying can become difficult.  Raven excels in this situation and one such sweet spot is:

Dynamic Entities, such as user-customizable entities, entities with a large number of optional fields, etc. – Raven’s schema free nature means that you don’t have to fight a relational model to implement it.

Installing and Running RavenDB

The compiled binaries are easy to install.  Download the latest build and extract the files to a share.  Note that in order to run the console you are required to install Silverlight.  To start the server, navigate to the folder[] and double click “Start.cmd”.  You will see a screen similar to this one once the server is up and running:

The console will launch it self and will resemble this:

How To Start Developing

In Visual Studio, reference Raven with Raven.Client.Lightweight.  For CRUD operations and querying this will be all that you will need.

First you will need to connect to the document store.  It is recommended that you do this once per application.  That is accomplished with


var documentStore = new DocumentStore {Url = "http://localhost:8080"};
documentStore.Initialize();

Procedures are carried out using the Unit of Work pattern, and in general you will be using these type of blocks:


using(var session = documentStore.OpenSession())
{
   //... Do some work
}

RavenDB will work with Plain Old C# Objects and only requires an Id property of type string.  An identity key is generated for Id during this session.  If were were to create multiple steps we would have identities created in succession.  A full discussion of the alternatives to the Id property is here.

Creating a document from your POCOs’ object graphs is very straight forward:


public class Person
{
    public string FirstName { get; set; }
	public string LastName { get; set; }
	public string Id { get; set; }
	public int DepartmentId { get; set; }
    // ...
}

var person = new Person();

using(var session = documentStore.OpenSession())
{
   session.Store(person);
   session.SaveChanges();
}

Fetching a document can be accomplished in two manners:  by Id or with a LINQ query.  Here’s how to get a document by id:


string person = "Person/1";  //  Raven will have auto-generated a value for us.
using(var session = documentStore.OpenSession())
{
   var fetchedPerson = session.Load<Person>(personId);
   //Do some more work
}

You’ll note that there is no casting or conversion required as Raven will determine the object type and populate the properties for you.

There are naturally cases where you want to query for documents based on attributes other than the Id. Best practices guides that we should create static indexes on our documents as these will offer the best performance. RavenDB also has a dynamic index feature that learns from queries fired at the server and over time these dynamic indexes are memorialized.

For your first bout with RavenDB you can simply query the documents with LINQ.   The test code takes advantage of the dynamic feature.  Later you will want to create indexes based on how you most likely will retrieve the documents.  This is different that a traditional RDMS solution, where the data is optimized for querying.  A document database is NOT.

Continuing with our example of Person documents we would use:


int departmentId = 139;

using(var session = documentStore.OpenSession())
{
   var people = session.Query<Person>()
                          .Where(x => x.DepartmentId == departmentId)
                          .ToList();
}

In the source code for this post there are more examples of querying.

Debugging, Troubleshooting and Dealing with Frustration

Given that this is something new and an open source project you may find yourself searching for help and more guidelines.  One thing to avail yourself of while troubleshooting is the fact that RavenDB has REST interface and you can validate your assumptions – or worse, confirm your errors – by using curl from the command line.  For example, to create a document via http you issue:

curl -X POST http://localhost:8080/docs -d "{ FirstName: 'Bob', LastName: 'Smith', Address: '5 Elm St' }"

Each action that takes place on the RavenDB server is displayed in a log on the server console app.  Sensei had to resort to this technique when troubleshooting some issues when he first started.  This StackOverflow question details the travails.

Another area that threw Sensei for a loop at first was the nature of the RavenDB writing and maintaining indexes.  In short, indexing is a background process, and Raven is designed to be “eventually consistent”.  That means that there can be a latency between when a change is submitted, saved, and indexed in the repository so that it can be fetched via queries.  When running tests from NUnit this code did not operate as expected, yet the console reported that the document was created:


session.Store(teamMember);

int posttestCount = session.Query<TeamMember>()
                .Count();

According to the documentation you can overcome this inconsistency by declaring that you are willing to wait until RavenDB has completed its current write operation.   This code will get you the expected results:


int posttestCount = session.Query<TeamMember>()
              .Customize(x => x.WaitForNonStaleResults())
              .Count();

Depending on the number of tests you write you may wish to run RavenDB in Embedded mode for faster results.  This might prove useful for automated testing and builds.  The source code provided in this post does NOT use embedded mode; rather, you have need your server running as this gives you the opportunity to inspect documents and acclimate yourself to the database.

There is much more that you can do with RavenDB, such as creating indexes across documents, assign security to individual documents, and much more.  This primer should be enough to get you started.  Next post we’ll see how RavenDB will fit into the ApprovaFlow framework.  Grab the source, play around and get ready for the next exciting episode.

 

[gigya src="http://listen.grooveshark.com/songWidget.swf" width="204" height="40" flashvars="hostname=cowbell.grooveshark.com&widgetID=25064281&style=water&p=0" allowScriptAccess="always" wmode="window" ]

Like Tolkien, Sensei wants to create the landscapes, cultures and languages before he writes his next epic. You can be the judge whether the work is a series of sketches and notes like the Silmarillion or cohesive, compelling story that you want read again and again. As a bonus Sensei will deliver working software that hopefully will be of use to you.  (Photo credit - utnapistim).

The epic will be called ApprovaFlow. ApprovaFlow is a framework / process / methodology that allows you to create workflow applications that are easy to deploy and are configurable. With ApprovaFlow Sensei hopes to demonstrate how to readily encorporate the inevitable changes that your users will ask of you. Deliver changes effortlessly and without groans. Cast off the chains inconvenient builds and focus on creating solutions that stay out of the users way.

Ok. Managent wants bullet points so here are our goals for ApprovaFlow:

• Model a workflow in a clear format that is readable by both developer and business user. One set of verbiage for all parties.
•. Allow the state of a workflow to be peristed as an integer, string. Quicky fetch state of a workflow.
•. Create pre and post nprocessing methods that can enforce enforce rules or carry out actions when completing a workflow task.
•. Introduce new functionality while isolating the impact of the new changes. New components should not break old ones
•.Communicate to the client with a standard set of objects. In other words, your solution domain will not change how the user interface will gather data from the user.
•. Use one. aspx page to processes user input for any type of workflow.
•. Provide ability to roll your own customizations to the front end or backend of your application.

There it is. These goals will probably take us a good amount of time to review and implement. Is it worth it? Hell yeah. We’ll end up with one simple project instead of a bloated framework where it takes forever to find anything. A nice by product will be that you can spend more time thinking about how to solve your users problems rather than trying to figure out a monsterous framework that requires a huge investment of energy and time learning how to get simple things done.

Source code has been updated!! Read about the changes in Dynamically Select Columns with Server-Side Paging and Datatables.Net If you are new to DataTables.Net and Sensei’s paging solution and want to detailed study of how it works, work through this post first, then get the latest edition.  Note, code links in this post are to the first version.

A central theme for 2010 has been fluency, or the continual practice of certain methods to such a degree that your performance improves and you produce increasingly polished, effective solutions.  For software development this has meant tools to save time and increase quality.  It also means keeping an eye toward making the users of your solutions more efficient as well.  In the spirit of “fluent solutions”, Sensei will end the year with a post that examines how to create a data paging solution for the jQuery data grid plug-in DataTables.Net.

DataTables can turn a HTML table into a fully functional data grid like the one offered by Telerik.  This plug-in offers client side sorting, filtering/ search,  as well as support for server-side processing processing of data.  It is an extremely feature rich tool created by Allan Jardine, and is itself worthy of a series of posts.  For this post on data paging Sensei recommends that you read through these examples to get an idea of what the data paging service needs to achieve.

Let’s get started with the goals we need to achieve when providing server-side data paging support:

  • Send data to client in the multiples or “chunks” that the client requests, and respond when the size of the sets requested is changed by the user.
  • Re-order the data set if the user clicks on a column heading.  Honor the data set size when returning the data.
  • Filter across all columns of data based on user input.  Implement this as partial matches, and again, honor the data set size.

Remember this is about flexibility, so we have the additional goals of:

  • Create a solution that can be reused.
  • Provide a mechanism to accommodate any type of .Net class using generics.

Essentially we want to be able to write code like so:

var tenants = tenantRepository.GetAll();
var dataTablePager = new DataTablePager();
var returnDataSet = dataTablePager.Filter(requestParms, tenants);

Before we proceed, Sensei wants to acknowledge those really smart people whose ideas contributed to this solution:

Zack Owens – jQuery DataTables Plugin Meets C#

Jeff Morris - Using Datatables.net JQuery Plug-in with WCF Services

Dave Ward – ASMX ScriptService mistake – Invalid JSON primitive

You may want to download the source before reading the rest of this post.

Communicating with DataTables

DataTables uses the following parameters when processing server-side data:

Sent to the server:

Type Name Info
int iDisplayStart Display start point
int iDisplayLength Number of records to display
int iColumns Number of columns being displayed (useful for getting individual column search info)
string sSearch Global search field
boolean bEscapeRegex Global search is regex or not
boolean bSortable_(int) Indicator for if a column is flagged as sortable or not on the client-side
boolean bSearchable_(int) Indicator for if a column is flagged as searchable or not on the client-side
string sSearch_(int) Individual column filter
boolean bEscapeRegex_(int) Individual column filter is regex or not
int iSortingCols Number of columns to sort on
int iSortCol_(int) Column being sorted on (you will need to decode this number for your database)
string sSortDir_(int) Direction to be sorted – “desc” or “asc”. Note that the prefix for this variable is wrong in 1.5.x where iSortDir_(int) was used)
string sEcho Information for DataTables to use for rendering

Reply from the server

In reply to each request for information that DataTables makes to the server, it expects to get a well formed JSON object with the following parameters.

Type Name Info
int iTotalRecords Total records, before filtering (i.e. the total number of records in the database)
int iTotalDisplayRecords Total records, after filtering (i.e. the total number of records after filtering has been applied – not just the number of records being returned in this result set)
string sEcho An unaltered copy of sEcho sent from the client side. This parameter will change with each draw (it is basically a draw count) – so it is important that this is implemented. Note that it strongly recommended for security reasons that you ‘cast’ this parameter to an integer in order to prevent Cross Site Scripting (XSS) attacks.
string sColumns Optional – this is a string of column names, comma separated (used in combination with sName) which will allow DataTables to reorder data on the client-side if required for display
array array mixed aaData The data in a 2D array

The data sent back is in the following form depicted below. Note that aaData is merely an array of strings – there is no column information. This will present a challenge in that you will not be able to simply serialize a collection and pass back the results.

{
    &quot;sEcho&quot;: 3,
    &quot;iTotalRecords&quot;: 57,
    &quot;iTotalDisplayRecords&quot;: 57,
    &quot;aaData&quot;: [
        [
            &quot;Gecko&quot;,
            &quot;Firefox 1.0&quot;,
            &quot;Win 98+ / OSX.2+&quot;,
            &quot;1.7&quot;,
            &quot;A&quot;
        ],
        [
            &quot;Gecko&quot;,
            &quot;Firefox 1.5&quot;,
            &quot;Win 98+ / OSX.2+&quot;,
            &quot;1.8&quot;,
            &quot;A&quot;
        ],
        ...
    ]
}

As you may be aware, if you wish to use ASP.Net web services to serialize JSON you must POST to the service and instruct it to interpret your parameters as JSON. DataTables will POST variables as value pairs and this won’t work for us when POSTing to a web service. We’ll have to translate the variables to a usable format. Luckily DataTables allows us to intervene with the following code, where we create a JSON string by serializing a structure called aoData:

&quot;fnServerData&quot;: function ( sSource, aoData, fnCallback ) {

		        	var jsonAOData = JSON.stringify(aoData);

			        $.ajax( {
                                        contentType: &quot;application/json; charset=utf-8&quot;,
				        type: &quot;POST&quot;,
				        url: sSource,
				        data: &quot;{jsonAOData : '&quot; + jsonAOData + &quot;'}&quot;,
				        success: function(msg){
				            fnCallback(JSON.parse(msg.d));
				        },
				        error: function(XMLHttpRequest, textStatus, errorThrown) {
                            alert(XMLHttpRequest.status);
                            alert(XMLHttpRequest.responseText);

                        }
			        });

Our web service can now de-serialize aoData and parse the appropriate parameters. This gives us important items such as how many records to display, what columns to sort on, and what search terms should be applied in a filter.

DataTablePager Class

DataTablePager.cs is the work horse of our solution.  It will sort, filter and order our data, and as an extra, serialize the results in format required by aaData.  Here’s the constructor:

public DataTablePager(string jsonAOData, IQueryable queryable)
        {
            this.queryable = queryable;
            this.type = typeof(T);
            this.properties = this.type.GetProperties(BindingFlags.Public | BindingFlags.Instance);
            this.aoDataList = new List&gt;();
            this.sortKeyPrefix = new List();

            PrepAOData(jsonAOData);
        }

The parameter jsonAOData is the JSON string that contains the variables iDisplayStart, iDisplayLength, etc.  These will be parsed by the method PrepAOData.  The parameter queryable is the collection of records that will be filtered and parsed into JSON format required by DataTables.

The method Filter() coordinates all of the work.  It’s pretty simple what we want to do:  filter our data based on each column containing the search term, sort the result, then pull out the number of records we need to include in the page, and finally convert the collection into the format DataTables understands.

public FormattedList Filter()
        {
            var formattedList = new FormattedList();

            //  What are the columns in the data set
            formattedList.Import(this.properties.Select(x =&gt; x.Name + &quot;,&quot;)
                                                 .ToArray());

            //  Return same sEcho that was posted.  Prevents XSS attacks.
            formattedList.sEcho = this.echo;

            //  Return count of all records
            formattedList.iTotalRecords = this.queryable.Count();

            //  Filtered Data
            var records = this.queryable.Where(GenericSearchFilter());
            records = ApplySort(records);

            //  What is filtered data set count now.  This is NOT the
            //  count of what is returned to client
            formattedList.iTotalDisplayRecords = (records.FirstOrDefault() == null) ? 0 : records.Count();

            //  Take a page
            var pagedRecords = records.Skip(this.displayStart)
                     .Take(this.displayLength);

            //  Convert to List of List
            var aaData = new List&gt;();
            var thisRec = new List();

            pagedRecords.ToList()
                    .ForEach(rec =&gt; aaData.Add(rec.PropertiesToList()));

            formattedList.aaData = aaData;

            return formattedList;
        }

That said, there is some trickery that goes on in order to make this happen because we are creating a solution to is going to work with any IQueryable to we supply. This means that the filtering and the sorting will need to be dynamic.

To make the filtering dynamic we will build expression trees that will convert each property to a string, convert the string to lower case, then execute a Contains method against the value of that property.  The method GenericSearchFilter() called on line 16 accomplishes this with the following lines of code:

//  Except from GenericSearchFilter
MethodInfo convertToString = typeof(Convert).GetMethod(&quot;ToString&quot;, Type.EmptyTypes);

 var propertyQuery = (from property in this.properties
        let toStringMethod = Expression.Call(                                          Expression.Call(Expression.Property(paramExpression, property), convertToString, null),                                                            typeof(string).GetMethod(&quot;ToLower&quot;, new Type[0]))
         select Expression.Call(toStringMethod, typeof(string).GetMethod(&quot;Contains&quot;), searchExpression)).ToArray();

We get an array of Expressions that when executed will tell us if the value matches our search term. What we want is to include the item if ANY of the properties is a match, so this means we have to use and OR for all of the properties. That can be accomplished with:

for (int j = 0; j &lt; propertyQuery.Length; j++)
{
  //  Nothing to &quot;or&quot; to yet
  if (j == 0)
  {
    compoundOrExpression = propertyQuery[0];
  }

  compoundOrExpression = Expression.Or(compoundOrExpression,
                                              propertyQuery[j]);
}

So with what is listed above we would be able to match all properties with against a single search term. Pretty cool. But DataTables raises the bar even higher. If you were to go to the samples page and filter using multiple partial words you would find that you could perform some very effective searches with phrases like “new chic”. This would select all records that had properties containing “new” OR “chic”. Imagine the scenario where your user wants to finds all cities “New York” or “Chicago”. We’ve all been there where we have a grid and can only search for one term, or worse, where we have to add a row to a search filter grid and constantly push a “query” button to perform our searches. DataTables does all of the with one search box – just type and the filtering begins.

GenericSearchFilter() handles that scenario. First the search term is parsed into individual terms if there is a ” ”  supplied in the string. This means we will have to perform the propertyQuery for each term that we have. To return all of the records that correspond to each term we still need to perform the OR in groups, but then we need to AND these predicates together so we can get all of the groups per individual term. Here’s the source edited slightly for readability:

//  Split search expression to handle multiple words
var searchTerms = this.genericSearch.Split(' ');

for (int i = 0; i &lt; searchTerms.Length; i++) {    var searchExpression = Expression.Constant( searchTerms[i].ToLower());                   //  For each property, create a contains expression   //  column =&gt; column.ToLower().Contains(searchTerm)
  //  Edited for clarity - create the array propertyQuery logic is here ...
  var propertyQuery = ...

  //  Inner loop for grouping all OR's for this search term
  for (int j = 0; j &lt; propertyQuery.Length; j++)   {     //  Nothing to &quot;or&quot; to yet     if (j == 0)     {       compoundOrExpression = propertyQuery[0];     }     compoundOrExpression = Expression.Or(compoundOrExpression, propertyQuery[j]);   }   //  First time around there is no And, only first set of or's   if (i == 0)   {     compoundAndExpression = compoundOrExpression;   }   else   {     compoundAndExpression = Expression.And(compoundAndExpression, compoundOrExpression);   } } 

So GenericSearchFilter will build a humongous expression tree for all the properties in your class. To make this usable for the Where we convert it using Expression.Lambda and our Where clause just goes about its merry way. Because we have used generics, you can supply any class from your assemblies. One caveat, and Sensei is trying to find a resolution. If you have a string property to that is set to null, the expression tree fails. You’ll note that in the classes supplied in the sample, the properties that are of type string in the Tenant class are defaulted to empty in the constructor.  A small price to pay for some great functionality. To sort our data we use the method ApplySort():

 private IQueryable ApplySort(IQueryable records)         {             string firstSortColumn = this.sortKeyPrefix.First();             int firstColumn = int.Parse(firstSortColumn);             string sortDirection = &quot;asc&quot;;             sortDirection = this.aoDataList.Where(x =&gt; x.Name == INDIVIDUAL_SORT_DIRECTION_KEY_PREFIX +
                                                                      &quot;0&quot;)
                                                .Single()
                                                .Value
                                                .ToLower();

            if (string.IsNullOrEmpty(sortDirection))
            {
                sortDirection = &quot;asc&quot;;
            }

            return records.OrderBy(this.properties[firstColumn].Name, sortDirection, true);
        }

An extension method OrderBy will accept the name of column, the sort direction as parameters. The parameter initial will indicate if we are sorting mulitple times, so we can accomplish multi-property sort with syntax like

var sortedRecords = records.OrderBy(&quot;State&quot;, &quot;desc&quot;, true)
                                      .OrderBy(&quot;City&quot;, &quot;asc&quot;, false);

public static IOrderedQueryable OrderBy(this IQueryable source, string property, string sortDirection, bool initial)
        {
            string[] props = property.Split('.');
            Type type = typeof(T);
            ParameterExpression arg = Expression.Parameter(type, &quot;x&quot;);
            Expression expr = arg;
            foreach (string prop in props)
            {
                // use reflection (not ComponentModel) to mirror LINQ
                PropertyInfo pi = type.GetProperty(prop);
                expr = Expression.Property(expr, pi);
                type = pi.PropertyType;
            }
            Type delegateType = typeof(Func&lt;,&gt;).MakeGenericType(typeof(T), type);
            LambdaExpression lambda = Expression.Lambda(delegateType, expr, arg);

            string methodName = string.Empty;

            //  Asc or Desc
            if (sortDirection.ToLower() == &quot;asc&quot;)
            {
                //  First clause?
                if (initial &amp;&amp; source is IOrderedQueryable)
                {
                    methodName = &quot;OrderBy&quot;;
                }
                else
                {
                    methodName = &quot;ThenBy&quot;;
                }
            }
            else
            {
                if (initial &amp;&amp; source is IOrderedQueryable)
                {
                    methodName = &quot;OrderByDescending&quot;;
                }
                else
                {
                    methodName = &quot;ThenByDescending&quot;;
                }
            }

            object result = typeof(Queryable).GetMethods().Single(
                    method =&gt; method.Name == methodName
                            &amp;&amp; method.IsGenericMethodDefinition
                            &amp;&amp; method.GetGenericArguments().Length == 2
                            &amp;&amp; method.GetParameters().Length == 2)
                    .MakeGenericMethod(typeof(T), type)
                    .Invoke(null, new object[] { source, lambda });
            return (IOrderedQueryable)result;
        }

All good things …
It’s been a long ride, this post. A lot of code discussed, a lot of ground covered. The solution is here.  As always, play around and see how this can help you. If anything breaks, tell Sensei. If you have improvements, tell Sensei. DataTables is a great tool for your arsenal, hopefully the DataTablePager can help you integrate paging with large datasets as part of your solution offering.

Right now Sensei wants to sign off by toasting to you for wading through all of this, and for having the desire to build up your skills.  Obtaining fluency in what you do is a hard road to travel, but it’s worth it because you get things done quicker and better with each session.

Be sure to read about the latest version in “Dynamically Select Columns with Server-Side Paging and Datatables.Net

ActiveEngine Software by ActiveEngine, LLC.