24 Jan 2015

This is a continuation of the Javascript Primer series where we focus on topics essential for .Net or back-end developers or who are transitioning to Javascript and client side development. Many of the topics covered in this series will be related to producing web apps running in the browser. Some design patterns and practices are also application to NodeJS / server-side Javascript apps as well.

Keeping IT Together

One complaint that many have when embarking on applications of medium complexity is that organizing your code is difficult; indeed, even with frameworks you can still end up with giant god object that contains all data-bindings, algorithms, helpers methods. If you take the attitude that Javascript is a second class, toy language where you simply store jQuery animation methods and AJAX calls, you quickly end up with files that can be 3-4000 lines long! Maintaining that is beyond torture.

A common design pattern used to alleviate this issue is the Model View ViewModel (MVVM) pattern. The goal of MVVM is to divide up the logic of your application into UX, business logic, and data-binding activities into discrete components. KnockoutJS is a popular framework that supports this approach. Addy Osmani’s “Design Patterns for Javascript” defines the primary components of MVVM, and it is great primer to read if you are unfamiliar with these terms. For our purposes:

Modelwill contain the data elements, such as FirstName, LastName, etc. Essentially this is a building block for your front-end that will “model” entities such as user, customer, project, etc.

ViewModel will contain the behavior for the UI. This can be business logic, formatting of data, and bridge the gap between data coming from a server and what is useful for the user to interactive with. The ViewModel will also use the Models.

Viewwill be the html document. This will also contain the directives for what to present to the user, and will interact with the ViewModel.

We Still Have A Problem

So even with the MVVM pattern at our disposal we still have to fight bloated ViewModels. From here out we will use a sample project for our discussion where we want to maintain project information comprised of project name, project description, and project notes, team members and a simple timeline / calendar function. Sounds straight forward enough. On our UI we will have a tab for grouping of information, and as information changes on a tab, we want that information available in each subsequent tab. Again, nothing too earth shattering here. It should look something like this JSFiddle below. (NOTE: For the sake of this exercise all code has been placed in the Javascript section of our JSFiddle. You should split your code into modules so they can easily managed).

Each tab on this screen has logical groupings of information. For the sake of argument let’s say that we decide to implement this UI with just one ViewModel for all three tabs. For databinding we will be using KnockoutJS, Starting out we have just one ViewModel – ProjectViewModel – that handles all updates; more specifically, we can take advantage of the data-binding facilities here, so when a team member is added, we can detect this change and automatically execute and update to the calendar.

We have three tabs – “Project Info” is pretty simple, and it uses the computed observable teamSize to display the count of the project team. You note that any changes to “Project Name” will be reflected on the “Team” tab. The tab “Team“ allows you to add a team member. To support updating the calendar with the team member start date we have create subscription to the projectTeam observable array. The tab “Timeline” has a calendar that displays the team member start date, and this is updated each time we add a new team member. Also, any changes to the number of team members will be reflected on the first tab, “Project Info”.

Indeed this works well, since we have the advantage of one ViewModel and can benefit from easily sharing one set of data between all three tabs, But we still have an issue should we start adding more functionality and increase the properties and functions in the ProjectViewModel. Soon maintaining the ViewModel will become difficult, and testing discrete portions of functionality will rapidly become difficult. We need to be able to isolate or reduce the impact that the alterations made to the ViewModels have on each other. This means adhering to the principal of “loose coupling”.

So what does it mean for us to create a ViewModel per tab? The biggest issue now will be communicating between each ViewModel, and as always, our mantra should be “Keep it simple. Please. Pretty please”. So how do we achieve communicating data updates without creating three ViewModels that are still highly dependent on the others? Our solution is to implement a subscribe and publish message architecture. While this sounds intimidating, this simply means we will create each ViewModel with a method – a “subscription” – that will wait for a message that has the data we need. As a corollary, each ViewModel need a way to “publish” any changes to data that occurs.

Super Simple Message with PostalJS

PostalJS is a very simple messaging framework that facilitates sub / pub messaging in a unique way. In particular, PostalJS allows us to set up a subscription that remains “ignorant” of how the message is generated. There is no “pre-registration processes” to map out a route between ViewModels; on the contrary, your Javascript object simply declares that will update when a subscription arrives. This also means that several ViewModels can subscribe to an event and the publisher doesn’t care.

Here is a brief sample taken from github:

var subscription = postal.subscribe({
channel: "orders",
topic: "item.add",
callback: function(data, envelope) {
// `data` is the data published by the publisher.
// `envelope` is a wrapper around the data & contains
// metadata about the message like the channel, topic,
// timestamp and any other data which might have been
// added by the sender.
}
});
postal.publish({
channel: "orders",
topic: "item.add",
data: {
sku: "AZDTF4346",
qty: 21
}
});

Looks pretty cool. And simple. So for us, our ViewModels will remain ignorant of each other, and only are aware that someone, something has sent data to it. Another nice by product is that should one of the ViewModels fail, the impact is greatly reduced. So should the ViewModel with the calendar fail, the other tabs could still collect data and function. Better yet, adding new features to a ViewModel is going to be easier to achieve since we can test in isolation, and if the new features do not interrupt our sub / pub messaging, we can feel confident that new changes can be rolled into production without bringing down the entire application. Let’s look at the results, then examine the changes to our app’s architecture.

A Brave New World

If you open the Javascript tab of the JSFiddle, you’ll see that we have broken up the ProjectViewModel into 3 ViewModels: TeamViewModel, TimelineViewModel, and of course the remants of ProjectViewModel. We’ll take the updates on at time, focusing on the feature in the UI and work back to the code.

Project NameAs before, entering the project name in the “Project Info” tab updates the title in the “Team” tab. Same as before, the update happens when the input box loses focus. Now let’s focus on the code. Open up the Javascript in the JSFiddle, and you’ll see some drastic changes. In the ProjectViewModel we have created a Knockout trigger that publishes a message:

So what we are doing here telling Knockout “Anytime there is a change to the observable _projectName, fire off a function that publishes a piece of data with the new value of _projectName”. That’s it. ProjectViewModel has fulfilled its responsibility and told anyone who will listen that a change has taken place. Now find the TeamViewModel object. Here we have a subscription that waits for a message containing _projectName updates:

We get the data, and merely update an observable on the TeamViewModel. It should be apparent by now that neither ProjectViewModel nor TeamViewModel “know” about each. ProjectViewModel says “_projectName update ready” and who can handle it, does so. TeamViewModel just grabs the update, uses it. That’s it. The messaging works by creating a “channel” – in this case “project” – further defines the message with a topic – “edit.projectNameChange”. This means you can a single channel that support multiple topics and narrowly define your event messages.

ProjectTeam UpdatePlay around with the “Team” tab and add some team members with different dates. The operates just as before. Under the hood, the code in TeamViewModel that handles the publishing is:

As before, we are asking KnockoutJS to watch for changes to the _projectTeam array, and when a change occurs, we publish a different message. The portion of code – topic: “edit.teamUpdate” distinguishes this event from the previous on. We simply take our observableArray and convert it a plain Javascript script array and throw out to whoever wants it. If you look in both ProjectViewModel and TimelineViewModel you’ll see subscriptions that handle this topic. This brings us to another important aspect of messaging and postaljs’ strength: should we want to add more ViewModels that need _projectTeam updates, we only need to subscribe to the topic “edit.teamUpdate”. We could subscribe 50 more times if we wanted. The publisher / source ViewModel does not need any alteration, and this achieves our goal of loose coupling.

What Are The Other Benefits?

Looking at our ViewModels, you may have noticed that we are exposing less in the return statements, and with each ViewModel handling less functionality they become simpler to read and maintain. Imagine that the needed to support 20 different data entry input boxes – one monster ViewModel would have a huge return statement. It makes it hard to keep things straight in one “god” class.

With PostalJS and event messaging we no longer need to expose an entry point in our objects for data to be passed. The subscriptions allow the ViewModel to handle receiving update messages internally. A quite common scenario would be responding to an AJAX update. With PostalJS you can avoid calls to each ViewModel when new data arrives from the server. Simply publish to the appropriate topic and let the ViewModels respond as they need.

19 Jan 2015

“This. Is Not. For. Practice!” – a phrase used to emphasize that you must get things right. Mentors have used it to mean “Get serious, now!”.

For years jQuery has been a tremendous productivity boost for client-side development; so successful, that it gave rise the Single Page Application (SPA) where a good portion of your application logic was now written with Javascript. Soon, so soon, we all learned that the increased complexity of our client side solutions required good organization, a better architecture. Time to get serious about clean code.

If you are .Net developer, then many times you can fall into the ECMAScript trap: all ECMAScript must be the same. What I know from C# must be applicable to Javascript, ’cause it looks the same. Sad news, it’s not. Javascript executes in a much different environment. And to make things more confusing, close cognates such as this are not close enough. “this” in C# is a reference to the current object. “this” is Javascript is , well, it all depends. “this” in Javascript changes context dependent on many factors. A good reference is here at Mozilla. Let’s create a quick summary, and where relevant we’ll talk relevant areas that impact programming practice:

Global Context

When you are outside any function, this is referred to as the global context. ”this” will refer to document. So if you fire up the console and perform this test:

console.log(this == document); // true.

And in web browsers this also equals the window. So:

console.log(this == window); // true.

Yikes! Wait there’s more. Try this little piece:

var yikes = "ouch";
console.log(window.yikes); // ouch

window is our global memory space. So think back to any client side code you have written, and this should be very familiar to you:

<script type="text/javascript" src="scripts/jquery.min.js"></script>

This loads jQuery into the global memory space. Go look at window and you will see “window.$” and “window.jQuery”. You guessed it, jQuery is now loaded into the global namespace.

This may seem like a digression, but we need to pause at this very important point. You must be really careful what you put into this global space. As you grow in Javascript capability you will eventually develop your own utils or libraries. So consider this very innocent utility file:

All of these functions are now attached to the global namespace, our what is called “polluting the global namespace”. Most likely a utility class will have 20 – 30 functions, not the mere three listed above. These functions will remain in memory until the user refreshes or navigates away from the page. With a small app, this will be no problem, but anything with a moderate degree of code will soon balloon and consume memory. And in some cases, such as a mobile friendly websites, you want to conserve as much memory as you can, only loading the objects that you need then allowing them to be garbage collected.

Wow – we’ve only covered “this” in a global context, and if your head isn’t a little numb, don’t worry, do another shot and see if it gets worse!

Function Context – Simple Call

Here we get a strange, as this is the rule: ”this” will depend on how the function is called. Consider this code:

var myFunc = function(){
return this;
};
myFunc() == window;

Since we are not using strict mode “this” must refer to something so it will default to the global object. Changing the code to:

You’ll note that both mathDoer.someNumber and mathDoer.addSomeNumber() are public in scope. When first developing in Javascript it may be tempting to create your objects as depicted below, and while it is legitimate, it will lead to clutter very quickly:

Many of you may be coming to Javascript via KnockoutJS, a data binding library that provides two way binding between the DOM and Javascript objects. Many of the KnockoutJS samples use this “style” for creating ViewModels:

Again, our observables and functions are public in scope. If you have a separate file for this ViewModel and simply include it with the HTML your “vm” variable is now added to the window object and part of the global memory space. This can be considered good or bad. From a diagnostics perspective, you can sit at the console and see what our ViewModel is doing by simply issuing commands like “vm.someNumber(45);” Good for debugging. This is also considered bad by others for two reasons: everything is public, and this can lead to bloated objects that are hard to use; and, you have added yet another item to the global memory space. Imagine you have several ViewModels for a single page. Things can get confusing very quickly.

So how can you make items private? Remember that the scope of “this” when used in a constructor is a reference to that object – in our case that object is mathDoerViewModel. If you were merely to declare a variable in the constructor, the scope of that variable would be local to the constructor. This “hides” the variable from contexts that are outside the scope of the constructor. That would look like this:

From the console still can interact with mathDoerViewModel.someNumber() and mathDoerViewModel.addSomeNumber(). We also have private functions and variables now: _justAnInt and privateFunction. For the .Net developer these conventions should have more familiar feel.

When you scour the web for Javascript code, you’ll find that many of the Javascript heavies will use a different standard for variable / scope hiding. We touch on that briefly here before we move on. In Javascript, your constructor returns a reference to the object you are creating. In other words, your constructor will return a version of “this” that refers to the objects properties and functions. However, your constructor can also return an object. This gives you great flexibility, and makes the “Module Reveal Pattern” possible. First here is what our ViewModel would look like using the Module Reveal Pattern:

Looks a little different. In our constructor we are creating local variables and local functions, and in fact our observable – _someNumber – is now a local variable. But we “reveal” the items that we want to be public with the “return” statement. So in this case, we return an object with someNumber that references _someNumber, and references addSomeNumber. As a result, we can create:

Notice that we are passing in a “ko” variable in the constructor call. This serves many purposes: firstly, it makes the ViewModel modular, and allows us to load the module asynchronously with AMD tools like requirejs or curljs; secondly, the constructor signature lets us know that we are depending “ko” to make our ViewModel work; finally, it gives us a tiny speed boost as now that “ko” is local, since Javascript does not have to search up the stack to find it.

You should avail yourself of the fantastic book “Learning Javascript Design Practises” by Addy Osmani. He’s been kind enough to place a copy online. This will help you understand some of the code that is that would otherwise seem very strange compared to what you are used to in C#.

Function Context – As A DOM Handler

Moving on the DOM, “this” takes on a different context. You’ll most likely be familiar with this common jquery statement:

The rule here is that “this” means the DOM object that fires the handler. So in this case “this” is equal to event.currentTarget.

Go Forth And Create

By now your head should hurt a little, with all these nuances it’s wonder that you don’t feel more beaten up. That’s where the complexity of web development is under appreciated. Hopefully we have covered enough here for you to save some time debugging, designing, or trying to understand some the vast Javascript frameworks, utils and libraries that are out there. If you are coming from .Net and are new to Javascript, you avoid the trap that many have fallen into of creating monstrous Javascript objects of pure public functions and properties jammed into a single file. This will lead to a deep valley of frustration when it comes time to refactor your code after you realize you have a hard time maintaining things. If you can keep your code modular and have things reside in separate files, you’ll be better off.

We covered “this” in order to reveal some deeper yet vital nuances to Javascript. Mastering “this” and the related topics above are going to help. A lot. This brings Javascript from being a “toy” to really productive platform because you can avoid some pitfalls that slow you down. In future posts we continue to build on this foundation where we focus on modular design and asynchronous loading.

25 May 2013

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:

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.

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:

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:

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

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.

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.

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.

25 May 2013

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.

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?

31 Aug 2012

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.

31 Aug 2012

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.

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.