With this release we welcome new core team member Michael Best, who implemented a lot of the 2.1.0 goodness. One of my favourite new features is the $index context variable. Here’s a short usage example:

The cool thing is that $index is an observable and is updated automatically as you add or remove items in any collection bound to a foreach (and so your UI will update to match). Impressively, Michael was able to add this new functionality while simultaneously improving the performance of foreach whether or not you are using $index!

We also benefited from pull requests, issue reports, and feature suggestions from many others in the community. Special thanks to neonstalwart and mtscout6 for not only implementing AMD module loader support and putting up with a lot of questions from me, but even including full documentation pages in their pull request – flawless OSS etiquette!

Again, if you want to know more about what’s new in KO 2.1.0, head on over to Ryan’s post for a full rundown.

Getting the post-beta tools update, and running the scaffolder

First, make sure you have ASP.NET MVC 4 Beta. Then if you want to scaffold up a simple data-editing SPA,

• Create a new MVC 4 project. Choose the Single Page Application subtemplate.
• Once you’ve created the new project, pop open NuGet package console (View > Other Windows > Package Manager Console), and install the latest scaffolder templates as folllows:

Install-Package SinglePageApplication.CSharp

Or, if you’re using Visual Basic instead of C#, install the VB package instead:

Install-Package SinglePageApplication.VisualBasic

Don’t skip this step, otherwise you’ll be using the old beta SPA templates and the result will be much less interesting.

Note that Visual Studio may give a false compiler error (“The type or namespace name ‘MvcTextTemplateHost’ could not be found”) – you can either just ignore it, or restart Visual Studio to make it go away. This is an unfortunate limitation of the way we’re packaging this post-beta update, and won’t affect the final tooling.

• Now you can follow the on-screen instructions in /Models/TodoItem.cs to scaffold a simple data-editing SPA. Use the Add Controller dialog as explained in the comments on that file, remembering to build the solution first, and then you can run the app and browse to http://localhost:whateverport/Tasks.

If you want to learn what the point of all this is, see http://www.asp.net/single-page-application or watch this presentation.

Getting the DeliveryTracker sample

If you want to see a slightly bigger and more fun app built with the same libraries and architecture, you can get hold of the DeliveryTracker app that I built during the SPA presentation. If you want to see the mobile UI, you’ll want to either use a real mobile to view it, or fake your useragent (instructions for IE or Chrome or Firefox).

Note that the source on GitHub doesn’t include the offline support, as that’s still very early in development – the design and functionality is still likely to change significantly.

New to all this? Now’s a great time to check it out. Knockout is an MVVM library for JavaScript – it makes rich dynamic web UIs easier and cleaner to build. The best place to start learning is with the interactive tutorials.

What just happened?

• The finished 2.0.0 build is now on GitHub
• All of the documentation and live examples are updated to reflect the new version
• All of the interactive tutorials are updated too.

Credits go to the many community members who contributed pull requests, bug reports, new documentation, and support during this process. These people include aaronpowell, amonat, antis, aredridel, artiomchi, barkmadley, b-dur, bmac, cburgdorf, develop-me, DomenicDenicola, doodlemoonch, dre2901, drewlesueur, ducka, gigi81, GLuKKi, hunterloftis, ifandelse, joeldart, kmalakoff, lcbarcellos, mbest, mtscout6, neonstalwart, owenssam, Quaternion, rniemeyer, RoyJacobs, schinckel, seanami, SimonBartlett, studgeek, tehsenaus, and tiberiuana – and that’s just those who made recent pull requests (apologies for not tracking everyone who contributed other things). rniemeyer wrote a lot of documentation too.

Why is it called 2.0.0? Why not 1.3.0?

For a long time, we were planning this next version to be called 1.3.0. However,

• Quite a few community members are keen on adopting SemVer-style versioning. 2.0.0 is a good place to start (expermentally) with that versioning convention.
• It’s such a big set of core changes that if this doesn’t count as 2.0, I guess nothing ever would…

New features

I’m mostly going to copy and paste the “what’s new” list from my earlier blog post about Knockout 1.3 beta, with a few further updates. Besides these things, there are all the usual bugfixes and performance improvements that you’d expect.

1. Control flow bindings

Previously, if you wanted to display a repeating sequence of UI elements (“foreach”), or have a section of the DOM exist only if some viewmodel condition was true (“if”), you’d need to create an entire template to define that. A bit cumbersome for something so simple and commonplace! Now you can use the new control flow bindings – if, ifnot, with, and foreach – to achieve basic, declarative control flow without the need for a template. This can make your code a lot more elegant and to-the-point.

Here’s an example of using “foreach” and “if”:

Tip: Switch to the “result” tab to see the output

The "with" binding changes the binding context to whatever object you specify. This makes it easy to compose many independent view models together – you have a host model that contains references to its children, and then use "with" to bind different sections of the page to different child models. Example:

Of course, the "if", "ifnot", "foreach", and "with" bindings can all be combined and nested arbitrarily.

2. Containerless control flow

What if you want to set up template-less control flow (as in the above example), but without having to use extra container elements just to hold the "foreach", "if", etc., bindings? In that case, you can use the new comment-based control flow syntax like this:

The comment-based control flow syntax works with the "if", "ifnot", "foreach", "with", and "template" bindings. In a large number of cases, this means you can skip string-based templates and use the binding-based control flows instead, which can run much faster depending on what exactly you’re doing.

3. Access to parent binding contexts

Whether you’re using regular nested templates, or nesting the new control flow blocks, sometimes you want to reference properties that exist at the upper levels of binding. There are four new pseudo-variables that you can use in any binding (inside or outside traditional templates):

• $data – returns the current item
• $parent – returns the item from the parent binding context
• $parents – an array containing all the parent binding contexts. $parents[0] == $parent, then $parents[1] is the level above that, and so on.
• $root – returns the item at the top level of binding (usually your primary view model)

Example:

4. Cleaner event handling

In most cases, data-bind attributes can be kept clean and elegant. But one rough spot in the past has been event handlers, because to pass parameters, you were generally guided to use function literals. For example:

<button data-bind="click: function() { viewModel.items.remove(this) }">Click me</button>

Many of you rightly pointed out that this is pretty ugly. It’s much nicer if bindings can be kept minimal and declarative! To fix this, KO 2.0 offers two alternative event handling syntaxes, both of which are better.

Firstly, event handlers now receive the current model value as their first parameter. So, you can implement “remove-from-list” as follows, with no inline function literals:

The other option is to use jQuery event delegation to catch events and invoke functions on your viewmodel. This is made possible by the ko.dataFor and ko.contextFor helpers, which tell you which part of your viewmodel a given event relates to. Here’s the preceding example, but now using event delegation:

5. Binding providers (and hence external bindings)

Most KO developers find the default data-bind attributes provide a very convenient, easy-to-maintain way of declaratively associating viewmodels with views. But if you would prefer to store your binding configuration elsewhere, the new binding providers API is an extensiblity point that allows alternative configuration mechanisms to be plugged in.

For example, here’s one possible alternative way that you could configure bindings. Notice the absence of data-bind attributes – I’m using a binding provider to set up the binding configuration in JavaScript:

To be clear, binding providers are a general extensibility mechanism, not any specific configuration format. The above example is just one possible way it can be used to define bindings in JavaScript. I’m looking forward to seeing suggestions from the community about how this extensibility can be used, and for what the most elegant and convenient way of defining bindings might be. I know some of you have already suggested externalising bindings (e.g., Brandon Satrom’s knockout.unobtrusive plugin); this new API will make it easier to implement custom binding mechanisms. Bring on more plugins!

6. Throttling

Note: ko.computed is Knockout 2.0’s new name for ko.dependentObservable – it’s easier to say, type, and explain. This doesn’t affect backward compatibility, though – ko.dependentObservable still works, because it references the same function instance as ko.computed at runtime. You don’t have to change your existing code if you don’t want.

Occasionally, it’s desirable to limit how fast observables and computed observables update. For example, you might be using a ko.computed to invoke Ajax requests whenever a set of observables change. Sometimes you might want to change multiple underlying observables, but only have that ko.computed re-evaluate once, after all the changes (so that it only fires one Ajax request). Effectively, you want a kind of atomic update.

This is now pretty easy to do: you can apply an extender called "throttle" either to observables or to computed observables. For example:

// Will not notify changes faster than once per 500ms 
var myObservable = ko.observable("initial value").extend({ throttle: 500 });
 
// Will not re-evaluate *or* notify changes faster than once per 500ms 
var myComputed = ko.computed(function() { 
    // Evaluation logic goes here, usually referencing other observables 
    return 123;
}).extend({ throttle: 500 });

The way this works is that, when throttled, notifications and evaluations are done asynchronously, and don’t occur at all until they stop being triggered for the specified throttle timeout duration.

In the case of making a computed value only update once even if there are multiple synchronous changes to its dependencies, you can use a very short timeout (for example, 1ms), and then it will re-evaluate as soon as possible after any series of synchronous changes to its dependencies. Example:

Breaking changes

There are two changes that might realistically affect existing 1.2.x application code. Both are for good reasons and are important for the long-term health of the project…

• Event handlers now receive your model object as their first parameter, and the DOM event object as the second parameter. Previously, they only received the DOM event object as the first parameter. So, if you are using the “click” or “event” bindings and are specifically catching and using the DOM event object, you’ll need to change your handler’s signature from this:

myViewModel.myEventHandler = function(evt) { /* do something with evt */ }

… to this:

myViewModel.myEventHandler = function(data, evt) { /* do something with evt */ }

This will not affect any event handlers that don’t specifically receive and process the “event” parameter. We chose to make this change because it significantly simplifies event handling in the majority of cases. Most developers have been able to upgrade to 2.0.0 beta without changing their applications at all.

• KO 2.0.0 drops support for very old versions of jquery-tmpl. If you need to use string-based templating (and most often you won’t now that KO 2.0.0 has native control flow bindings), get jquery-tmpl 1.0.0pre. But also consider dropping the string-based templating, and switching to control flow bindings instead, as jquery-tmpl is no longer in active development.

Summary

Try the updated interactive tutorials, update your existing KO applications, have a great Christmas/vacation/newyear

This is the third in a series of posts about web app layouts, i.e., giving your web-based application a UI comparable to a desktop or mobile/tablet app. Posts so far:

1. Layout basics – A CSS technique for slicing up the browser window into arbitrarily nested panes both horizontally and vertically. You know, like a proper application, and not like an infinite-height document…
2. Animated transitions – How to put more than one content block into a given pane, and then switch between them with hardware-accelerated animations
3. This post – Keeping track of what content has appeared in each pane, so the visitor can navigate back and forwards. And supporting deep linking. And injecting new panes dynamically.

Disclaimer: To be clear, this post series just represents my own experiments in lightweight, flexible web app layouts and is not an official part of any Microsoft technology stack. No guarantees or warranties or SLAs, blah blah blah.

The goal

It’s very common on mobile/tablet-like UIs for users to navigate through some structure of content within a given pane. For example, in a tablet-like app, you’ll often want to have a left-hand pane representing navigation through a hierarchy, with the main section of the screen representing the currently selected item or folder:

So, you’ll want to be able to:

• Keep track of where the user has been, letting them go back and forwards, with each pane able to maintain its own independent history.
• Perform smooth animated transitions within each pane when any navigation event occurs.
• Support deep-linking to arbitrary locations in your content structure
• Fetch and render content dynamically

Basic navigation

Continuing from previous posts that introduced pane hierarchies and panes.js, it’s pretty easy to keep track of where a visitor has been. First you might set up a basic pane layout with a header/body/footer like this:

<div class="page">
    <div class="header row">
        Header will go here
    </div>
    <div class="body row">
        Body contents will go here
    </div>
    <div class="footer row">
        My footer. Could put icons here.
    </div>
</div>

… and then put multiple panes into the body row:

<div class="body row">
    <div id="location-continents" class="pane">
        <h3>Continents</h3>
        <ul>
            <li><a href="#america">America</a></li>
            <li><a href="#europe">Europe</a></li>
        </ul>
    </div>
 
    <div id="location-america" class="pane">
        <h3>Countries in the Americas</h3>
        <ul>
            <li><a href="#canada">Canada</a></li>
            <li><a href="#usa">USA</a></li>
        </ul>
    </div>
 
    <div id="location-canada" class="pane">
        <h3>Cities in Canada</h3>
        <ul>
            <li>Vancouver</li>
            <li>Toronto</li>
            <li>Edmonton</li>
        </ul>
    </div>
 
    <!-- ... etc ... -->
</div>

Now you can begin history tracking by adding a bit of JavaScript to instantiate a PaneHistory object and navigate to an initial pane:

// Navigation
var paneHistory = new PaneHistory();
paneHistory.navigate("location-continents");

… and perform pane navigations each time the visitor clicks on one of the links:

$("a").click(function (evt) { 
    var dest = (evt.srcElement || evt.target).href.split("#")[1]; 
    paneHistory.navigate("location-" + dest); 
    return false; 
});

This code will intercept clicks on the links, figure out which pane they are trying to get to, and then animate that destination pane sliding smoothly into the body area from the right.

If you also want to let the visitor go “back” through the pane’s history stack, add a button perhaps into the page header:

<div class="header row">
    <p><button class="goBack">&lt; Back</button></p>
</div>

… and handle clicks by instructing the PaneHistory instance to perform a reverse navigation animation:

$(".goBack").click(function () {
    paneHistory.back();
});

That’s it. Try it out. Live example:

Also: Run full screen (e.g., to try it on a phone)

Supporting the back/forward buttons and deep-linking

If your app will be deployed to the web (as opposed to using something like PhoneGap to package for an appstore), then you will almost certainly want to respect the browser’s native back/forward buttons and allow deep-linking to specific locations in your virtual navigation system.

There are many JavaScript libraries for working with browser history and the HTML5 pushState feature. Currently my favourite is history.js (license: New BSD) by Benjamin Lupton, because of its robustness, great pushState support, support for older browsers, and because it has no dependencies.

panes.js integrates with history.js, so once you’ve added a reference to history.js, you can start using UrlLinkedPaneHistory instead of PaneHistory. Specify the name of one or more URL parameters that the pane will use to represent what data it is showing. In this case, I’ll call my parameter “location”:

var paneHistory = new UrlLinkedPaneHistory({
    params: { location: 'continents' }
});

Then, update your paneHistory.navigate call so that it specifies which URL parameter is to be updated (in this case, my only parameter, “location”):

$("a").click(function (evt) {
    var dest = (evt.srcElement || evt.target).href.split("#")[1];
    paneHistory.navigate({ location: dest });
    return false;
});

And finally, since it no longer makes sense for “back” clicks to affect only a single pane (the URL history is global), update your “back” button handler so that it performs a global browser “back” navigation:

$(".goBack").click(function () {
    History.back();
});

… and you’re done. Now if you run the follow demo full-screen (click the link below the fake phone UI), you’ll see the URL update as you navigate around, and you can use the back/forward buttons (still getting the animated transitions), and can bookmark or refresh the page without losing your position. If your browser supports HTML5 pushState, for example recent versions of Chrome and Firefox, then your URLs will be updated with real querystring parameters as you go. If your browser doesn’t support pushState, history.js will gracefully degrade to using a URL hash.

Try it:

Dynamically generating panes

If you do a view HTML source on either of the two previous demos, you’ll see that there’s a long list of pre-prepared <DIV> elements – one for each pane that you might visit (Europe, Canada, Vancouver, Toronto, etc….). That’s OK if your app only has a small and finite set of visitable panes (e.g., because those panes represent a fixed number of tabs), but it’s awkward if there are a lot of panes, and useless if the number is effectively infinite because panes represent navigation through data in some large external database.

Fortunately, this is easy to fix. Because panes.js doesn’t modify your DOM structure in any way, and requires no initialisation step to start using newly-inserted DOM elements, it composes perfectly with any external mechanism for updating the DOM. In this example, I’m going to use Knockout.js to inject new panes dynamically as data is fetched from some external source.

The trick here is to make the UrlLinkedPaneHistory a property of your Knockout view model. For example:

function AppViewModel() {
    this.paneHistory = new UrlLinkedPaneHistory({
        params: { location: null },
 
        // Making the set of history entries observable, so we can dynamically generate corresponding DIVs
        entries: ko.observableArray([]),
 
        // Each time the visitor navigates forwards, this will be called to fetch data for the new pane
        loadPaneData: function (params, callback) {
            // Here I'm loading data from some external source, asynchronously
            locationInfoService.getLocationInfoAsync(params.location, callback);
        }
    });
};
 
ko.applyBindings(new AppViewModel());

(Note: do a “view source” on the live example below if you want to see the finished code and what JS libraries you must reference to make all this work.)

Now the set of history entries is observable, we can ask Knockout to generate corresponding DIVs dynamically, by using a “foreach” binding:

<div class="body row" data-bind="foreach: paneHistory.entries">
    <div id="location-continents" class="pane scroll-y" data-bind="attr: { id: paneId }">
        <h3 data-bind="text: paneData.name"></h3>
    </div>
</div>

Notice that Knockout will assign an ID property to each pane <DIV> corresponding to the navigation parameters, so it can associate navigation events with the <DIV> you want to slide into view.

Of course, you don’t just want to display the “name” property of each item you’re visiting – you want to generate some more UI for each pane. Let’s generate a list of child locations that the user can navigate to:

<div class="body row" data-bind="foreach: paneHistory.entries"> 
    <div id="location-continents" class="pane scroll-y" data-bind="attr: { id: paneId }"> 
        <h3 data-bind="text: paneData.name"></h3> 
        <ul data-bind="foreach: paneData.children"> 
            <li data-bind="text: name, 
                            click: $root.navigate, 
                            css: { navigable: childLocations.length }"></li> 
        </ul> 
    </div> 
</div>

Each of the <li> elements there will try to invoke a viewmodel method called “navigate” when you click it. Implement that by adding a “navigate” method to your viewmodel:

function AppViewModel() {
    // Rest of class unchanged
 
    this.navigate = function (evt) {
        var destination = ko.dataFor(evt.srcElement || evt.target);
        if (destination.childLocations.length)
            this.paneHistory.navigate({ location: destination.id });
    } .bind(this);
};

Now the visitor will be able to navigate forwards through the hierarchy of locations. What about navigating backwards too? You can put a “back” button into the header pane, and use a Knockout binding to make its text update to show the name of parent location (e.g., “< Europe”):

<div class="header row">
    <p data-bind="with: paneHistory.currentData().parent">
        <button data-bind="click: $root.navigate">&lt; <span data-bind="text: name"></span></button>
    </p>
</div>

Done. Your visitor can now navigate through an arbitrarily deep hierarchy, with the data being pulled from the server as needed and dynamically rendered on the client. The browser’s back/forward buttons still work, deep linking works, and there are smooth animated transitions. And you wrote about 15 lines of JavaScript . Have a go with it:

What’s next?

Well, what are you interested in? Possible next posts in this series:

• Using all this stuff to build a complete application with meaningful functionality
• Making this kind of Single Page Application (SPA) work offline via HTML5 offline support
• Packaging and selling such apps on mobile appstores via PhoneGap/Callback
• Data access: editing collections of entities, and letting the user track, synchronise, and revert their changes

If you’re building single page applications, whether for mobile or desktop or both, please let me know what sort of technologies you’re using, what challenges you face, and what kinds of features you’d like to see baked into the ASP.NET/MVC stack.

In the previous post, I showed a simple yet very useful and robust CSS technique for creating full-height layouts for web-based applications. To recap, it means you can subdivide both the width and height of the screen into a arbitrarily nested set of panes, each of which can scroll independently. This is useful whether you’re building apps for desktop browsers, for tablets, or for phones.

Not amazingly exciting just yet, but there’s more…

One of the other reasons for defining pane positioning using those particular CSS rules is that it becomes trivial to have multiple different content panes that can populate any given pane container, then to change which pane is visible within a container, and even to animate the transitions during those changes.

For example, here’s a layout involving a fixed header, a fixed footer, and two scrollable body regions (laid out using the same CSS rules as defined in the previous post):

<div class="header row">
    <h2>My header</h2>
</div>
<div class="body row">
    <div class="first pane scroll-y">
        <p>This is the first body view</p>
    </div>
    <div class="second pane scroll-y">
        <p>This is the second body view</p>
    </div>
</div>
<div class="footer row">
    <p>My footer. Could put icons here.</p>
</div>

This will lay out as follows, with the first body pane and second body pane occupying the same area on the screen:

Then, you can trivially switch between the two body panes just by controlling their visibility (e.g., by using $(".first.pane").hide() and $(".second.pane").show()).

Animating the transitions

Instead of just hiding and showing panes instantly, you can cause them to fade in/out or even to slide in and out. This pretty well replicates an aspect of the UI experience familiar to users of touch-based smartphones and tablets.

However, JavaScript-based animation mechanisms (such as $.animate in jQuery) aren’t as smooth as I’d like. They tend to give low frame rates, as the browser has to run custom JavaScript to compute the positions of elements for each frame. Fortunately since we’re controlling the layout purely using CSS, it’s both easy and robust to use pure CSS 3 animated transitions, giving silky-smooth results on devices that support hardware accelerated CSS transforms (e.g., iPhone and iPad), exactly like a native application.

To make this easy to reuse, I created a small bit of JavaScript boilerplate (about 1kb gzipped) that exposes functions for triggering pane transitions, being sure to take full advantage of hardware acceleration where available. For example, you can write:

// Initial pane visibility
$(".first.pane").showPane();
 
// Navigation between panes
$(".first.pane button").clickOrTouch(function () {
    $(".second.pane").showPane({ slideFrom: 'right' });
});
$(".second.pane button").clickOrTouch(function () {
    $(".first.pane").showPane({ slideFrom: 'left' });
});

… and then if you click any button in the first body pane, the second body pane will slide in smoothly from the right, and vice-versa. Note that although this code uses looks as if it uses jQuery, it doesn’t – it actually uses XUI instead (a very lightweight JavaScript framework that implements a fraction of the jQuery API in a fraction of the space), but you could equally do similarly with jQuery.

The boilerplate code offers the following transitions:

• slideFrom – causes the target pane to slide in from the specified direction, and simultaneously the current pane to slide out in the opposite direction
• coverFrom – causes the target pane to slide in from the specified direction. The current pane stays still, getting covered over by the target pane.
• uncoverTo – causes the current pane to slide out in the specified direction, revealing the target pane underneath
• default – instantly shows the target pane and hides the current pane

… and it works on IE7+ (including WP7 Mango), iOS, Firefox, Chrome, Safari, Opera, and probably others. For browsers that support hardware-based CSS3 transforms, like Safari on iOS 4+, it will be used and is impeccably smooth; others will use unaccelerated CSS3 transforms, and for those that don’t support CSS3 transforms, it falls back on JavaScript-based animation.

Also notice the “clickOrTouch” event – on browsers that support touch events (e.g., iOS Safari), this fires the instant your finger comes into contact with the screen (and hence is noticably faster than a regular click), whereas on non-touch devices, it’s equivalent to a regular click (i.e., when you release the mouse).

Runnable examples

Here’s a phone-styled example just showing how you can transition the contents within a given pane, or you can transition the contents of the entire screen. Note that this is an iframe you can interact with, not just a pretty picture

Also: Run full screen (e.g., to try it on a phone)

Similarly, here’s a tablet-styled example showing how transitions work just the same in arbitrary sub-panes as well.

Also: Run full screen (e.g., to try it on a tablet device)

Note: To be clear, I’m not starting a new open source project here. These are experiments in mobile-friendly app layouts – I’m blogging the results just in case it’s useful to someone else! In the next post, I’ll focus on managing navigation history within each pane, so you can easily let a visitor go “back” and “forwards”.

That makes sense for documents, but it’s a pain for application UIs. Native application UIs tend to slice up the screen both horizontally and vertically into a nested set of panels, some of which may scroll/resize, others being docked against particular edges of their parent panes.

So, what’s the robust way, with HTML/CSS, to set up a nested collection of panes that exactly divide both the width and height of the browser window?

Hang on, didn’t we have this one solved back in 1999?

Hmm… this reminds me of something… I remember: the <frameset> tag from HTML 4. Yes, HTML frames do divide the browser window both horizontally and vertically, exactly consuming the available screen area. So why don’t we use them any more? There are loads of reasons, including:

• What you’re building is logically one page, but technically each frame is a separate HTML document, which makes interactions between them so much more complex
• It’s not really practical to support deep-linking to (i.e., bookmarking) particular UI states
• Mobile devices and tablets have very limited support for HTML 4 frames. iOS in particular requires the user to use two-fingered scrolling within panes. This is UX death.

OK, so what’s the 21st century solution?

I’ve used lots of hacks and tricks over the years to get columns and panes into my web applications, often involving JavaScript, $(…).height(…), window.body.clientHeight, and the onresize event. Ugh. Fragile and messy. But at long last this week I learned there is actually an elegant and robust way to set up nested exact-height panes with pure CSS, and it works on all browsers back to IE 7, even on current mobile browsers that don’t support position:fixed.

You know that if you set position: absolute on an element, then you can make it appear at a specified distance from the top, left, right, or bottom from its parent element. Well, it turns out that you can specify both top and bottom, or both left and right, and then it will dock against both edges and always resize to match its parent’s dimensions.

Let’s define some generic CSS rules for panes:

/* Generic pane rules */
body { margin: 0 }
.row, .col { overflow: hidden; position: absolute; }
.row { left: 0; right: 0; }
.col { top: 0; bottom: 0; }
.scroll-x { overflow-x: auto; }
.scroll-y { overflow-y: auto; }

Now it’s easy to set up a fixed-height header, variable-height body, and fixed-height footer:

<body>
    <div class="header row">
        <h2>My header</h2>
    </div>
 
    <div class="body row scroll-y">
        The body
    </div>
 
    <div class="footer row">
        My footer
    </div>
</body>

Of course, you also have to configure the heights and positions of the three rows by using a bit more CSS:

.header.row { height: 75px; top: 0; }
.body.row { top: 75px; bottom: 50px; }
.footer.row { height: 50px; bottom: 0; }

The result? It’s the classic mobile phone app layout. Screenshot with some colours and content added for interest:

Try it in your desktop or mobile browser here. Works on IE7+.

More nesting (or, tablet-style layouts)

The reason for setting up the generic CSS rules in that way is that it makes it easy nest panes arbitrarily. For example, you could split the main viewport into two vertical columns:

<body>
    <div class="left col">
        Left col here    
    </div>
    <div class="right col">
        Right col here
    </div>
</body>

… and then subdivide the right column so it has a fixed header, variable-height body, and fixed footer, just by putting some more row divs inside it:

<div class="right col">
    <div class="header row">
        View or edit something
    </div>
    <div class="body row scroll-y">
        Here’s some content that can scroll vertically
    </div>
    <div class="footer row">
        Some status message here
    </div>
</div>

Here’s the CSS to configure the widths/heights/positions of those panes:

.left.col { width: 250px; }
.right.col { left: 250px; right: 0; }
.header.row { height: 75px; line-height: 75px; }
.body.row { top: 75px; bottom: 50px; }
.footer.row { height: 50px; bottom: 0; line-height: 50px; }

Going further, in the right-hand pane’s body, you could also nest a horizontally-scrollable row:

<div class="body row scroll-y">
    <p>Here's a horizontally-scrollable thing:</p>
 
    <div class="scroll-x">
        Any content in here, if it's too wide, becomes independently scrollable
    </div>
 
    <p>That's enough - bye.</p>
</div>

The result of all this? Well, it’s a structure like this:

… but that’s pretty boring to look at, so here’s a version where I threw in a rough effort of some iPad-like styling:

Here’s a live example. It still renders correctly on very small screens (like a WP7 or iPhone) but this 2-column layout really needs a wider screen to be usable.

Enabling touch scrolling

The scrolling looks and works fine on a desktop browser, but on a mobile browser it varies:

• On WP7, you’ll see no scrollbars, but you’ll get one-finger touch scrolling, without the lovely inertia/momentum effect. This is kind-of OK, though imperfect.
• On iOS, you’ll see no scrollbars, and it requires two-finger scrolling (which is horrible), and it won’t use the inertia/momentum effect either. Badness.
• There are similar problems on Android

With iOS 5, it will be possible to enable fluid, native touch-based momentum scrolling to our divs just by making a tiny tweak to the CSS, thanks to the new “touch scrolling” feature:

.scroll-x, .scroll-y { -webkit-overflow-scrolling: touch; }

I really hope this catches on and becomes a standard.

But in the meantime, for visitors on other mobile OSes, and until iOS 5 becomes prevalent, you can use the open-source iScroll library that provides one-finger momentum scrolling for Webkit (iOS and Android) and Mozilla browsers.

Enabling momentum scrolling on any given element requires only one line of JavaScript (assuming you’ve referenced iScroll.js):

new iScroll(theElementYouWantToEnableItFor);

For my example, I used the following block of JavaScript, which enables touch scrolling on all the .scroll-x and .scroll-y elements:

<!-- Touch scrolling -->
<!--[if !IE]><!-->
<script src="script/iscroll.js" type="text/javascript"></script>
<script type="text/javascript">
    var xScrollers = document.getElementsByClassName("scroll-x");
    for (var i = 0; i < xScrollers.length; i++)
        new iScroll(xScrollers[i], { vScroll: false });
 
    var yScrollers = document.getElementsByClassName("scroll-y");
    for (var i = 0; i < yScrollers.length; i++)
        new iScroll(yScrollers[i], { hScroll: false });                
</script>
<!--<![endif]-->

You could do this in fewer lines if you’re using a library like jQuery or XUI (which is a tiny implementation of a small part of the jQuery API surface, intended for mobiles). Here’s the resulting mobile-style scrollbar:

Of course, to see the momentum effect, you’ll need to run it in your Chrome/Safari/Firefox browser.

Credits: Thanks to Rob Swan and FellowshipTech for their articles and projects where I found the CSS positioning trick that underlies this approach to exact-height layout.

The key theme is developer happiness – the new features will let you get more done with less code, eliminate some previous limitations, and offer more power to extend and customize how things work.

New to Knockout? If you’ve never used it before, don’t start with this post – start with the interactive tutorials.

The 1.3 code is now stable and feature-complete, so it’s time for a beta release. You can get it from…

• For the JavaScript files, get the minified version (13kb gzipped, for production use) and/or the debug version
• For the source, head over to the GitHub repo

For Visual Studio users, the NuGet package ID is knockoutjs, and this latest version is 1.2.9.0 (reserving version 1.3.0 for the final 1.3 release).

So, what’s new? Well, full documentation for the new features is still to be written, but here’s a brief rundown of the main enhancements.

1. Control flow bindings

Previously, if you wanted to display a repeating sequence of UI elements (“foreach”), or have a section of the DOM exist only if some viewmodel condition was true (“if”), you’d need to create an entire template to define that. A bit cumbersome for something so simple and commonplace! Now you can use the new control flow bindings – if, ifnot, with, and foreach – to achieve basic, declarative control flow without the need for a template. This can make your code a lot more elegant and to-the-point.

Here’s an example of using “foreach” and “if”:

Tip: Switch to the “result” tab to see the output

The "with" binding changes the binding context to whatever object you specify. This makes it easy to compose many independent view models together – you have a host model that contains references to its children, and then use "with" to bind different sections of the page to different child models. Example:

Of course, the "if", "ifnot", "foreach", and "with" bindings can all be combined and nested arbitrarily.

2. Containerless control flow

What if you want to set up template-less control flow (as in the above example), but without having to use extra container elements just to hold the "foreach", "if", etc., bindings? In that case, you can use the new comment-based control flow syntax like this:

The comment-based control flow syntax works with the "if", "ifnot", "foreach", "with", and "template" bindings. In a large number of cases, this means you can skip string-based templates and use the binding-based control flows instead, which can run much faster depending on what exactly you’re doing.

3. Access to parent binding contexts

Whether you’re using regular nested templates, or nesting the new control flow blocks, sometimes you want to reference properties that exist at the upper levels of binding. There are four new pseudo-variables that you can use in any binding (inside or outside traditional templates):

• $data – returns the current item
• $parent – returns the item from the parent binding context
• $parents – an array containing all the parent binding contexts. $parents[0] == $parent, then $parents[1] is the level above that, and so on.
• $root – returns the item at the top level of binding (usually your primary view model)

Example:

4. jQuery-style event handling

In most cases, data-bind attributes can be kept clean and elegant. But one rough spot in the past has been event handlers, because to pass parameters, you were generally guided to use function literals. For example:

<button data-bind="click: function() { viewModel.items.remove(this) }">Click me</button>

Many of you rightly pointed out that this is pretty ugly. It’s much nicer if bindings can be kept minimal and declarative! To fix this, KO 1.3 lets you replace that with:

<button class="remove-item">Click me</button>

… and then in your JavaScript, add this (if you’re using jQuery):

$(".remove-item").live("click", function() { 
    viewModel.items.remove(ko.dataFor(this));
});

There are two new helper functions that make this possible:

• ko.dataFor(domElement) – returns the data item associated with a particular DOM element
• ko.contextFor(domElement) – returns the entire binding context associated with the DOM element, so you can retrieve its $parent property, etc.

Example:

5. Binding providers (and hence external bindings)

Most KO developers find the default data-bind attributes provide a very convenient, easy-to-maintain way of declaratively associating viewmodels with views. But if you would prefer to store your binding configuration elsewhere, the new binding providers API is an extensiblity point that allows alternative configuration mechanisms to be plugged in.

For example, here’s one possible alternative way that you could configure bindings. Notice the absence of data-bind attributes – I’m using a binding provider to set up the binding configuration in JavaScript:

To be clear, binding providers are a general extensibility mechanism, not any specific configuration format. The above example is just one possible way it can be used to define bindings in JavaScript. I’m looking forward to seeing suggestions from the community about how this extensibility can be used, and for what the most elegant and convenient way of defining bindings might be. I know some of you have already suggested externalising bindings (e.g., Brandon Satrom’s knockout.unobtrusive plugin); this new API will make it easier to implement custom binding mechanisms. Bring on more plugins!

6. Throttling

Occasionally, it’s desirable to limit how fast observables and dependent observables update. For example, you might be using a dependentObservable to invoke Ajax requests whenever a set of observables change. Sometimes you might want to change multiple underlying observables, but only have that dependentObservable re-evaluate once, after all the changes (so that it only fires one Ajax request). Effectively, you want a kind of atomic update.

This is now pretty easy to do: you can apply an extender called "throttle" either to observables or to dependent observables. For example:

// Will not notify changes faster than once per 500ms 
var myObservable = ko.observable("initial value").extend({ throttle: 500 });
 
// Will not re-evaluate *or* notify changes faster than once per 500ms 
var myDependentObservable = ko.dependentObservable(function() { 
    // Evaluation logic goes here, usually referencing other observables 
    return 123;
}).extend({ throttle: 500 });

The way this works is that, when throttled, notifications and evaluations are done asynchronously, and don’t occur at all until they stop being triggered for the specified throttle timeout duration.

In the case of making a dependent observable only update once even if there are multiple synchronous changes to its dependencies, you can use a very short timeout (for example, 1ms), and then it will re-evaluate as soon as possible after any series of synchronous changes to its dependencies. Example:

This is all I have time to write about just now, but there are also some other new extensibility features I haven’t mentioned. I’ll follow up with more as soon as I can.

Backward compatibility notes

This beta version of Knockout 1.3 should work with your existing applications, with the following exceptions:

• It has dropped compatibility with old versions of jquery.tmpl. If you’re using a version of jquery.tmpl older than 1.0.0pre, you’ll need to upgrade. You can find it at https://github.com/jquery/jquery-tmpl.
• The API for registering custom template engines has changed, so any existing custom ones will need to be updated. The change makes it much easier to define custom view engines (you don’t have to worry about "rewriting" any more). I’ll write a separate post about this soon.
• Since the binding algorithm has been enhanced in many ways, any third-party plugins that specifically try to alter how bindings work may not work immediately (for example, the "namespaces" plugin). I’ll be talking to the creators of those plugins to ensure both KO and the plugins are updated to work together properly. Apologies for any inconvenience! The new extensibility APIs should make it much easier to implement these kinds of plugins now anyway.

Please try it out and let me know what you think of the new features!

Since this was a one-person weekend project, I’ve been using all possible means to minimise the total development time. A key part of that has been using existing open source components so I can avoid reinventing stuff wherever possible.

In the end, I was surprised to realise just how many open source projects went into building this single-page application, and how high-quality and easy-to-use most of them were. So, I’d like to give them a bit of recognition by listing them here and giving you a mini-review of each. Maybe you’ll benefit from a few of these in your own projects.

1: Knapsack

Knapsack (NuGet: knapsack) is Andrew Davey’s JavaScript / CSS dependency manager for ASP.NET. It lets you define a series of JS/CSS references like this:

Html.ReferenceScript("Scripts/Lib/knockout-1.3.0.latest.js");
Html.ReferenceScript("Scripts/Custom/bindings.js");
Html.ReferenceScript("Scripts/Custom/appViewModel.js");
Html.ReferenceStylesheet("Content/App/boilerplate.css");
// ... etc ...

… and then emit the actual <script> / <link rel="stylesheet"> tags like this:

@Html.RenderScripts()

What’s the point? Well, in debug mode, it just emits one <script> tag per referenced script, as usual, so you can use your browser’s JavaScript debugger as always. But in release mode, it emits just one <script> tag pointing to a special URL that returns all of the JavaScript code combined into a single file, minified using the MS Ajax Minifier library. So, if you view source on learn.knockoutjs.com, you’ll see only one or two <script> tags even though I’m actually using dozens of JS files.

It also sets all the right cache/etag headers so the browser can avoid making unnecessary HTTP requests, but doesn’t risk using out-of-date scripts because the dynamic script URL changes whenever you change the referenced script files (the URL includes a hash of your JavaScript source code).

I’ve been very happy with knapsack, and would definitely recommend it. The one caveat I discovered is that it automatically references all JavaScript files in any folder that you point it at, which is surprising if you intentionally didn’t reference one of the files in that folder. That aside, if you can organise your JS/CSS files into folders to match how they should be combined, you’ll probably be very happy with Knapsack too.

Note: Knapsack will soon be changing its name to something else due to a cease-and-desist.

2: YamlSerializer

As part of my minimum viable product kind of philosophy for the site, I didn’t create any kind of editor for the tutorials, and I didn’t even store them in a database. The simplest editor is a text editor, and the simplest data store is files on disk. So, the tutorials are written in YAML – a human-editable structured text format.

To parse these YAML files, I used YamlSerializer (NuGet: yamlserializer), a .NET library written by Osamu Takeuchi. So, I have .NET classes like this:

public class Tutorial
{
    public string Title { get; set; }
    public virtual ICollection<tutorialStep> Steps { get; set; }
    // ... various other properties ...
}
 
public class TutorialStep
{
    public string Instructions { get; set; }
    // ... other properties ...
}

… and YAML files like this:

title: Introduction
steps:
 - instructions: |
    ##Welcome!
    Blah blah blah, here's what to do...
 - instructions: |
    ##Doing the next thing
    Do the following things...

… and YamlSerializer parses Tutorial/TutorialStep instances like this:

Dictionary data = new YamlSerializer().Deserialize(allText);
return new Tutorial {
    Title = (string)data["title"],
    Steps = (from stepDict in (Dictionary)data["steps"]
             select new TutorialStep {
                 Instructions = ((string)stepDict["instructions"]).Trim(),
                 // ... other properties ...
             }).ToList(),
    // ... other properties ...
};

It’s maybe not quite as pretty as it could be with a more generics-oriented API (or maybe even a dynamic one?) but it’s robust, fast enough (though I do cache the parsed result), and I had it working in minutes. So I’m satisfied with that!

3: Ninject

I didn’t strictly need to use Dependency Injection in this project, but since it takes exactly 10 seconds to set up thanks to NuGet, I did it anyway. My favourite DI container is Ninject (NuGet: Ninject.MVC3), a very easy-to-configure product from Nate Kohari. The MVC 3 version hooks itself into the MVC 3 Dependency Injection extensibility point automatically (internally, it uses David Ebbo’s WebActivator to make itself run when your app first starts).

In this site, it’s only used to supply ITutorialRepository instances to my one-and-only HomeController. Really I could have just hardcoded the dependency, as there is only one tutorial repository (YamlTutorialRepository), but hey it genuinely did take less than one minute to set up the DI and it made me feel less like I was just hacking things together…

4: CodeMirror

See those lovely in-browser code editors with context-specific syntax highlighting, the ones that even work on IE6? That’s CodeMirror, a JavaScript library from Marijn Haverbeke.

This was not particularly easy to get working just as I wanted – I hit a range of browser-specific performance problems mainly because of my compulsive need to put rounded corners and dropshadows on every element on the page. Nonetheless, it’s a completely vital component, the entire site couldn’t exist without it, and it’s an impressive technical achievement in its own right, so I’m willing it to give it plenty of slack.

The one alternative code editor I tried was Ace – it looks very promising, but had serious layout issues in IE (e.g, if you resize the font). In the future Ace might overtake CodeMirror to become the smartest and best-performing in-browser code editor, but it’s not there yet.

5: Amplify.js

Did you notice that if you work on one of the tutorials, then leave the tutorial (possibly even the whole site), and then later come back, the site will offer to restore your code and your position in that tutorial? How can this be, given that you didn’t even register for an account? It’s HTML 5 local storage, of course.

To implement this, I used Amplify.js (NuGet: amplifyjs), a JavaScript library from appendTo. Of all the JavaScript libraries I used, this one was the easiest to get working. It was completely trivial, in fact – just about three lines of code in total.

Whenever you run your code, the site saves your state:

amplify.store("tutorialState." + tutorial.Id, { view: ..., viewModel: ..., stepIndex: ... });

Similarly, whenever you load a tutorial, the site checks if you have saved state:

var savedState = amplify.store("tutorialState." + id);

… and if so, offers to restore it. The site doesn’t care what browser you’re running, because Amplify.js figures out what local storage options exist and uses whichever one is going to work for you.

6: json2.js

Amplify.js needs your browser to support JSON.stringify, the JavaScript API for serializing an object to JSON. All decent browsers do, but just in case you’re running IE 7 (What kind of web developer are you? Shame on you!), I reference json2.js (NuGet: json2) which provides an implementation of JSON.stringify. Json2.js is the work of legendary JavaScript guru and JSON inventer, Douglas Crockford.

7: Highlight.js

In the tutorial instructions, there are lots of little snippets of code showing you what to do. For the syntax highlighting here, I used highlight.js from Ivan Sagalaev.

There are dozens of code-highlighting JavaScript libraries, and I’ve no reason to say this one is better than the rest. I chose this one simply because it lets me “highlight” a certain DOM element at an arbitrary time of my choosing, and doesn’t get fussy about doing things when the page first loads. Also it tolerates existing HTML markup in the element you’re highlighting, which is how I was able to put special yellow backgrounds on selected bits of code to emphasise the key points.

Highlight.js was pretty easy to work with. I made a Knockout custom binding to display the tutorial steps, and whenever it updates the UI, it highlights any code blocks like this:

$('pre code', element).each(function () {
    hljs.highlightBlock(this, '    ' /* tab = four spaces */)
});

To customise the colour scheme, you just edit its CSS file. Pretty convenient.

8: Showdown.js

I said the tutorials are written in YAML, but that’s just how the .NET objects are represented as text. To represent the actual markup within the instructions (e.g., the headings, links, code blocks, etc.), I used Markdown, a simple text-formatting DSL invented by John Gruber. So I’ve got “markdown” syntax within my YAML files, like this:

 - instructions: |
    ##How to write markdown
    To emphasise text, use *asterisks*. To include a code snippet, just indent it like this:
 
        var blah = "this is some JavaScript"
 
    You can put bits of text into code font `using backtick quotes`.

That markdown text gets sent to the client (in JSON form, of course – so many text-based formats!). To render it as HTML in the browser, I use showdown.js, a Markdown-to-HTML conversion library from John Fraser. This is pretty straightforward – I have a Knockout custom binding like this:

ko.bindingHandlers.markdown = {
    update: function (element, valueAccessor) {
        var markdownValue = ko.utils.unwrapObservable(valueAccessor());
        var htmlValue = markdownValue && new Showdown.converter().makeHtml(markdownValue);
        $(element).html(htmlValue || "");
    }
};

… and then I can bind elements to show markdown data like as follows, and it will refresh the display whenever the markdown text changes:

<div data-bind="markdown: someMarkdownValue"></div>

9: jQuery and friends

Obviously I used jQuery. I won’t bother discussing the core library because everyone knows about that, but I will mention the jQuery plugins I used:

• jQuery UI, not for any of the visual elements, but merely for its “draggable” API. (You can drag to resize the panes, see?). I didn’t need any of its buttons, menus, etc.
• jQuery Impromptu, to display the overlaid prompts (e.g., for choosing a tutorial or for explaining that your code will be overwritten when you click “Help, it’s not working!”). To be honest, this is the only component I regretted using. It’s is probably great if you use it for its intended use case (which includes things like multi-step wizards), but all I wanted was to move an existing DOM element in front of a gray background, lightbox style. jQuery Impromptu tries to do all manner of extra things that that screwed around with my DOM and its default animation was horribly stuttery on Chrome and Safari. In the end, I butchered its source code almost beyond recognition to get the desired behaviour with tolerable performance. It would have been much quicker for me to write my own version from scratch…
• jQuery Templates (used internally by Knockout, and soon to be replaced with JsRender)
• jQuery Address (used internally by knockout.address for the hash-based navigation)

10: … and of course, Knockout.js

Not surprisingly, the UI is all orchestrated with knockout.js (NuGet: knockoutjs), so I have a very tidy MVVM architecture for the client-side code. There are objects to represent each of the major UI elements (panes, draggable splitters, code editors, prompts, etc.), and Knockout takes care of keeping the visible UI in sync with that whole object graph.

But I don’t need to explain this – you can learn much more from the tutorials…

Summary

Building an application by smashing together a lot of different open-source projects is pretty quick. The end result is not always a perfectly harmonious symphony, as each component brings its own coding styles and conventions, but it works.

What I’ve learned about components is kind of predictable: the most useful ones are

• Focused. Just solve one problem, please.
• Self-contained. I’m not going to accept a tall stack of dependencies; it’s too risky.
• Clearly documented. First I want examples, then a systematic list of API functions.
• Available on NuGet

It wasn’t difficult to find components to suit my requirements. It’s great to see the open source ecosystems are thriving, both on .NET and JavaScript.

• Changed the license to MIT (more permissive than the previous license, MS-PL)
• Added useful new bindings: event, attr, html
• Enhanced some existing bindings: options, checked
• Enhanced templating features (now supports jquery.tmpl 1.0.0pre as well as previous versions, template polymorphism, passing additional data via options)
• Various performance improvements (e.g., now precompiles and caches templates, and ensures all data/subscriptions associated with DOM elements are cleaned immediately when those elements are removed) plus bugfixes
• Better compilation style (ensures Closure Compiler no longer adds any extra variables to global namespace)
• Various new extensibility points requested by plugin authors
• Minor syntactical improvements (e.g., added zero-arg constructor for observable arrays)
• All documentation updated to match 1.2.0

Thanks very much to the many people who have contributed ideas, pull requests, bug reports, and support to make this release possible! I’m really enjoying the community that’s growing around this.

Hang on, what’s Knockout.js?

In case you’ve never heard of it, here’s tekmaven’s explaination:

(By the way, for Visual Studio developers: Install-Package knockoutjs)

More specifically, Knockout is a JavaScript library for building rich, responsive user interfaces. It uses automatic dependency tracking and declarative bindings to update your UI whenever your data model changes, letting you cleanly structure your code around the MVVM pattern.

No, that’s just marketing blather… show me something real

OK then, to learn more:

• See the live examples on knockoutjs.com
• See my original introductory post or the tutorial for using it with ASP.NET MVC (note: it works with any other server-side technology too, as it’s just a JavaScript library)
• Get advanced hints and techniques from Ryan Niemeyer’s site, knockmeout.net (special kudos to Ryan, a.k.a. rpn, for his truly amazing support efforts on the forum!)
• Watch this fast-paced introduction presented at MIX 2011:
  
  
  

1. Introduction: Scaffold your ASP.NET MVC 3 project with the MvcScaffolding package
2. Standard usage: Typical use cases and options
3. One-to-Many Relationships
4. Scaffolding Actions and Unit Tests
5. Overriding the T4 templates
6. Creating custom scaffolders
7. This post: Scaffolding custom collections of files

Previously you’ve seen how to modify the output from existing scaffolders (by overriding their T4 templates) and how to create custom scaffolders that take arbitrary parameters and render new templates of their own.

But what if, instead of generating just a single file, you want to generate multiple files that all work together? Well, it’s not surprising that you can do so.

• You can put multiple Add-ProjectItemViaTemplate commands in your PowerShell file. You can generate as many different files, using as many different templates, as you want.
• You can invoke one scaffolder from another. For example your custom scaffolder logic can contain “Scaffold Controller” or “Scaffold View” instructions to generate controllers and views using the built-in logic.

In this final post in the current MvcScaffolding series, I’ll show how some of these ideas can be tied together to build something useful.

Example: An Ajax-powered Controller

I showed an example of doing this in my MvcConf talk (video here) a couple of months ago, when I built a custom ControllerWithAjaxGrid scaffolder. This custom scaffolder produces a controller (obviously), but instead of having the usual index/edit/details/delete views, it just has a single view that contains an Ajax-powered grid from which the user can view, add, edit, and delete records. Videos are hard to reuse code from, so for your convenience I’ll reproduce the code in this blog post.

To see it in action, download the demo project, and then scaffold an Ajax-grid controller for the included StockItem model by executing “Scaffold ControllerWithAjaxGrid StockItem” in the console:

Run the controller by launching the application and navigating to /StockItems:

It uses jqGrid to do all the client-side stuff. By the way, if you’re wondering how to make jqGrid do different things like sorting or filtering, don’t ask me, I have no idea – talk to the experts! Let’s keep this post focused on the scaffolding side of things.

How ControllerWithAjaxGrid Works

I won’t list all the code for ControllerWithAjaxGrid and its template – you can download the runnable demo project for that. As an outline of how it works, ControllerWithAjaxGrid.ps1 contains the following instruction to create the controller itself:

Scaffold MvcScaffolding.Controller $ModelType -Project $Project `
    -CodeLanguage $CodeLanguage -OverrideTemplateFolders $TemplateFolders `
    -NoChildItems -Force:$Force

This inherits all the normal controller-scaffolding logic (e.g., knowing which folder to output the class file into) from MvcScaffolding.Controller, and merely overrides location where the T4 template is found (using –OverrideTemplateFolder). I was then able to put a ControllerWithContext.cs.t4 file in my custom scaffolder’s folder and hence override the code that gets generated. My custom controller template returns JsonResult data to support the Ajax grid. For example, here’s the template for its GetData action:

public JsonResult GridData(int rows, int page)
{
    var count = _context.<#= modelNamePlural #>.Count();
    var pageData = _context.<#= modelNamePlural #>.OrderBy(x => x.<#= Model.PrimaryKey #>).Skip((page - 1) * rows).Take(rows);
    return Json(new {
        page = page,
        records = count,
        rows = pageData,
        total = Math.Ceiling((decimal)count / rows)
    }, JsonRequestBehavior.AllowGet);
}

Similarly, my custom controller doesn’t need all the usual views – it only needs one that contains the JavaScript code to display the grid. I generate that view using a “Scaffold View” command in ControllerWithAjaxGrid.ps1, again using the –OverrideTemplateFolders parameter to make the View scaffolder load the T4 template from ControllerWithAjaxGrid’s folder.

One interesting thing about the view template is that it gets a list of all the properties on your model class:

<# var properties = viewDataType.VisibleMembers().OfType<codeProperty>(); #>

… then later uses this to generate some JavaScript code relating to each property:

<script type="text/javascript">
    jQuery("#ajaxGrid").jqGrid({
        ...
        colNames: [<#= string.Join(", ", properties.Select(prop => "'" + prop.Name + "'")) #>],
        ...
    });
</script>

Finally, my custom controller needs to be sure that there is actually a data context class that it can use for data access. This is easy to arrange: I just put the following command in ControllerWithAjaxGrid.ps1:

Scaffold DbContext $ModelType -DbContextType ((Get-Project $Project).Name + "Context")

You can see I’m using the convention that the data context class should be called ProjectNameContext, but you could change that if you wanted.

For the full code including the T4 templates, download the demo project.

Conclusion

You could use the same techniques to create other custom controller types with different combinations of views, data access classes, and so on.

If you’re unfamiliar with PowerShell then it might take a bit of learning, but once you’ve got a custom scaffolder to suit your project’s requirements, you can commit your /CodeTemplates folder into source control, and then everyone on your team can quickly generate controllers in the style you’ve defined, supplying whatever custom parameters you’ve declared.

For more information about creating custom controllers, see the tutorial in my previous blog post and the list of useful cmdlets for custom scaffolder scripts.