Click this link immediately, and you’ll see wonderful things! Sensei has said many times that simple is better, and rgubarenko of MakeItSoft has a brand spanking new template engine that is so simple it makes you speechless. His premise: every possible rendering task can be accomplished as a random combination of two functional primitives:

repeat – repeats fragment of HTML code for each object in arraytoggle – shows or hides fragment of HTML depending on boolean flag

Here is an example taken from the github site. To get the output display below:

This looks very promising. In fact, this could be a very cool way of writing reports in jQuery! Think about it – with a tool like jLinq for filtering data sets and jsRazor, you could replace SQL Server Reports.

Sensei is a libertarian – so you can interpret that to mean few rules, respect others freedom, government and busy bodies “leave me the hell alone”, stay-outta-my-way-attitude-person is his motto. That means the only way to drive is with the stick. Automatic is for the soccer moms. Javascript is like driving manual transmission – sometimes you grind the gears.

It’s not Javascript’s fault, it’s Sensei’s fault. Now you can see why he writes in the third person, ’cause it’s easier to remove yourself from these type of dumb mistakes when you can treat your persona as separate person!! If you see the issue, leave a comment before I post the resolution.

On 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:

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:

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:

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:

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.

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:

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:

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

(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:

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:

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.

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?

The last episode of server-side paging with DataTablerPager for DataTables.Net we reviewed the basics of a server-side solution that paged records and returned results in the multiples as specified by DataTables.Net. You will want to have read that post before preceding here. The older version of the source is included in that post as well as this will help get you acclimated. The following capabilities were reviewed:

The solution used generics and could work with any collection of IQueryable. In short any of your classes from you domain solution could be used.

Filtering capability across all properties was provided. This included partial word matching, regardless of case.

Ordering of result set was in response to the column clicked on the client’s DataTables grid.

DataTablePager Enhancements

This past month Sensei has added new capabilities to the DataTablePager class that makes it an even better fit for use with DataTables.Net. The new features are:

Dynamically select the columns from the properties of your class based on the column definitions supplied by DataTables.Net!!!

Exclude columns from sort or search based on configuration by DataTables.Net

Mix columns from your class properties with client-side only column definitions; e.g. create a column with <a href>’s that do not interfere with filtering, sorting, or other processing.

Before we jump into the nitty-gritty details let’s review how DataTables.Net allows you to control a column’s interaction with a data grid. Grab the new source code to best follow along.

DataTables.Net Column Definition

You would think that there would be quite a few steps to keep your server-side data paging solution in concert with a client side implementation, and that would mean customization for each page. DataTables.Net provides you with fine control over what your columns will do once displayed in a data grid. Great, but does that mean a lot of configuration on the server side of the equation? As well soon see, no, it doesn’t. What is done on the client for configuration will be that you need to do.

The structure aoColumnDefs is the convention we use for column configuration. From the DataTables.Net site:

aoColumnDefs: This array allows you to target a specific column, multiple columns, or all columns, using the aTargets property of each object in the array (please note that aoColumnDefs was introduced in DataTables 1.7). This allows great flexibility when creating tables, as the aoColumnDefs arrays can be of any length, targeting the columns you specifically want. The aTargets property is an array to target one of many columns and each element in it can be:

a string – class name will be matched on the TH for the column

0 or a positive integer – column index counting from the left

a negative integer – column index counting from the right

the string “_all” – all columns (i.e. assign a default)

So in order for you to include columns in a sort you configure in this manner:

In other words we are defining that the first column – column 0 – will not be included in the sorting operations. When you review the columns options you’ll see you have options for applying css classes to multiple columns, can include a column in filtering, can supply custom rendering of a column, and much more.

In the example that we’ll use for the rest of the post we are going to provide the following capability for a data grid:

The first column – column 0 – will be an action column with a hyperlink, and we will want to exclude it form sort and filtering functions.

Only display a subset of the properties from a class. Each of these columns should be sortable and filterable.

Maintain the ability to chunk the result set in the multiples specified by DataTables.Net; that is, multiples of 10, 50, and 100.

Column 0 is our custom column – do not sort or search on this content. Look at oObj.aData[4] – this is a column that we’ll return but not display. It’s referred so by the position in the data array that DataTables.Net expects back from the server.

Columns 1 – 3 are data and can be sorted. Note the use of “sName”. This will be included in a named column list that corresponds to the source property from our class. This will be very important later on for us, as it allows us to query our data and return it in any order to DataTables.Net. DataTables will figure out what to do with it before it renders.

Threw in another custom column. Again, no sort or search, but we’ll see how this affects the server side implementation later on. Hint – there’s no sName used here.

Another data column.

To recap, we want to be able to define what data we need to display and how we want to interact with that data by only instructing DataTables.Net what to do. We’re going to be lazy, and not do anything else – the class DataTablePager will respond to the instructions that DataTables.Net supplies, and that’s it. We’ll review how to do this next. Sensei thinks you’ll really dig it.

DataTablePager Class Handles your Client Side Requests

If you recall, DataTables.Net communicates to the server via the structure aoData. Here is the summary of the parameters. One additional parameter that we’ll need to parse is the sColumns parameter, and it will contain the names and order of the columns that DataTables.Net is rendering. For our example, we’ll get the following list of columns if we were to debug on the server:

,Name,Agent,Center,,CenterId,DealAmount

These are all the columns we named with sName, plus a place holder for those custom columns that not found in our class. This has several implications. For one, it will mean that we will no longer be able to simply use reflection to get at our properties, filter them and send them back down to the client. The client is now expecting an array where each row will have 7 things, 5 of which are named and two place holders for items that the client wants to reserve for itself. Hence the convention of passing an empty item in the delimited string as shown above.

It will also mean that we’ll have to separate the columns that we can filter or sort. Again this is the reason for leaving the custom column names blank. In other words, we’ll have to keep track of the items that we can search and sort. We’ll do this with a class called SearchAndSortable:

This will summarize what we’re doing with our properties. The property ColumnIndex will record the position in sColumn where our column occurs. Since we’ll need access to the actual properties themselves we’ll store these in the SearchAndSortable as well so that we can reduce the number of calls that use reflection. DataTablePager uses a List of SortAndSearchables to track what’s going on. We fill this list in the method PrepAOData()

We’ll get the properties from our class. Next we’ll traverse the columns and match the property names with the names of the columns. When there is a match, we need to query aoData and get the column search and sort definitions based on the ordinal position of the column in the sColumns variable. DataTables.Net convention for communicating this is the form of:

Now we go through the list of properties again but this time determine if we should sort any of the columns. That happens in the section //Sort. In the end we have a list of properties that corresponds with the columns DataTables.Net has requested, and we have defined if the property can be search (filtered) or sorted.

For filtering DataTablePager recall that we use the method GenericSearchFilter(). The only alteration here is that we only will add the properties to our query that are defined as searcable:

The rest of the method is unaltered from the prior version. Pretty cool!! Again, we’ll only get the properties that we declared as legal for filtering. We’ve also eliminated any chance of mixing a custom column in with our properties because we did not supply an sName in our configuration.

The method ApplySort() required one change. On the initial load of DataTable.Net, the client will pass up the request to sort on column 0 even though you may have excluded it. When that is the case, we’ll just look for the first column that is sortable and order by that column.

After we have filtered and sorted the data set we can finally select the only those properties that we want to send to the client. Recall that we have parsed a variable sColumns that tells what columns are expected. We’ll pass these names onto extension method PropertiesToList(). This method will only serialize the property if the column is include, and since we have already paired down our data set as a result of our query and paging, there is very little performance impact. Here is the new PropertiesToList method:

You might ask why not just pass in the list of SearchAndSortTable and avoid using reflection again. You could, but remember at this point we have reduced the number of items to the page size of 10, 50 or 100 rows, so your reflection calls will not have that great an impact. Also you should consider whether you want to simply have a function that will select only those properties that you need. Using SearchAndSortable would narrow the scope of utility, as you can use this method in other areas other than prepping data for DataTables.Net.

Now It’s Your Turn

That’s it. Play with the page named SpecifyColumns.aspx. You should be able to add and remove columns in the DataTable.Net configuration and they will just work. This will mean, however, that you’ll have to always define your columns in your aspx page. But since we worked really hard the first time around, DataTablePager will still be able to create paged data sets for any class in your domain.

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.

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.

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:

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:

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.

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:

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:

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:

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():

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

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.