aboutcode.net

Automating Chrome on Windows with JavaScript using Selenium's WebDriverJS

2013-12-02T00:00:00-08:00

To test my web application, I'm using web browser automation. Getting this set up on Windows took a bit of trial and error, so I've documented the process for future reference.

Here's the list of tools you'll need to get up and running:

Java
Selenium
Chromedriver
NodeJS
selenium-webdriver via npm

Installing the tools

Selenium runs on Java, so if you don't it installed yet, download it from http://www.java.com/en/download/manual.jsp.

Check that Java is installed, by running the following from a command prompt:

c:\>java -version

Here's what I get:

C:\Users\andrew>java -version
java version "1.7.0_45"
Java(TM) SE Runtime Environment (build 1.7.0_45-b18)
Java HotSpot(TM) 64-Bit Server VM (build 24.45-b08, mixed mode)

Next, you need to get Selenium. It's enough to simply download the "selenium-server-standalone" jar file from https://code.google.com/p/selenium/downloads/list. At the time of writing, the latest version was selenium-server-standalone-2.37.0.jar.

To allow Selenium to control Chrome, you'll need the "chromedriver", available from here: http://chromedriver.storage.googleapis.com/index.html. At the time of writing, the latest version was 2.7.

Copy the selenium-server-standalone jar file and chromedriver.exe into your project's directory. Open a new command prompt, change to your project directory and then start Selenium with the following command:

c:\myproject>java -jar selenium-server-standalone-2.35.0.jar -Dwebdriver.chrome.driver=chromedriver.exe

The server can be stopped by pressing Ctrl+C.

To run JavaScript-based tests, you'll need to have NodeJS installed. Download the installer from http://nodejs.org/.

Once NodeJS is installed, you can use the Node Package Manager (npm) to install the selenium-webdriver library:

c:\myproject>npm install selenium-webdriver

A basic browser automation script

You can now create JavaScript files that will automate Chrome. Here's a simple script, test.js.

var webdriver = require("selenium-webdriver");

function createDriver() {
    var driver = new webdriver.Builder()
        .usingServer('http://localhost:4444/wd/hub')
        .withCapabilities(webdriver.Capabilities.chrome())
        .build();
    driver.manage().timeouts().setScriptTimeout(10000);
    return driver;
}

var driver = createDriver();
driver.get("http://www.google.com");

driver.getTitle().then(function (title) {
    console.log(title);
});

driver.quit();

Make sure the Selenium server is running. Then run the script at the command prompt, using node:

c:\myproject>node test.js

You will see Chrome open and load the Google home page. It will then quit, and at the command prompt you'll see the page title printed.

Learning more

The WebDriverJS library is documented here: https://code.google.com/p/selenium/wiki/WebDriverJs.

The library makes great use of "Promises" to handle the asynchronous nature of browser automation. So it's essential to read the Understanding the API section.

Saving my sanity with browser-automation testing?!

2013-11-30T00:00:00-08:00

In the rough-and-tumble world of creating a SaaS start-up, I find it all too easy to fall off the automated testing wagon. It starts with a few quick-fixes, hacked in to meet a new customer need and before I know it, all my tests are nasty red, unmaintainable mess! Then comes the dilemma: when do I spend precious feature development time paying down that technical debt?

I need to be pragmatic about how and what I test in my application. What do my customers care about? They need to be able to log in, enter data and view various reports. So a basic set of high-level, browser-automation tests that verify common customer scenarios should be a great start. They'll give me the confidence to push code live, without worrying if it broke something essential!

I'm sure some kind of 80/20 rule applies. 80% of the application's usage can be covered by 20% of the tests. So for now, I'll focus on getting that 20% in place.

I'm on a journey to restore sanity to my application's tests. I'll be blogging here more about what I learn on the way.

The set-up

My web application uses AngularJS. The future of browser-automation testing for this lies with Selenium's WebDriverJS and the Protractor wrapper library.

After a few false starts, and hours spelunking through half-finished documentation and library source code, I've managed to get a working environment for browser-automation tests.

Currently, I'm not using Jasmine, Mocha, or any other test runner. I'm yet to find one that makes WebDriverJS's promise-based approach to async testing feel natural. I don't need fancy BDD DSLs and pretty output reports. For now, it's enough to simply run node my-scenario.js and see no exceptions :)

Here's one of the first scenarios I got working. It tests the login page of the application.

var browserTest = require("../browserTest");
var LoginPage = require("../pages/LoginPage");
var db = require("../utils/db");

// browserTest is a helper that manages creating a WebDriverJS instance and wrapping it with Protractor.
browserTest(function (browser) {
    var loginPage;
    // Set up some basic data in my test database
    db.createSchool("1234567");
    db.createSchoolUser("user@school.com", "1234567");

    // Login with invalid credentials
    loadLoginPage();
    loginPage.setEmailAddress("no@example.com");
    loginPage.setPassword("wrong");
    loginPage.clickLogin();
    loginPage.errorMessage().shouldBe("The email address or password you entered doesn't match our records. Please try again.");

    // Login with valid credentials
    loadLoginPage();
    loginPage.setEmailAddress("user@school.com");
    loginPage.setPassword("password");
    loginPage.clickLogin();
    // Should be redirected to school home page
    browser.getCurrentUrl().shouldBe("http://localhost/school/1234567");

    function loadLoginPage() {
        browser.get("http://localhost");
        loginPage = new LoginPage(browser);
    }
});

UI tests have a tendency to be very brittle. The slightest change to a page can result in every test failing!

To keep my test code clean and maintainable I'm making use of the "Page Object" pattern. This abstracts away the messy business of interacting with the web page, leaving the test code to be a clear expression of a user's intent.

Here's the LoginPage module.

var protractor = require("protractor");

var LoginPage = function (browser) {
    this.browser = browser;
};

LoginPage.prototype = {

    setEmailAddress: function (emailAddress) {
        this.browser.findElement(protractor.By.input("emailAddress")).sendKeys(emailAddress);
    },

    setPassword: function (password) {
        this.browser.findElement(protractor.By.input("password")).sendKeys(password);
    },

    clickLogin: function () {
        this.browser.findElement(protractor.By.tagName("button")).click();
        this.browser.waitForAngular();
    },

    errorMessage: function () {
        return this.browser.findElement(protractor.By.css(".alert")).getText();
    }
};

module.exports = LoginPage;

I'd love to hear about your experiences with browser-automation testing. What handy tools/libraries have you tried? What's tripped you up?

Creating AngularJS controller classes with TypeScript

2013-10-20T00:00:00-07:00

I recently learned of AngularJS's "controller as" syntax. It allows you to define an indentifier for the controller instance that is controlling your view. This means you can then access properties of that controller.

<div ng-controller="ExampleController as example">
    <input type="text" ng-model="example.message" />
</div>

This syntax is an alternative to the controller defining data directly on the scope. It is particularly useful when working with TypeScript or CoffeeScript, which have a nice class syntax. We can define a controller as a class, with properties for the data to display and methods that handle UI events.

Here's an example AngularJS application, written in TypeScript:

And here's the HTML for that application:

Automatic JSON date parsing with AngularJS

2013-07-27T00:00:00-07:00

JSON doesn't have a native date/time data-type. So you're most likely to see dates encoded as strings. A good choice of string format is ISO 8601. It's easy to parse and relatively unambiguous.

However, when it comes to working with dates in JavaScript, it's far better to work with the built-in Date object, instead of strings. Client-side code will need to convert any date strings found in JSON responses into Date objects.

Here's a function that recursively searches the properties of an object, replacing date/time strings with Date objects:

var regexIso8601 = /^(\d{4}|\+\d{6})(?:-(\d{2})(?:-(\d{2})(?:T(\d{2}):(\d{2}):(\d{2})\.(\d{1,})(Z|([\-+])(\d{2}):(\d{2}))?)?)?)?$/;

function convertDateStringsToDates(input) {
    // Ignore things that aren't objects.
    if (typeof input !== "object") return input;

    for (var key in input) {
        if (!input.hasOwnProperty(key)) continue;

        var value = input[key];
        var match;
        // Check for string properties which look like dates.
        if (typeof value === "string" && (match = value.match(regexIso8601))) {
            var milliseconds = Date.parse(match[0])
            if (!isNaN(milliseconds)) {
                input[key] = new Date(milliseconds);
            }
        } else if (typeof value === "object") {
            // Recurse into object
            convertDateStringsToDates(value);
        }
    }
}

Instead of using this function manually each time we make an AJAX call, we'd rather wire it into the default AJAX processing i.e. "set it and forget it". AngularJS makes this easy by using HTTP response interceptors.

First, let's assume we have a basic AngularJS application module:

var app = angular.module("app", []);

We can configure the $httpProvider.defaults by adding our response transformer, so it'll be used everytime an HTTP request is made using the $http service. Note that this is also how Angular is able to parse JSON response strings into objects for us.

app.config(["$httpProvider", function ($httpProvider) {
     $httpProvider.defaults.transformResponse.push(function(responseData){
        convertDateStringsToDates(responseData);
        return responseData;
    });
}]);

We can now make HTTP requests using the $http service and know that any date-strings will have already been converted into Date objects.

app.controller("MyController", ["$scope", "$http", function($scope, $http) {
    $scope.go = function() {
        $http.get("/foo").then(function(response) {
            // date-string properties of `response.data` will now be Date objects.
        };
    };
}]);

Working Demo

Check out the AngularJS $http documentation for more details about transforming HTTP requests and responses.

Twitter Bootstrap control-group directive for AngularJS

2013-07-13T00:00:00-07:00

Twitter Bootstrap makes it easy to create great looking forms. However, you may find yourself repeating the same control-group boilerplate markup.

<div class="control-group">
    <label class="control-label" for="example">Example</label>
    <div class="controls">
        <input type="text" id="example" />
    </div>
</div>

With AngularJS, we can refactor this UI pattern into a directive, and use it like this:

<div control-group label="Example">
    <input type="text" id="example" />
</div>

The directive generates the boilerplate divs and label elements. It then transcludes the input element you provided inside the generated elements.

Here's the basic control-group directive:

var app = angular.module("app", []);

app.directive("controlGroup", function() {
    return {
        template: 
        '<div class="control-group">\
            <label class="control-label" for="{{for}}">{{label}}</label>\
            <div class="controls" ng-transclude></div>\
        </div>',

        replace: true,
        transclude: true,

        scope: {
            label: "@" // Gets the string contents of the `label` attribute.
        },

        link: function (scope, element) {
            // The <label> should have a `for` attribute that links it to the input.
            // Get the `id` attribute from the input element
            // and add it to the scope so our template can access it.
            var id = element.find(":input").attr("id");
            scope.for = id;
        }
    };
});

The directive specifies transclude: true. This means it can use the ng-transclude directive within its template to insert the child elements of the source markup into the <div class="controls"> element.

Validation styling

Bootstrap provides classes to indicate invalid inputs. Adding the error class to the control-group element will make the label, input and other help text red to alert the user to the problem.

Since we are using AngularJS, let's leverage the existing ng-model and form validation behaviors. Here's a simple form with an input data-bound to a scope property. The input also has the required attribute to trigger some basic AngularJS validation.

<form name="form" class="form-horizontal" ng-controller="ExampleController">
    <div control-group label="Example">
        <input type="text" ng-model="data.example" id="example" name="example" required />
    </div>
</form>

Assume the ExampleController is simply initialising the scope.

app.controller("ExampleController", ["$scope", function($scope) {
    $scope.data = {
        example: ""
    };
}]);

To toggle the error class whenever the input is invalid, we can use ng-class directive within the control group template.

…
template: 
'<div class="control-group" ng-class="{ error: isError }">\
    <label class="control-label" for="{{for}}">{{label}}</label>\
    <div class="controls" ng-transclude></div>\
</div>',
…

The directive's link function will need to managed this new isError property. To do this it's need to access the input's validation state, which is kept by the form. Adding the following require property to the directive defintion will give us access to the NgFormController in the link function.

…
replace: true,
transclude: true,
require: "^form", // Tells Angular the control-group must be within a form
…
link: function(scope, element, attrs, formController) {
…

The validation status of an input is stored in the scope like this: scope.{form-name}.{input-name}.$invalid. Note that the form and input elements must have name attributes for this to work.

Our directive definition has scope: { label: "@" }, which means it will create an isolated scope. So the form validation information is actually in the parent scope i.e. scope.$parent…

Here's the updated link function:

…    
link: function(scope, element, attrs, formController) {
    // The <label> should have a `for` attribute that links it to the input.
    // Get the `id` attribute from the input element
    // and add it to the scope so our template can access it.
    var id = element.find(":input").attr("id");
    scope.for = id;

    // Get the `name` attribute of the input
    var inputName = element.find(":input").attr("name");
    // Build the scope expression that contains the validation status.
    // e.g. "form.example.$invalid"
    var errorExpression = [formController.$name, inputName, "$invalid"].join(".");
    // Watch the parent scope, because current scope is isolated.
    scope.$parent.$watch(errorExpression, function(isError) {
        scope.isError = isError;
    });
}
…

Other improvements

If you don't use the input's id attribute anywhere else in your application, then it only exists to link it to the label. You could remove the attribute from your mark-up and make the directive generate a unique ID instead and set it on the input element.

Auto-generated unique IDs are very useful when your UI widgets may be inserted into pages where you can't guarantee uniqueness of manually defined IDs.

Another useful directive I use is to show validation error messages. Here's an example of it in use:

<div control-group label="Example">
    <input type="text" ng-model="data.example" name="example" required/>
    <span validation-error-for="required">This input is required</span>
</div>

It expands into the following mark-up:

<div control-group label="Example">
    <input type="text" ng-model="data.example" name="example" required/>
    <span class="help-inline" ng-show="form.example.$error.required">This input is required</span>
</div>

I'll leave the implementation as an exercise to the reader, or perhaps a future post! ;)

Demo

Here's a JSFiddle with a demo of the code.

eBook Review - Twitter Bootstrap Web Development How-To

2013-01-10T00:00:00-08:00

I was recently given a copy of a Twitter Bootstrap Web Development How-To to review.

The book provides an introduction to Twitter Bootstrap. Its step-by-step style walks the reader through the basics of getting started. You'll learn how to create and customize a variety of different page layouts and enhance these using some of Bootstrap's built-in jQuery plugins.

If you're new to web development and find online documentation a bit terse when learning new libraries, then this book is worth a quick read.

Load images with jQuery Deferred

2013-01-09T00:00:00-08:00

Have you ever needed to know the dimensions of an image in JavaScript? In the past, you may have used code like this:

var image = new Image();
image.onload = function() {
  alert("Loaded image: " + image.width + "x" + image.height);
};
image.src = "/my-image.png";

This is okay for very basic scenarios, but it becomes tricky to handle things like:

Notifying more than one part of your application when the image is loaded
Error handling
Loading multiple images in parallel
Chaining together a sequence of asynchronous operations

I also dislike the backwards nature of writing the callback function before assigning the src property. This is essential however, because image loading is asynchronous and could potentially finish before your callback was assigned to onload.

Fortunately, there is a cleaner way to handle this.

Using jQuery Deferred

The jQuery deferred object is perfect for wrapping up asynchronous operations, such as image loading. The deferred object provides a consistent API for adding callbacks and chaining operations. It results in very readable code.

Here's what it's like to load an image using a jQuery deferred object.

$.loadImage("/my-image.png")
.done(function(image) {
  alert("Loaded image: " + image.width + "x" + image.height);
})
.fail(function(image) {
  alert("Failed to load image");
});

jQuery deferred's are easy to chain together using the pipe function. For example, imagine we need the dimensions of a user's avatar image. But first we need to the image URL from a profile retrieved via ajax...

var avatarDimensions = $.get("/user-profile")
  .pipe(function(profile) {
    return $.loadImage(profile.avatarUrl);
  })
  .pipe(function(avatarImage) {
    return { width: avatarImage.width, height: avatarImage.height };
  });

// avatarDimensions is a deferred object.
avatarDimensions.done(function(dimensions) {
  console.log(dimensions);
});

Implementing $.loadImage

Here's the code for $.loadImage. It assumes you have already included jQuery 1.5 or newer in your page.

$.loadImage = function(url) {
  // Define a "worker" function that should eventually resolve or reject the deferred object.
  var loadImage = function(deferred) {
    var image = new Image();
    
    // Set up event handlers to know when the image has loaded
    // or fails to load due to an error or abort.
    image.onload = loaded;
    image.onerror = errored; // URL returns 404, etc
    image.onabort = errored; // IE may call this if user clicks "Stop"
    
    // Setting the src property begins loading the image.
    image.src = url;
    
    function loaded() {
      unbindEvents();
      // Calling resolve means the image loaded sucessfully and is ready to use.
      deferred.resolve(image);
    }
    function errored() {
      unbindEvents();
      // Calling reject means we failed to load the image (e.g. 404, server offline, etc).
      deferred.reject(image);
    }
    function unbindEvents() {
      // Ensures the event callbacks only get called once.
      image.onload = null;
      image.onerror = null;
      image.onabort = null;
    }
  };
  
  // Create the deferred object that will contain the loaded image.
  // We don't want callers to have access to the resolve() and reject() methods, 
  // so convert to "read-only" by calling `promise()`.
  return $.Deferred(loadImage).promise();
};

Google Chrome extensions using KnockoutJS

2013-01-06T00:00:00-08:00

Attempting to use KnockoutJS within a Google Chrome extension will swiftly result in the following error message.

Uncaught Error: Unable to parse bindings.
Message: Error: Code generation from strings disallowed for this context;

This is due to Chrome's Content Security Policy for extensions. Essentially, it blocks the use of eval and new Function, which means features like Knockout's template engine and data-bindings won't work.

Sandboxing your application

The solution to using KnockoutJS in a Google Chrome extension is to sandbox the extension's HTML page and javascript. This isolates them from the rest of the extension and allows the use of previously restricted features.

To sandbox an HTML page, we need to mention it in the extension's manifest.json file. Here's an example manifest that sandboxes a file named app.html.

{
  "name": "Knockout Chrome Extension",
  "version": "0.1",
  "manifest_version": 2,
  "description": "An example extension that uses KnockoutJS",
  "sandbox": {
    "pages": ["app.html"]
  },
  ...
}

The app.html page can now reference knockout.js and your other scripts. These referenced files are then also sandboxed. However, it can no longer be loaded directly into your extension's browser action pop-up, or be displayed in a tab.

Loading the sandboxed application

A sandboxed HTML page needs to be loaded from a non-sandboxed page, using an <iframe>.

For example, the extension can have a browser action pop-up, specified by the following part of the manifest.json:

{
  ...
  "browser_action": {
    "default_popup": "popup.html",
    "default_title": "Knockout Chrome Extension",
    "default_icon": {
      "19": "icon19.png",
      "38": "icon38.png"
    }
  },
  ...
}

The popup.html page serves as a container for the sandboxed application page.

<!DOCTYPE html>
<html>
  <head>
    <script src="popup.js"></script>
  <head>
  <body style="padding: 0">
    <iframe src="app.html" id="app" seamless></iframe>
  <body>
<html>

Note the handy HTML5 seamless attribute on the <iframe> tag. This removes all borders and scrollbars.

Communicating with the application

Anything loaded by a sandboxed page, such as scripts, are also sandboxed. This means your application script won't be able to use any of the Chrome APIs.

Scripts loaded by the un-sandboxed popup.html do have access to the Chrome APIs. Therefore, if your application needs to interact with Chrome, it has to get the un-sandboxed script to do so.

To communicate between sandboxed and un-sandboxed windows, you have to use messages.

Here's a snippet from popup.js, loaded by popup.html, which calls a Chrome API and then posts a message to the application.

var appWindow = document.getElementById("app").contentWindow;
chrome.topSites.get(function(topSites) {
  appWindow.postMessage({ displayLinks: topSites }, "*");
});

MDN has great documentation about the window.postMessage method.

In the application script, we can listen for this message:

var app = {
  links: ko.observableArray()
};

window.addEventListener(
  "message",
  function(event) {
    if (event.data.displayLinks) {
      app.links(event.data.displayLinks);
    }
  },
  false
);

ko.applyBindings(app);

Similarly, the application can post messages to the un-sandboxed script via the parent window property. For example:

window.parent.postMessage({ example: true }, "*")

Full sample code

To get the full sample code for a simple extension that uses KnockoutJS, join my web development mailing list. I'll give you access to a GitHub repository containing code samples, which you can copy and use in your own projects.

Twitter Bootstrap Modals and Knockout.js

2012-11-15T00:00:00-08:00

Displaying modal dialog boxes directly from your Knockout view models turns your application into unmaintainable jQuery spaghetti. Your once clean view model, is now fighting with the DOM and dragging you into callback hell.

Imagine instead maintaining a clear separation of concerns between your view models and your UI. Views models only need to collaborate with other view models, never with the DOM.

Keep your code clean and elegant - just like your application!

What you'll learn

This post will teach you how to use Twitter Bootstrap modals in a Knockout.js application, while keeping your code clean and simple.

You'll learn how to use Knockout's built-in function, ko.renderTemplate, to generate a modal dialog box UI, on-demand, from a template.

This post will also show how jQuery's Deferred object can neatly manage the asynchronous nature of displaying a modal dialog and waiting for its result.

View model flow

In this post, we'll be discussing the interaction between an application's root view model, which is data-bound to the page, and a separate view model, data-bound to a modal dialog.

The flow of interaction when displaying a modal is shown below.

The viewmodel/view interaction of a modal dialog

Twitter Bootstrap Modal

Twitter Bootstrap provides a very nice looking modal component. However, using the simple $.fn.modal jQuery plugin directly from a Knockout view model can result in DOM code creeping in where it doesn't belong.

The Bootstrap modal plugin requires there to be an element in the page which it will display as a modal dialog. This element will look something like the following:

Screenshot of the modal dialog

This UI is created by the following HTML.

<div class="modal hide fade">
    <div class="modal-header">
        <button type="button" class="close" aria-hidden="true" data-bind="click: cancel">&times;</button>
        <h3>Add Note</h3>
    </div>
    <div class="modal-body">
        <form action="#" data-bind="submit: add">
            <div class="control-group">
                <label class="control-label">New note:</label>
                <div class="controls">
                    <textarea data-bind="value: text"></textarea>
                </div>
            </div>
            <div class="control-group">
                <div class="controls">
                    <label class="checkbox"><input type="checkbox" data-bind="checked: important" />Important</label>
                </div>
            </div>
        </form>
    </div>
    <div class="modal-footer">
        <a href="#" class="btn btn-primary" data-bind="click: add">Add Note</a>
        <a href="#" class="btn" data-bind="click: cancel">Cancel</a>
    </div>
</div>

We need a way to dynamically generate this HTML at runtime and also data bind it to a separate view model. Luckily Knockout provides ko.renderTemplate to do exactly this.

Rendering modal templates

ko.renderTemplate accepts five arguments:

templateName	The ID of the template to render
viewModel	The view model to data bind to the template
options	Additional options passed to the rendering engine. We'll be providing an `afterRender` callback here.
target	Where to render the template, such as a `<div>` element.
renderMode	When this is `"replaceNode"` the target element is replaced with the rendered output.

The rendered elements do not necessarily appear in the DOM immediately. We have to provide an afterRender callback function via the options argument.

ko.renderTemplate(
    "mytemplate",
    viewModel,
    {
        afterRender: function(renderedElement) {
            console.log("rendered!");
        }
    },
    target,
    "replaceNode"
);

Let's wrap up this complexity in helper function that returns a jQuery Deferred. This will make it easy to chain together rendering of templates with code that uses the output.

var createModalElement = function(templateName, viewModel) {
    var temporaryDiv = addHiddenDivToBody();
    var deferredElement = $.Deferred();
    ko.renderTemplate(
        templateName,
        viewModel,
        // We need to know when the template has been rendered,
        // so we can get the resulting DOM element.
        // The resolve function receives the element.
        {
            afterRender: function (nodes) {
                // Ignore any #text nodes before and after the modal element.
                var elements = nodes.filter(function(node) {
                     return node.nodeType === 1; // Element
                });
                deferredElement.resolve(elements[0]);
            }
        },
        // The temporary div will get replaced by the rendered template output.
        temporaryDiv,
        "replaceNode"
    );
    // Return the deferred DOM element so callers can wait until it's ready for use.
    return deferredElement;
};

var addHiddenDivToBody = function() {
    var div = document.createElement("div");
    div.style.display = "none";
    document.body.appendChild(div);
    return div;
};

The view models

An application view model will be responsible for initiating the display of a modal. It will create a separate view model object for the modal and call a helper function to show the modal.

Here's a simple application view model that shows a modal:

var AppViewModel = function() {
    this.notes = ko.observableArray();
};

AppViewModel.prototype.addNote = function() {
    showModal({
        viewModel: new AddNoteViewModel(),
        context: this // Set context so we don't need to bind the callback function
    }).then(this._addNoteToNotes);
};

AppViewModel.prototype._addNoteToNotes = function(newNote) {
    this.notes.push(newNote);
};

This view model provides a method that can be bound to the click event of a button or link. It shows the modal dialog UI, which is data-bound to the given view model. Then it waits for the modal to be closed with some result data.

We'll dive into the showModal function soon. For now, note that it is returning deferred object that is resolved when the modal has been closed. The modal is able to pass back a result, which in this case the application view model is adding to its notes array.

Here's the AddNoteViewModel, which will be data bound to the modal UI:

var AddNoteViewModel = function() {
    this.text = ko.observable();
    this.important = ko.observable();
};
    
// The name of the template to render
AddNoteViewModel.prototype.template = "AddNote";

AddNoteViewModel.prototype.add = function () {
    var newNote = {
        text: this.text(),
        important: this.important()
    };
    // Close the modal, passing the new note object as the result data.
    this.modal.close(newNote);
};

AddNoteViewModel.prototype.cancel = function () {
    // Close the modal without passing any result data.
    this.modal.close();
};

The AddNoteViewModel provides the name of the template to render. This will be used by the showModal function.

The view model is also in control of when to close the modal. It assumes that a modal property has been attached to itself. This object contains a close method that is used to close the modal and optionally pass a result.

The `showModal` function

Here's the showModal function:

var showModal = function(options) {
    if (typeof options === "undefined") throw new Error("An options argument is required.");
    if (typeof options.viewModel !== "object") throw new Error("options.viewModel is required.");

    var viewModel = options.viewModel;
    var template = options.template || viewModel.template;
    var context = options.context;
        
    if (!template) throw new Error("options.template or options.viewModel.template is required.");
        
    return createModalElement(template, viewModel)
        .pipe($) // jQueryify the DOM element
        .pipe(function($ui) {
            var deferredModalResult = $.Deferred();
            addModalHelperToViewModel(viewModel, deferredModalResult, context);
            showTwitterBootstrapModal($ui);
            whenModalResultCompleteThenHideUI(deferredModalResult, $ui);
            whenUIHiddenThenRemoveUI($ui);
            return deferredModalResult;
        });
};

After some standard pre-condition validation, the function starts the process of showing the modal. The pipe method provides a nice way to chain together a set of deferred operations.

First, the modal element creation is started. Once Knockout has finished updating the DOM, the next operation in the pipeline runs.

The call to pipe($) is equivalent to:

pipe(function(modalElement) {
    return $(modalElement);
})

Because this returns a non-deferred value, the next stage of the pipeline executes immediately after.

The final stage of the pipline creates a new deferred object that will contain the result of the modal when it is closed. A helper object is attached to the view model so it is able to close the modal.

var addModalHelperToViewModel = function (viewModel, deferredModalResult, context) {
    // Provide a way for the viewModel to close the modal and pass back a result.
    viewModel.modal = {
        close: function (result) {
            if (typeof result !== "undefined") {
                deferredModalResult.resolveWith(context, [result]);
            } else {
                // When result is undefined, we don't want any `done` callbacks of
                // the deferred being called. So reject instead of resolve.
                deferredModalResult.rejectWith(context, []);
            }
        }
    };
};

The deferred object's resolveWith method is used to provide a useful value for this in any callback functions. The context value was provided to the showModal function via its options argument.

The signature of resolveWith is similar to Function.prototype.apply i.e. the arguments must be passed as an array.

Sometimes a user will need to cancel a modal. To handle this case, close can be called with an undefined result. The deferred modal result is then rejected, instead of resolved. This means that the "happy path" in the application view model doesn't need to check for a cancelled modal. Cancelling can be detected by providing a fail callback instead.

showModal({ viewModel: new ModalViewModel() })
    .done(function(result) {
        console.log("Modal closed with result: " + result);
    })
    .fail(function() {
        console.log("Modal cancelled");
    });

The remaining helper functions called by showModal are listed below:

var showTwitterBootstrapModal = function($ui) {
    // Display the modal UI using Twitter Bootstrap's modal plug-in.
    $ui.modal({
        // Clicking the backdrop, or pressing Escape, shouldn't automatically close the modal by default.
        // The view model should remain in control of when to close.
        backdrop: "static",
        keyboard: false
    });
};
    
var whenModalResultCompleteThenHideUI = function (deferredModalResult, $ui) {
    // When modal is closed (with or without a result)
    // Then always hide the UI.
    deferredModalResult.always(function () {
        $ui.modal("hide");
    });
};

var whenUIHiddenThenRemoveUI = function($ui) {
    // Hiding the modal can result in an animation.
    // The `hidden` event is raised after the animation finishes,
    // so this is the right time to remove the UI element.
    $ui.on("hidden", function() {
        // Call ko.cleanNode before removal to prevent memory leaks.
        $ui.each(function (index, element) { ko.cleanNode(element); });
        $ui.remove();
    });
};

When a modal is closed, it is removed from the DOM to free up memory. However, Twitter Bootstrap modal's hide method will animate the hiding. Instant removal would prevent this nice effect.

A two-step approach is used to remove the modal once the deferred result has been resolved or rejected. The Bootstrap modal "hide" method is called. This will raise the "hidden" event once the animation has finished. At that point we can remove the modal's DOM element.

Extensions and ideas

The use of ko.renderTemplate to dynamically generate UI can be generalised for other components. For example, Twitter Bootstrap Popovers.

Occasionally one modal will need to display another modal. There are two possible flows to consider:

Close the first modal, then show the second.
Stack the second modal on top of the first.

In the first case, the modal's deferred result object must be passed onto the second modal. The application view model shouldn't resume until the second modal has been closed.

The modal helper object assigned to view models could be extended to support this scenario. Here's a possible API:

FirstViewModel.prototype.showSecond = function() {
    this.modal.closeCurrentAndShowModal(new SecondViewModel());
    // The first modal is now removed from the DOM.
};

The second case is somewhat simpler. A separate deferred result object is created for the second modal. The first modal remains in the background, ready handle the result when the second modal is closed.

Again, the modal helper object could be enhanced to support this behavior:

FirstViewModel.prototype.showSecond = function() {
    this.modal.showNestedModal(new SecondViewModel());
    // The first modal is still loaded, but hidden until the second is closed.
};

To prevent Twitter Bootstrap adding multiple backdrop overlays to the page, the first modal could be hidden, but not removed, while the second modal is displayed.

Full sample code

To get the full sample code that accompanies this blog post, join my web development mailing list. I'll give you access to a private GitHub repository containing code samples, which you can copy and use in your own projects.

Thanks for reading

I hope you found this post useful. Let me know in the comments, or on twitter @andrewdavey. Feel free to copy, modify and use the code in your applications.

Zero Configuration Asp Net Modules And Handlers

2012-01-15T00:00:00-08:00

--- title: Zero-configuration ASP.NET modules and handlers layout: post ---

A couple of my open source projects, Cassette and Not Found MVC, add custom HTTP handlers and modules to the host application. Cassette, for example, can return bundled assets from a route added to the ASP.NET RouteTable. It does this without requiring any additions to Web.config or Application_Start in Global.asax.

Removing the requirement of editing configuration or adding initialization code makes it simpler to use a library. A developer can just reference the library and they're ready to go.

Achieving this simplicity requires two handy libraries, called WebActivator and Microsoft.Web.Infrastructure. Both are available via Nuget.

Using WebActivator's PreApplicationStartMethod attribute we can provide a method to run very early in the web application's start up process. The method can use DynamicModuleUtility, from the Microsoft.Web.Infrastructure assembly, to register HTTP modules.

[assembly: WebActivator.PreApplicationStartMethod( typeof(Example.StartUp), "PreApplicationStart")]
namespace Example
{
    public static class StartUp
    {
        public static void PreApplicationStart()
        {
            DynamicModuleUtility.RegisterModule(typeof(MyHttpModule));
        }
    }
}

HTTP modules are useful for adding functionality that applies to all requests. For example, Cassette uses an HTTP module to rewrite HTML output of pages. However, if you want to handle your own custom URLs you need to create an HTTP handler hooked up via the ASP.NET routing system.

Adding custom routes needs to happen after the application itself has finished starting up. It's too early to add routes in the PreApplicationStartMethod. Instead, use the PostApplicationStartMethod attribute also provided by WebActivator.

The method specified in PostApplicationStartMethod is run after the web application's Application_Start method. It's the ideal place to modify the route table.

This is the attribute:

[assembly: WebActivator.PostApplicationStartMethod( typeof(Example.StartUp), "PostApplicationStart")]

And here's the method added to the StartUp class:

public static void PostApplicationStart()
{
    var route = new Route("my/url", new MyRouteHandler());
    // Insert route at front of route list to avoid conflicts with application routes.
    RouteTable.Routes.Insert(0, route);
}

The application will have already defined its own routes, so we need to ensure our library's routes don't conflict. For example, the application's "{controller}/{action}" route would capture something like "my/url". So if our library needs to handle that specific URL, then its route must be first in the route table.

Another precaution you can take is to constrain your route to only match incoming requests. The routing table is also used to generate URLs, so you may need to guard against unintended matches. Here's an example constraint:

class OnlyMatchIncomingRequestsConstraint : IRouteConstraint
{
    public bool Match(HttpContextBase httpContext, Route route, string parameterName, RouteValueDictionary values, RouteDirection routeDirection)
    {
        return routeDirection == RouteDirection.IncomingRequest;
    }
}

Use it like this:

var route = new Route(
    "my/url",
    new RouteValueDictionary(),
    new RouteValueDictionary(new { incoming = new OnlyMatchIncomingRequestsConstraint() }),
    new MyRouteHandler()
);

See these techniques in action in the source code of Cassette and NotFoundMVC over on GitHub:

Have you seen any other cool uses of WebActivator out there? Let me know in the comments!

Testing Temp Directory

2011-10-26T00:00:00-07:00

--- layout: post title: Testing with a Temporary Directory ---

When testing a class that interacts with the file system, it’s useful to have a clean “temp” directory. We don’t want old files lying around, which could randomly break later tests.

The System.IO.Path class has a static method GetTempPath. This returns the path of the system’s temporary folder. Rather than work directly in the temp directory, we can create a new, uniquely named, directory for each test. This makes cleaning up after the test easy – simply delete the directory.

This repeated pattern of using a temporary directory can be encapsulated into a simple class.

class TempDirectory : IDisposable
{
    public TempDirectory()
    {
        path = Path.Combine(
            Path.GetTempPath(),
            Guid.NewGuid().ToString()
        );
        Directory.CreateDirectory(path);
    }

    readonly string path;

    /// 
    /// Allows the TempDirectory to be used anywhere a string is required.
    /// 
    public static implicit operator string(TempDirectory directory)
    {
        return directory.path;
    }

    public override string ToString()
    {
        return path;
    }

    public void Dispose()
    {
        Directory.Delete(path, true);
    }
}

Here’s a simple test using the TempDirectory class:

[Test]
public void SimpleTest()
{
    using (var temp = new TempDirectory())
    {
        // Temp directory is used as a string...
        File.WriteAllText(Path.Combine(temp, "file.txt"), "hello");
        var widget = new FileWidget(temp);
        widget.Load("file.txt");
        Assert.AreEqual("hello", widget.Title);
    }
}

The TempDirectory creates a new, uniquely named, temporary directory. The class is disposable, so can be used in a using statement. This ensures the directory is deleted, even if the test code throws an unhandled exception.

The implicit cast to string operator allows us to use the TempDirectory as if it were a string. When passing it as a string argument, the full path to the directory is used.

This simple class could also be extended with methods that allow you to quickly set up temporary files as well.

P.S. Obviously it’s a good idea to avoid spreading file I/O throughout all your objects! However, there will always be some point where performing real I/O is appropriate. I hope this simple class proves useful for testing those objects.

Efficient Encapsulation Of Javascript Objects

2011-10-04T00:00:00-07:00

--- layout: post title: Efficient Encapsulation of JavaScript Objects ---

Encapsulation is one of the most important principles of object oriented programming. Ideally, an object exposes a limited public interface and keeps its data and implementation details private.

JavaScript does not provide a built-in way to manage the visibility of an object’s members. However its flexibility does allow us to recreate encapsulation. A common approach is to use a function that contains the private data and functions, and then return a limited set of public functions that can interact with the private data.

var Customer = function(id) {
    var totalSpend = 0;

    function isSpecial() {
        return totalSpend > 100;
    }

    return {
        placeOrder: function(order) {
            totalSpend += order.total;
        },
        getReward: function() {
            if (isSpecial()) {
                return "Special Customer Coupon!";
            } else {
                return "Nothing Today";
            }
        },
        toString: function() {
            return "Customer #" + id;
        }
    };
};

This approach is valid, but not necessarily that efficient when creating lots of objects. Every time an object is created, all its functions and created as well. This takes time, and perhaps more importantly, memory. If you’re script is running on a mobile device then resources can be limited. Also, server-side JavaScript running in NodeJS could be creating many thousands of objects.

JavaScript provides the prototype model of inheritance to solve this problem. A single prototype object can contain the functions. Then any objects that have that prototype can share them without any extra overhead.

The following code demonstrates the common pattern of defining a prototype.

var Customer = function(id) {
    this.id = id;
    this.totalSpend = 0;
};
Customer.prototype.placeOrder = function(order) {
    totalSpend += order.total;
};
Customer.prototype.getReward = function() {
    if (isSpecial()) {
        return "Special Customer Coupon!";
    } else {
        return "Nothing Today";
    }
};
Customer.prototype.toString = function() {
    return "Customer #" + id;
};
Customer.prototype.isSpecial = function() {
    return totalSpend > 100;
};

While this code is more efficient, we have lost the ability to encapsulate any data and private functions. Anyone creating a Customer object can directly access the totalSpend property.

A possible workaround is to rely on a convention of, for example, prefixing all non-public members with an underscore. Personally, I dislike this. It adds syntactic noise to the code and doesn’t discourage wayward developers from using objects in ways they shouldn’t!

Therefore I created an alternative solution. It combines the efficiency of prototypes, with the principles of encapsulation. Here’s a quick example of defining a class:

var Customer = defineClass({
    "constructor": function(id) {
        this.id = id;
        this.totalSpend = 0;
    },
    "public": {
        placeOrder: function(order) {
            this.totalSpend += order.total;
        },
        getReward: function() {
            if (this.isSpecial()) {
                return "Special Customer Coupon!";
            } else {
                return "Nothing Today";
            }
        },
        toString: function() {
            return "Customer #" + this.id;
        }
    },
    "private": {
        isSpecial: function() {
            return this.totalSpend > 100;
        }
    }
});

The defineClass function accepts an object literal which contains the constructor, the public functions and private functions. Within functions, the "this" keyword works as normal, allowing storage of data in the object. All the object’s functions, public and private, can call each other.

Let’s examine the use of an instance of the object.

var customer = new Customer(123);
console.log( customer.toString() ); // > "Customer #123"
customer.placeOrder( { total: 10 } );
console.log( customer.getReward() ); // > "Nothing Today"
customer.placeOrder( { total: 101 } );
console.log( customer.getReward() ); // > "Special Customer Coupon!"

So what happens if we try to access the private members of the object?

var customer = new Customer(123);
customer.totalSpend = 1000;
console.log( customer.getReward() ); // > "Nothing Today"
console.log( typeof customer.isSpecial ); // > "undefined"

Any attempt to use the private data or functions fails. The actual object we’re using doesn't have those private members.

Annotated source for defineClass

The source code for defineClass is annotated with comments to explain the trickier details. It’s less than 100 lines and is probably easier to read, than explain it again here.

var defineClass = (function() {

    // Creates a proxying function that will call the real object.
    function createProxyFunction(functionName) {
        return function() {
            // 'this' in here is the proxy object.
            var realObject = this.__realObject__,
                realFunction = realObject[functionName];

            // Call the real function on the real object, passing any arguments we received.
            return realFunction.apply(realObject, arguments);
        };
    };

    // createProxyClass creates a function that will create Proxy objects.
    //   publicFunctions: an object of public functions for the proxy.
    function createProxyClass(publicFunctions) {
        var ProxyClass, functionName, func;

        // This is this Proxy object constructor.
        ProxyClass = function (realObject) {
            // Choose a reasonably obscure name for the real object property.
            // It should avoid any conflict with the public function names.
            // Also any code being naughty by using this property is quickly spotted!
            this.__realObject__ = realObject;
        };

        // Create a proxy function for each of the public functions.
        for (functionName in publicFunctions) {
            func = publicFunctions[functionName];
            // We only want functions that are defined directly on the publicFunctions object.
            if (publicFunctions.hasOwnProperty(functionName) &&
                typeof func === "function") {
                ProxyClass.prototype[functionName] = createProxyFunction(functionName);
            }
        }

        return ProxyClass;
    }

    function copyToPrototype(source, destination) {
        var prototype = destination.prototype,
            property;
        for (property in source) {
            if (source.hasOwnProperty(property)) {
                prototype[property] = source[property];
            }
        }
    };

    function createRealClass(constructor, publics, privates, proxyClass) {
        var RealClass = function () {
            var proxy;

            if (typeof constructor === "function") {
                // Call the constructor function to perform any initialization of the object.
                constructor.apply(this, arguments);
            }
            proxy = new proxyClass(this);
            // Maintain the illusion that the proxy object is a real object.
            // Assign the constructor property in case anyone uses it to create another instance.
            proxy.constructor = RealClass;
            // Returning the proxy object means creating a new instance of Class
            // results in a proxy object, instead of the real object.
            // Callers can then only interact with the proxy.
            return proxy;
        };
        // The RealClass has both public and private functions.
        copyToPrototype(publics || {}, RealClass);
        copyToPrototype(privates || {}, RealClass);

        return RealClass;
    }

    // Return the defineClass function.
    return function (options) {
        // 'public' and 'private' are reserved keywords, so the option properties must be 
        // accessed using strings instead of options.public, for example.
        var proxyClass = createProxyClass(options["public"]),
            realClass = createRealClass(
                options["constructor"],
                options["public"],
                options["private"],
                proxyClass
            );
        return realClass;
    };

}());

Proxy Object

The key to how defineClass works lies with the "proxy" object pattern. A cute trick of JavaScript is that an object constructor function may return a different object, other than the one being constructed. So when creating a new Customer object, you actually get a CustomerProxy object. The real Customer object is hidden within the proxy.

To protect the real object from unwanted external manipulation, a proxy object is created to only expose the public functions. This proxy object has a single property that references the real object. Any call to a function of the proxy object is passed back to the real object.

This does provide a way to circumvent the proxy, by directly using the real object property. However, choosing a suitable name for the property will clearly highlight any calling code that is doing something questionable.

In addition, it is sometimes necessary to violate encapsulation. A common case is for serialization, which requires access to the private data of an object. It’s therefore useful to have an "escape valve".

Extensions

The approach given here could be extended to support inheritance and mixins.

Feel free to use the code and extend it for your own purposes.

Dear ASP.NET, we need to talk about JavaScript

2011-06-19T00:00:00-07:00

Dear ASP.NET,

I only began to enjoy web development with you once MVC came along. Thank you for getting me into the wonderful world of the web. However, the more I develop rich web applications, the more I see gaps in your tooling and libraries. Your server-side development story is excellent, but client-side (in browser) is weak.

Having now built a few JavaScript heavy, rich interactive web applications with .NET, I can tell you that you are lacking in some key areas. Therefore, I’m (not so humbly) going to make some observations and feature requests.

JavaScript

Visual Studio needs a JavaScript project type. If I’m building a complex jQuery plugin, Node.JS application or anything else involving more than one JavaScript file, then rolling my own build system is tedious.

You already have an excellent Visual Studio language service for JavaScript. The intellisense tricks you’re pulling off are fantastic. Capitalise on this by adding a project type.

I want File > New JavaScript Project.

The result of Release building a JavaScript project should be a concatenated, minified version of all the scripts. You will need to determine the file dependency ordering (take a look at Knapsack). You already have the Ajax Minifier library, so reuse this.

Allow the Web Application Project types to link to a JavaScript project to get the scripts. This could be similar to how Silverlight projects link to Web Application projects.

Also, build in support for JSLint and display red squiggles in my code when I’m writing poor JavaScript.

CoffeeScript

Get on the CoffeeScript bandwagon as soon as possible! Rails already has. CoffeeScript makes writing JavaScript faster and easier to maintain. It’s a fantastic language.

I need Visual Studio support for CoffeeScript i.e. syntax highlighting, intellisense and a project type. I’ll also need to mix JavaScript and CoffeeScript in the same project because of existing libraries like jQuery.

The existing CoffeeScript compiler runs in JavaScript. So either, get your own DLR-based, JavaScript engine or (even better) support IronJS or Jurassic. Alternatively, write a new compiler in C#.

HTML Templates

Client-side web applications require HTML templating. jQuery.tmpl is very nice and works well with Steve Sanderson’s KnockoutJS. However, the current approach of “stuff a bunch of template containing script tags into the page” does not scale well with projects having hundreds of templates.

Making the browser parse and code-generate the templates into JavaScript on every page feels like a huge waste of time. This needs to be done server-side or even at build time. The final JavaScript functions should be deployed just like any other script files.

The key to solving this problem is Razor.

Razor totally nails HTML templating. We should be using it for both server and client-side templates. The same templates could even be reusable on both sides.

You just need to add JavaScript and (please, please, please) CoffeeScript support to the Razor parser. CoffeeScript will be an especially nice language to write Razor templates in. For example, it has a much cleaner, C#-style, “for each” than raw JavaScript.

Implementing this requires a managed JavaScript engine. Again, something like IronJS/Jurassic can be used.

Server-side, the Razor views run on the DLR and work just like any other MVC view.

For the client-side, send down the JavaScript generated from the Razor compiler.

Client-side Asset Management

Scripts, style sheets, images and HTML templates are the client-side assets of a web application. The current ASP.NET story for these is “stuff them into folders and deploy”. This is not good enough!

Combining, minification, versioning, compression and caching, all matter for production deployment. We need a solution that handles all that, whilst still maintaining an excellent debug-time experience. Stepping into a 10,000 line, minified, script is no fun at all!

I have already started to explore the solutions to these problems in my Knapsack project. For example, Knapsack determines the dependency order of JavaScript files based on the XML reference comments. Much more needs to be done, but please take a look and either get involved or even steal ideas!

I just want a solution. I need to get back to writing web applications with .NET. Creating tools, frameworks and build processes is your job.

Best regards,

Andrew Davey
- a passionate .NET open source developer -

P.S. Put Steve Sanderson in charge of all this :) I think he really gets ASP.NET, JavaScript and open source.

P.P.S. While this is an open letter to ASP.NET, I really would love to hear the entire community's thoughts on the issues raised here.

Either comment here, or heckle me on Twitter @andrewdavey.

Knapsack - Automatic JavaScript and stylesheet dependency management for ASP.NET

2011-05-15T00:00:00-07:00

Are you wasting time correctly ordering, concatenating and minifying your JavaScript? How about debugging that 10,000 line minified script? Knapsack solves all these problems. It's easy to install (via nuget) and provides some fun extras, like CoffeeScript support!

Knapsack is a new open source project. It's an answer to my previous rant about managing JavaScript in an ASP.NET web application.

Say goodbye to maintaining JavaScript build files - Knapsack determines the correct order of files.

In debug-mode, Knapsack lets you debug against the original scripts. In production-mode, minified, cache-friendly, script modules are generated instead. This is config controlled, so not a single source change is needed.

Head over the the project home page aboutcode.net/knapsack to get started with Knapsack.

Managing JavaScript

2011-04-12T00:00:00-07:00

When it comes to writing rich web applications there is no escaping piles of JavaScript. I've come to quite like the language. However, managing hundreds of JS files is starting to get a bit annoying. In a large application there will be:

Third-party libraries, such as jQuery, knockout, backbone, ES5 polyfills, etc
Shared scripts used by all parts of the application
Collections of files for each "area" of the application
Custom scripts for single pages

I expect to see a lot of JavaScript files in a well written project. As tempting as it is to stuff function after function into one poor file, please don't! Favour many smaller files that are scope limited and easy to understand.

Working with JavaScript this way during development is very much at odds with production requirements. I like to keep each source file separate for sane debugging sessions. However, when deploying to production I want the scripts concatenated and minified into as few files as possible.

Scripts files can depend on other script files. This means the order that scripts are loaded into a page matters.

Existing Solutions

I've used Chirpy in the past to build collections of JS files into logical units. However, this approach means I lose the one-to-one mapping of my original files. What's worse is that I have to manually maintain an XML file listing all the JS source files to build. This is tedious and feels like something the computer should do for me.

Another alternative is SquishIt. SquishIt handles the dev-time vs. production experience nicely by outputting each source script tag when in debug mode. In release mode, a single minified script file is generated instead.

Unfortunately, SquishIt still requires each source file to be listed in the relevant order.

What I want to see

Let's get rid of manually listing all our source scripts for the purposes of concentration and minification. Instead move the intent closer to the actual scripts themselves.

If I have a script that depends on another script then let's declare that in the depending script. Visual Studio provides a special XML comment syntax to do exactly this:

/// <reference path="myother.js"/>
MyOtherFunction(1,2,3);

Documenting my dependencies this way will save my sanity when I come back to this code in a years' time. Also, Visual Studio will now provide me with intellisense for any objects, functions, etc, exposed by the other script. This is a good thing since typos and dynamic languages do not mix!

Also note that the references declaration is transient. If script C references script B, and script B references script A, then script C automatically gets a reference to script A as well.

Next, clearly identify logical script file units. I listed examples of these at the start of this post. It makes sense to group the units of scripts into separate folders. E.g. ~/scripts/libs, ~/scripts/admin, ~/scripts/customers.

Further sub-folders within those may still make sense for your project, but the top-level folder defines the unit. All files with a top-level folder will be concatenated in the correct order and minified into a single script.

Ordering the scripts

Remember the special "references" comments added to the scripts? We can use them to define a directed acyclic graph of dependencies. The scripts can then be topologically sorted and output in the correct order.

The algorithm will need to account for dependencies between units. This means that the order that each unit is added into a page will be taken care of too.

Managing scripts

Maintaining a block of script tags in your HTML is fine for simple web pages. This does not scale for complex application with multiple regions, controls, components, etc. It's good practice to extract common bits of HTML into "partials". However, if a partial requires a script to be loaded into the page as well then we have a problem.

Do not output script tags with your partial!

Your partial needs to somehow register that it requires a script to be referenced from the page. The page will then add all the required script tags in one place.

The page script manager must be aware of debug and release mode. In debug mode a script tag is created for each source script. In release mode the minified script of each unit is produced instead.

Solution?

Sorry to disappoint you, but this is all just ideas for now! I've had them floating around in my head and wanted to get them out in public for discussion.

I'd love to hear about how you are managing JavaScript.

Please let me know what you think in the comments or on Twitter @andrewdavey.

Caching versioned static files with ASP.NET MVC and IIS7

2011-03-21T00:00:00-07:00

Correctly caching a website's content will improve the load time of pages. There's no sense in making a web browser download the same stylesheets and images repeatedly. In fact, we want to avoid the web browser even doing tentative "if not modified" requests. These all add up to extra HTTP connection overhead.

This article will show you how to configure IIS7 and use ASP.NET MVC to make sure your static files are always cached correctly.

Using max-age

IIS7 is easy to configure from your web application's Web.config file. Find the <configuration>/<system.webServer> section and add:

<staticContent>
    <!-- Tell client to cache static files for a year -->
    <clientCache cacheControlMode="UseMaxAge"
                 cacheControlMaxAge="365.00:00:00" />
</staticContent>

This tells IIS to add a cache-control header to all static files it serves. The header specifies the "max-age" of a file to be 365 days. So once a web browser has downloaded the file once, it won't request it again for a year.

Versioning URLs

Websites change over time. We'll have a problem if we can't make a web browser download an updated stylesheet, image or (worst of all) javascript file. Therefore it's important to include a version number into the URL of any static file.

When we update our website we can increment the version number to ensure the static files are downloaded again.

For this article, we'll assume all static files are within a directory called "static" in the root of the website.

Let's consider a file saved as "/static/styles/site.css". In our HTML, we'll reference the stylesheet like this:

<link href="/static/1.0.0.0/styles/site.css" type="text/css" rel="stylesheet"/>

Notice the insertion of a version number. Since we're using ASP.NET, I find it convenient to use the application Assembly's version number. This is increased with each build and deployment, so it guarantees we won't ever use stale files.

I'll show automate this URL how to generation later. Let's first see how to make IIS server the actual file from this modified URL.

Add the following XML into your Web.config, in <configuration>/<system.webServer>:

<rewrite>
    <rules>
        <rule name="StaticFiles" stopProcessing="true">
            <match url="static/[\d.]+/(.*)$" /> 
            <action type="Rewrite" url="static/{R:1}" />
            <!-- e.g. "static/1.9.8.4/styles/site.css" -> "static/styles/site.css" -->
        </rule>
    </rules>
</rewrite>

This is using the IIS7 Rewrite Module. If you don't already have this already then Install URL Rewrite.

As the comment in the XML explains we're matching static file urls that contain a version number and rewriting to the actual file on disk. The "{R:1}" refers to the text captured by "(.*)" in the match regular expression.

Generating versioned URLs

Manually maintain the version of each URL would be crazy. We can use an HTML helper to generate the correct URLs for us. Add this helper to your MVC web application.

using System.IO;
using System.Reflection;
using System.Web;
using System.Web.Mvc;

namespace StaticDemo.Helpers // Change this namespace to match your web application.
{
    public static class StaticFileHelper
    {
        static string assemblyVersion;

        static StaticFileHelper()
        {
            // This way of getting the assembly version works in medium trust.
            assemblyVersion = new AssemblyName(typeof(StaticFileHelper).Assembly.FullName).Version.ToString();
        }

        public static string StaticFile(this UrlHelper html, string filename)
        {
            var virtualPath = (
                html.RequestContext.HttpContext.IsDebuggingEnabled
                    ? DebugVirtualPath(filename, html.RequestContext.HttpContext.Server)
                    : ReleaseVirtualPath(filename)
            );

            var root = html.RequestContext.HttpContext.Request.ApplicationPath;
            if (root.Length > 1) // e.g. "/myapp" instead of just "/"
            {
                virtualPath = root + virtualPath;
            }
            return virtualPath;
        }

        static string ReleaseVirtualPath(string filename)
        {
            // Insert the assembly version into the path (not the query string).
            // This seems to be more reliable when proxies are involved:
            // http://www.stevesouders.com/blog/2008/08/23/revving-filenames-dont-use-querystring/
            return "/static/" + assemblyVersion + "/" + filename;
        }

        static string DebugVirtualPath(string filename, HttpServerUtilityBase server)
        {
            // Use query string to break caching. This means the file's path
            // still matches the development file system.
            var absoluteFilename = server.MapPath("~/static/" + filename);
            var version = File.GetLastWriteTime(absoluteFilename).Ticks.ToString();
            var separator = (filename.Contains("?") ? "&" : "?");
            return "/static/" + filename + separator + "nocache=" + version;
        }
    }
}

This HTML helper creates the static versioned URL for a filename. Notice that it behaves differently when the web application is in debug mode. While we're developing a website we'll be in debug mode. In this case we don't want caching by application version number. Instead the helper appends the last write time of the file.

Always be sure to set <configuration>/<system.web>/<compilation debug="false"> when you deploy your web application!

Now make this helper available to your views. In "Views\Web.config", add your helpers namespace into <configuration>/<system.web.webPages.razor>/<pages>/<namespaces> (for sexy Razor views), or <configuration>/<system.web>/<pages>/<namespaces> (for horrid old ASPX views).

<add namespace="StaticDemo.Helpers"/>

Change the namespace to match your web application.

Now in our Razor view we use the helper:

<link href="@Url.StaticFile("styles/site.css")" rel="stylesheet" type="text/css" />

For those using ASPX views:

<link href="<%: Url.StaticFile("styles/site.css") %>" rel="stylesheet" type="text/css" />

That's it!

You now have elegantly versioned static files. If you like what you've read follow me on Twitter for regular web development tips, ideas and rants.

MVC Property Binder

2011-03-12T00:00:00-08:00

ASP.NET MVC has a rich model binder. Complex objects can be created from various bits of the HTTP request data. However, this isn't always enough and sometimes we need to extend the default binding behaviour.

In my application, I have a data structure to represent a "change password" request.

class ChangePassword {
  public string Username {get; set;}
  public string OldPassword {get; set;}
  public string NewPassword {get; set;}
  public string ConfirmNewPassword {get; set;}
}

A controller action method receives this and performs the required update.

public ActionResult ChangePassword(ChangePassword change) { ... }

An HTML form will provide the three password property values, but the Username property is different. The username must be that of the currently authenticated user. This value is contained in HttpContext.User.Identity.Name.

I don't want it allowing some evil user to pass in some other username, via the query string, for example. So I need to tell the MVC binder how to assign this property. This requires a custom model binder.

The problem is that MVC does not provide a way to set a custom model binder for a specific property.

What I like to do is this:

class ChangePassword {
  [PropertyBinder(typeof(CurrentUsernameBinder))]
  public string Username {get;set;}
  public string OldPassword {get;set;}
  public string NewPassword {get;set;}
  public string ConfirmNewPassword {get;set;}
}

PropertyBinder is a basic attribute that lets me declare the model binder to use.

public class PropertyBinderAttribute : Attribute
{
  public PropertyBinderAttribute(Type binderType)
  {
    BinderType = binderType;
  }

  public Type BinderType { get; private set; }
}

For this new attribute to work, I have to override the default model binder like this:

public class CustomModelBinder : DefaultModelBinder
{
  protected override void BindProperty(ControllerContext controllerContext, ModelBindingContext bindingContext, System.ComponentModel.PropertyDescriptor propertyDescriptor)
  {
    // Check if the property has the PropertyBinderAttribute, meaning
    // it's specifying a different binder to use.
    var propertyBinderAttribute = TryFindPropertyBinderAttribute(propertyDescriptor);
    if (propertyBinderAttribute != null)
    {
      var binder = CreateBinder(propertyBinderAttribute);
      var value = binder.BindModel(controllerContext, bindingContext);
      propertyDescriptor.SetValue(bindingContext.Model, value);
    }
    else // revert to the default behavior.
    {
      base.BindProperty(controllerContext, bindingContext, propertyDescriptor);
    }
  }

  IModelBinder CreateBinder(PropertyBinderAttribute propertyBinderAttribute)
  {
    return (IModelBinder)DependencyResolver.Current.GetService(propertyBinderAttribute.BinderType);
  }

  PropertyBinderAttribute TryFindPropertyBinderAttribute(PropertyDescriptor propertyDescriptor)
  {
    return propertyDescriptor.Attributes
      .OfType()
      .FirstOrDefault();
  }
}

By overriding the BindProperty method, I can check for the attribute and call into the specified model binder.

This line of code in Global.asax Application_Start to assign the new default binder:

System.Web.Mvc.ModelBinders.Binders.DefaultBinder = new CustomModelBinder();

Incidentally, the username binder looks something like this:

public class ClientIdBinder : IModelBinder
{
  readonly HttpContextBase httpContext;

  public ClientIdBinder(HttpContextBase httpContext)
  {
    this.httpContext = httpContext;
  }

  public object BindModel(ControllerContext controllerContext, ModelBindingContext bindingContext)
  {
    if (httpContext.User.Identity.IsAuthenticated)
    {
      return httpContext.User.Identity.Name;
    }

    bindingContext.ModelState.AddModelError(bindingContext.ModelName, "User not signed in."); 
    
    return null;
  }
}

For more web development banter, with an MVC slant, follow me on Twitter!

Git Forked

2011-03-03T00:00:00-08:00

I now use GitHub almost exclusively as my project hosting provider. I have open source and private projects hosted there. GitHub really encourages the social aspects of open source. They also provide plenty of hand-holding while I'm still learning git.

As the creator of open source projects, the thing I hope for most is people getting involved. I want people to fork a project, edit the code and submit pull requests. So I created gitforked.com.

Git Forked creates social media style "fork" buttons that link to your GitHub repository page. You can put these buttons on your home page, blog, etc. The number of forks is shown next to the button, just like the numbers of tweets next to a Twitter tweet button.

Here's an example button: Fork

So head over to gitforked.com, enter your repository URL and generate your very own fork button!

CDNCatalog Updated

2011-03-01T00:00:00-08:00

If you're building a modern website then you'll be needing some javascript libraries and css.

I've updated CDNCatalog.com with links to all the latest javascript and css resources hosted by Google, Microsoft, etc.

The website now has easy one-click icons to copy either the URL or HTML snippet for a resource.

So take a look and tell your friends!

Handling Not Found with ASP.NET MVC3

2011-02-26T00:00:00-08:00

A web application built using ASP.NET MVC can break in a few different places when handling a URL it does not recognise. By default, your user will receive a rather unfriendly default ASP.NET error page. Ideally, you should be catching these “not found” errors and displaying a more useful page.

First let's look at the places you need to watch for broken URLs in an ASP.NET MVC3 application. Then I'll introduce a simple library you can use to handle all this.

Missing action method on a controller

Imagine we have a controller called HomeController and a default route of “{controller}/{action}” in the route table. Then a URL with the path “home/epicfail” will be routed to the HomeController and look for an action method called “EpicFail”.

If the action method does not exist then the Controller's default HandleUnknownAction method is called and throws an HttpException, with 404 as the status code. ASP.NET then shows its nasty error page.

A possible solution is to override HandleUnknownAction and render your friendly 404 page instead of throwing an exception.
Missing controller

Given a route of “{controller}/{action}”, the URL “missing/example” will cause a search for a controller called “MissingController”. If this controller is not found then a 404 HttpException is thrown.

To catch this, you need to have a custom controller factory (IControllerFactory) that returns a special “not found” controller to handle the broken request.
Unknown route

If the URL does not match any of the defined routes then a 404 HttpException is thrown. To intercept this you need to create a “catch-all” route. For example, “{*any}” and map this to some controller that will then show your friendly 404 page.
Deliberate not found response

Sometimes your action methods need to say that a resource is not found. For example, a row with the given ID was not found in the database anymore. You may want to reuse a common “Not Found” view.

Introducing NotFoundMvc

Correctly handling all the possible “not found” causes is non-trivial and is likely to be repeated in many MVC applications. Therefore I created the NotFoundMvc library.

Add the library to your project via nuget: Install-Package NotFoundMvc

Or get the source code on GitHub: github.com/andrewdavey/NotFoundMvc

Referencing the NotFoundMvc.dll assembly from your web application project will cause it to auto-start with the application. (Thank you PreApplicationStartMethod .)

NotFoundMvc will:

Handle all “not found” causes and render a friendly error view
Add a catch-all route to the end of the route table to handle unrecognised routes
Wrap the controller factory to handle missing controllers
Wrap the ActionInvoker of each created controller to handle missing actions
Provide a NotFoundViewResult you can use to return a NotFound view from your actions

The wrapper objects pass through to the original implementations. So if, for example, you're using a custom controller factory already, it will still work as before.

Installing the nugget package will also add a basic NotFound.cshtml view to the ~\Views\Shared folder. So if you're not using nugget, then please create this view manually. If you're using aspx views, or something else, change the file extension as required.

The output of the NotFound view must be at least 512 bytes in length, otherwise IE and Chrome will show their own error page! The default NotFound.cshtml view includes padding spaces to avoid this.

The source code for NotFoundMvc contains a sample project to demonstrate basic usage.

MVC routing for public facing web applications

2011-02-13T00:00:00-08:00

When building a public web application with ASP.NET MVC, I often want to divide the project into three major parts.

The publicly visible, marketing website with about pages, product tour, contact info, sign up, etc.
The actual application, secured behind a login form.
A system admin area, so I can manage user accounts, monitor reports, etc.

Areas, in MVC 2 and better, make it easy to slice up the three parts of the web application. Read on to learn how I set this up and get some useful tips you can use for your own applications.

Everything is an Area

You probably want the public marketing pages to live at the root of your URL structure. So it's tempting to put the controllers and views into the top-level Controllers and Views folders. Don't do this. I don't see why the marketing junk should get special treatment. It's an area just like the application and the system admin areas.

So add three areas to your MVC project called "Public", "App", and "Admin". The default route registration for these is mostly OK, except for Public. We don't want "public" in the URLs. However, simply editing the route registration for Public will cause a potential routing failure. The order of route registration matters.

If, by chance, the Public area is registered before the other two, then its default route of "{controller}/{action}/{id}" will greedily steal any URL heading for App or Admin. For example, the URL "app/home/index" would end up looking for a controller in Public called "AppController" and an action method called "Home". This is not what we intended!

To remedy the situation we must force the Public area to general route to be added after all other areas. Cut it out of the PublicAreaRegistration.cs file. Move it to Application_Start in Global.asax, after the call to AreaRegistration.RegisterAllAreas.

Then make the following changes to make it still behave as an Area route:


    AreaRegistration.RegisterAllAreas(); // Force App and Admin to run first
var publicRoute = routes.MapRoute(
    "PublicRoute",
    "{controller}/{action}/{id}",
    new { controller = "Home", action = "Index", id = UrlParameter.Optional },
    new[] { typeof(Areas.Public.Controllers.HomeController).Namespace }
);
publicRoute.DataTokens["Area"] = "Public";

This gives the route the correct namespace to look for controllers and assigns the Area name.

URLs heading for App and Admin will reach their intended destinations. You can still keep custom routes in Public's registration. Just make sure they aren't too general, capturing URLs for areas.

I hope you found this tip useful. Follow me on Twitter for constant web application development banter!

Displaying a flash message with ASP.NET MVC

2010-11-30T00:00:00-08:00

Post-Redirect-Get is a common pattern used in MVC applications. You show a form to the user, they enter their data and click a button to post it to the server. A controller processes the form and returns an HTTP redirect response to the web browser. The browser follows the redirect by getting the given URL.

The form post controller action may need to show a message to the user. For example, saying "your message has been sent". So you have to pass this message to the next page somehow.

The Wrong Way

One approach is to use the controller's TempData dictionary. TempData, by default, uses the session to pass data between requests. The post action method will put the message into TempData. The page we're redirecting to will read TempData and display the message.

Unfortunately using TempData will cause an annoying bug when the browser has already cached the final page. The redirect tells the browser to get the page, but the browser has it cached. So the page is shown without the extra call to the server. This means the TempData is never read.

What's worse is some subsequent page request may not be cached and actually read the TempData which was not intended for it!

A Better Way

Use a cookie to send the message along with the redirect request. The controller action method will look like:

public ActionResult ProcessForm() {
    // ... process form ...
    Response.Cookies.Add(new HttpCookie("FlashMessage", "Data processed") { Path = "/" }));
    return RedirectToAction("Index");
}

In the view we're redirecting to, use JavaScript to read the cookie and display the message. Then delete the cookie so the message is not shown again the next time we load this page.

I use jquery.cookie.js to handle the cookie access. I use a jQuery extension that wraps up the flash message display code:

$.fn.flashMessage = function (options) {
    var target = this;
    options = $.extend({}, options, { timeout: 3000 });
    if (!options.message) {
        options.message = getFlashMessageFromCookie();
        deleteFlashMessageCookie();
    }
    if (options.message) {
        if (typeof options.message === "string") {
            target.html("" + options.message + "");
        } else {
            target.empty().append(options.message);
        }
    }

    if (target.children().length === 0) return;

    target.fadeIn().one("click", function () {
        $(this).fadeOut();
    });

    if (options.timeout > 0) {
        setTimeout(function () { target.fadeOut(); }, options.timeout);
    }

    return this;

    function getFlashMessageFromCookie() {
        return $.cookie("FlashMessage");
    }

    function deleteFlashMessageCookie() {
        $.cookie("FlashMessage", null, { path: '/' });
    }
};

The view contains a div to show the message:

<div id="flash-message"></div>

The flash message extension is called using:

$(function() { $("#flash-message").flashMessage(); });

Bandage - Add properties to view models at runtime

2010-11-19T00:00:00-08:00

This post introduces the Bandage project for ASP.NET MVC.

Introduction

Are you a pragmatic ASP.NET MVC web developer? I like to think I am. When working with simple entities it feels like overkill to use separate view model objects in my views. I'd rather just send my entity directly to the view and get on with something more fun (like delivering business value!)

Whilst AutoMapper does a great job of conventionally mapping entities into view models, I'd rather not have to create the view model class when it's essentially a property-by-property mirror of my entity.

Nothing stops me sending entities directly to the view. However, things get messy when I need to display information derived from properties of the entities. I end up resorting to helpers, extension methods and other contraptions that don't feel as natural as simply getting a property value. Furthermore, when using dynamic view models, extension methods do not work, so they're no good anyway.

If I later decide to man-up and create real view models, I'd then have to replace all helper calls in my view with properties. Have you tried refactoring view code? It's not fun!

I created the Bandage library to solve this problem. Read on for a simple example and learn what Bandage can do for you.

Use Case

Let's take a use case I hit quite often when developing MVC web applications. We have some list of objects, products for example, to show on the screen. For each product, we want a hyperlink to a details page.

class Product {
    public int Id { get; set; }
    public string Name { get; set; }
}

The URL for a product details page is formed using the Id and the Name properties. The Name property will be processed to create a "slug" (a URL safe version of the actual Name). This is to be more SEO-friendly. We keep the Id in the URL to keep our coding easy.

For example: The product
new Product { Id = 1, Name = "Interwebz for Dummies" }
will have the URL /product/1/interwebz-for-dummies

My MVC route set up defines the route as follows:

routes.RouteUrl(
    "ProductDetails",
    "product/{id}/{slug}",
    new { controller = "Product", action="Details" }
);

The ProductController List action will get the products and send them to the view like this:

public ActionResult List() {
    ViewModel.Products = ProductRepository.GetAll();
    Return View();
}

The List view is then something like:

<ul>@foreach (Product product in View.Products) {
    <li><a href="Url.RouteUrl("ProductDetails", new { id = product.Id, slug = Util.GetSlug(product.Name) })">@product.Name</a></li>
}</ul>

Code like that, in my opinion, does not belong in the view. It's complex and really doesn't express the intent well.

It would be so much nicer to write the following.

<ul>@foreach (var product in View.Products) {
    <li><a href="@product.Url">@product.Name</a></li>
}</ul>

We simply need a way to add an extra property to Product. We don't want the Url property in our business object, it's purely a web-thing. We don't want to create a view model, that's overkill for simple situations like this.

Notice that the product variable in the second code snippet is dynamically typed. This is because View is dynamic, so anything you get from it is also typed as dynamic. This dynamism is where we can inject some magic pixie dust.

Say hello to Bandage

Bandage is a small library which lets you define dynamic view models and then effectively monkey patch properties onto existing types. So, for our example, we'll have Product objects in the view model and then add a Url property to each product.

The controller List action changes from before to this:

public ActionResult List() {
    var viewmodel = new Bandage.DynamicViewModel();
    viewmodel.Products = ProductRepository.GetAll();
    viewmodel.Add(DynamicProperty.For<Product>("Url", product => ProductUrl(product)));
    Return View(viewmodel);
}

private string ProductUrl(Product p) {
    return Url.RouteUrl("ProductDetails", new { id = product.Id, slug = Util.GetSlug(product.Name) });
}

The key line of code there is when we add a DynamicProperty for the Product type. We provide the name of the property and a lambda that will return the value for a given Product. This is registered for the entire view model. So any Product object, anywhere in the object graph, will have this dynamic property available.

The view can now use this dynamic view model and its magic dynamic properties.

<ul>@foreach (var product in Model.Products) {
    <li><a href="@product.Url">@product.Name</a></li>
}</ul>

Note: We are passing the viewmodel in to the view's Model property, rather than using the View object as before. Model is also typed as dynamic however in this case. This is because Controller's ViewModel property is readonly so we can't set it to our own object. Please vote on the CodePlex issue to have this fixed.

Behind the curtain

DynamicViewModel intercepts any attempt to get a property and returns a special wrapper object instead of the original value. This wrapper is also dynamic and intercepts property calls and other kinds of member access.

When we ask for the Url property of Product, the wrapper first checks if a DynamicProperty added to the view model can be used instead. The product object is passed to the lambda we register in the controller. This then returns the value.

All other regular member access is delegated back to the wrapped object.

Try Bandage for yourself

Bandage is an open source library (MIT License). You can get the source code at GitHub. Feel free to fork, improve and send me pull requests.

The dynamic object wrapper is still beta-quality and needs some serious testing. However it does work for my meagre needs.

I'd love to hear what you think about Bandage. Give me a shout on twitter @andrewdavey or leave a comment here.

Going Postal - Generating email with ASP.NET MVC View Engines

2010-11-17T00:00:00-08:00

Preamble

The .NET framework provides a simple API for sending email. I assume you are already acquainted with the handy namespace System.Net.Mail. However, dynamically generating the content of an email is still a bit tricky. Code that concatenates strings and variables is no fun to write or read!

What we need is a way to write text (or html) templates which will be rendered with some data. ASP.NET MVC already has exactly this in the form of Views. So let's reuse the view engine infrastructure to create our emails.

I created a simple library called Postal that does just that. Read on to find out more.

Postal in action

First, let's see what an email view will look like. I'm using the excellent Razor view engine (coming with MVC3).

Example.cshtml


    To: @View.To
From: example@website.com
Subject: @View.Subject

Hello,
This email was generated using Postal for asp.net mvc on @View.Date.ToShortDateString()
Message follows:
@View.Message

Thanks!

This email is just plain text, but it could contain HTML instead for richer formatting options.

Notice also that we are defining some email headers (To, From, Subject) at the top. Postal makes it easy to define everything about the email in a single file, rather than having to set the headers in code. Postal will parse the headers out of the rendered view and apply them to the outgoing email message.

Since this is a regular Razor view, we can use the handy View dynamic object to access view data. This data is populated from code. Let's see an example controller action that will send this email.


    public ActionResult Send(string to, string subject, string message)
{
    dynamic email = new Email("Example");
    email.To = to;
    email.Subject = subject;
    email.Message = message;
    email.Date = DateTime.UtcNow;

    service.Send(email);

    return RedirectToAction("Sent");
}

This code creates a new Email object, passing the name of the email view to use. Postal will look for email views in ~/Views/Emails/. So our email view is at ~/Views/Emails/Example.cshtml.

We've typed the Email object as dynamic. This lets us define the properties we want at runtime, without having to create an explicit view model class. I like this lightweight approach. (If you don't, feel free to send me a pull request!)

The Email object is building up a ViewDataDictionary internally, ready to send to the view for rendering.

Once the email object is ready to send, we're calling the service object. This is a field of the controller.


    public class HomeController : Controller
{
    // In real code this should be injected by an IoC container.
    IEmailService service = new EmailService(ViewEngines.Engines);

    // ... action methods here ...
}

The EmailService manages finding the view, rendering the text, parsing the headers and finally sending the email.

Email is sent using the System.Net.Mail.SmtpClient class. You can configure the SMTP settings in web.config. For example, we can simple write the emails to a folder for testing purposes.


    <configuration>
    <system.net>
        <mailSettings>
            <smtp deliveryMethod="SpecifiedPickupDirectory">
                <specifiedPickupDirectory pickupDirectoryLocation="c:\email"/>
                <network host="localhost"/>
            </smtp>
        </mailSettings>
    </system.net>
</configuration>

Get the code

Postal is something I put together in an afternoon. So the usual warnings about code you find on the internet apply! That said, head over to GitHub and grab the source:

https://github.com/andrewdavey/postal

There's a sample project in there as well that puts the code from this post together into a basic web application.

If you want to change Postal, fix bugs, etc, please fork the repository and send me pull requests. I love to see people getting involved with open source projects. (Postal has the MIT License.)

For questions and discussion, either follow me on twitter @andrewdavey or leave a comment here.

List GitHub projects using JavaScript

2010-11-11T00:00:00-08:00

Do you use GitHub? Got a blog/website? Then read on for a handy bit of JavaScript.

Preamble

GitHub is simply fantastic. If you're into open source then it really is the place to host your work. Heck, I even use it for private projects as well.

If you have some kind of blog or personal website why not promote and show-off your projects? It's exactly what I'm doing here. Just look at my home page.

The list of projects is generated using some simple JavaScript. Read on to get the code.

Get the code

Before I go further, I must say that I originally copied this code from jointheconversation.org. However, I've made enough changes that I think it's worth posting here to share the love.

In your HTML add a <div> with an ID. The list of projects will be inserted here.

<html>
  ...
  <div id="github-projects"></div>
  ...
</html>

Next, just before </body>, add these scripts.

<script src="http://ajax.microsoft.com/ajax/jquery/jquery-1.4.2.min.js" type="text/javascript"></script>
<script src="/scripts/github.js" type="text/javascript"></script>
<script type="text/javascript">
  $(function() {
    $("#github-projects").loadRepositories("andrewdavey");
  });
</script>

Feel free to load jQuery from wherever you usually do. I just happen to like using a CDN.

Make sure you replace "andrewdavey" with whatever github username you want to display repositories for.

Finally, create the /scripts/github.js file. Here comes the magic.

jQuery.githubUser = function(username, callback) {
  jQuery.getJSON("http://github.com/api/v1/json/" + username + "?callback=?", callback);
}

jQuery.fn.loadRepositories = function(username) {
  this.html("<span>Querying GitHub for repositories...</span>");

  var target = this; 
  $.githubUser(username, function(data) {
    var repos = data.user.repositories;
    sortByNumberOfWatchers(repos);

    var list = $('<dl/>');
    target.empty().append(list);
    $(repos).each(function() {
      list.append('<dt><a href="'+ this.url +'">' + this.name + '</a></dt>');
      list.append('<dd>' + this.description + '</dd>');
    });
  });

  function sortByNumberOfWatchers(repos) {
    repos.sort(function(a,b) {
      return b.watchers - a.watchers;
    });
  }
};

I hope that code is fairly self-explanatory. It's extending jQuery with a function that will query GitHub for information about the given username. A definition list is generated to display the repositories.

Please feel free to use the code, change it, etc. Maybe even let me know if you find it useful, I'm on twitter @andrewdavey!

OpenWrap - Package management for .NET

2010-11-10T00:00:00-08:00

One of the open source projects I'm helping with is OpenWrap.

OpenWrap is a package manager for .NET. We're always looking for awesome .NET developers to help out, so if you're interested please get in touch.

The main website has all the details and links to source code: www.openwrap.org

Nested layout pages in Razor

2010-11-08T00:00:00-08:00

This post is for people using the Razor view engine in ASP.NET MVC3.

Preamble

In any reasonably sized website you will want to use layout pages for the common header and footer parts of HTML. Razor makes this easy and the syntax is elegant (especially when compared to the old webforms view engine). However, on more complex websites there is often a need to nest layouts.

Consider a web application that has some common scripts and styles across all pages, but a number of "areas" that have their own HTML structure. For example, a "public" area, an "admin" area and a "customer" area. We'd like to define a layout for the top-level HTML, stylesheets and scripts. Then define layouts for each area and have them inherit from the top-level layout.

Nested Layouts

The top-level layout looks like a regular Razor layout. Let's create a file:
~/Views/Shared/_site.cshtml

<!DOCTYPE html>
<html>
<head>
  <title>@View.Title</title>
</head>
<body>
  @RenderBody()
  <p>Copyright Me 2010</p>
  <script type="text/javascript" src="/scripts/jquery.js"></script>
  @RenderSection("scripts", required: false)
</body>
</html>

Note that this top-level layout defines where it's inner content will go (RenderBody) and also has an optional "scripts" section. Pages using this layout will be able to specify the extra scripts they need in that section.

For each area, we can now create a nested layout page. For example, in the "Public" area we'll create a file:
~/Areas/Public/Views/Shared/_public.cshtml

@{ Layout = "~/Views/Shared/_site.cshtml"; }
<div id="public">
  <p>public header</p>
  @RenderBody()
  <p>public footer</p>
</div>
@section scripts {
  <script type="text/javascript" src="/scripts/public.js"><script>
  @RenderSection("scripts", required: false)
}

This nested layout inherits from the top-level layout. It adds some HTML common to all pages in the public area and defines where the page content will go (RenderBody).

It also has to redefine the scripts section. This has to be there even when not actually adding any HTML to the section, otherwise content pages will not be able to add to the section. This is just like nested master pages in webforms using ContentPlaceholders.

A view in the public area will look like this:

@{
  Layout = "~/Areas/Public/Views/Shared/_public.cshtml";
  View.Title = "Home Page";
}
<p>Welcome to my public website!</p>

End Result

When the home page view is rendered the top-level and area-level layouts are nested correctly. The output will look like this:

<!DOCTYPE html>
<html>
<head>
  <title>Home Page</title>
</head>
<body>
  <div id="public">
    <p>public header</p>
    <p>Welcome to my public website!</p>
    <p>public footer</p>
  </div>
  <p>Copyright Me 2010</p>
  <script type="text/javascript" src="/scripts/jquery.js"></script>
  <script type="text/javascript" src="/scripts/public.js"><script>
</body>
</html>

Hotmod - HTML Output Modification

2010-11-03T00:00:00-07:00

This post introduces the motivation behind the Hotmod project.

Preamble

Using ASP.NET to generate HTML, either with webforms or MVC, can leave the resulting output looking somewhat messy. The indentation is inconsistent and can be harder to debug when a viewing a page's source.

Also, when deploying your application in release mode, do you need pretty looking HTML? You could actually "minify" the HTML by removing all the insignificant whitespace between tags; Just like you can with CSS and JavaScript.

Inline HTML generation using server-side controls or helpers is great on an ad-hoc basis, but sometimes this gets very un-DRY. For example, say you want to enter application relative URLs in your HTML and have them expanded at runtime to their equivalent full paths. This is essential when your web application is going to run inside a virtual directory, not at the root.

In ASP.NET MVC you'll probably write something like:

<a href="<%: Url.Content("~/content/foo.html") %>">foo</a>

That works, but I think the intent could be clearer.

Why can't we just type:

<a href="~/content/foo.html">foo</a>

and establish a convention that all URLs in the HTML that start with a "~" need to be expanded into their absolute form?

What we need is a post-processor for HTML generated by ASP.NET.

Hotmod is exactly that.

Enter Hotmod

ASP.NET is very extensible, Hotmod contains an implementation of IHttpModule that hooks into the web request pipeline to provide some funky post-processing for your HTML output.

Hotmod will capture the HTML generated by your web form pages and MVC views, parse the document into an XDocument and then apply any number of modifiers. The resulting HTML can be either "pretty printed" with nice indentation, or minified to remove all unnecessary whitespace.

Your HTML will need to be parseable as XML for this work. So I hope you are closing your tags correctly and using quotes around attribute values!

Hotmod defines a simple IModifier interface you can implement to add any application-wide modifications you want to make to the HTML. For example, you could add a generation timestamp footer in a comment.

The approach let's you be much more compositional than trying to nest multiple master pages.

Get Hotmod

Hotmod is an open source project. Get the code from Hotmod on Github.

Start background tasks from MVC actions using Autofac

2010-11-01T00:00:00-07:00

This post is for people who know about ASP.NET MVC and IoC containers.

Preamble

Your MVC actions should be quick to return a response to the user. Any long running task should be run on a background thread. This reduces the chance of your web server becoming unresponsive.

I'm using Autofac as my IoC container in ASP.NET MVC projects. In addition to an application wide, global container, Autofac provides a "http request scoped" container for each web request. This means we can declare dependencies such as database connections to be "HTTP Request Scoped". Each request gets its own instance. At the end of the request, Autofac knows to dispose of any disposable objects.

This works very well, until you don't have an HTTP request to work within. Which is what happens when running some code on a background thread.

So we need a way to start our background task from a controller action method, but give it a new request-style context. It will not have an actual HTTP context. We'll pass any required information to the task when starting it.

Code time

To allow controller actions to start background tasks, I will pass an instance of the following interface into the controller via the constructor.

public interface IAsyncRunner
{
    void Run<T>(Action<T> action);
}

Remember, I'm using Autofac to create my controllers. So the constructor parameters are resolved from the container. An example controller looks like this:

public class HomeController : Controller {
    public HomeController(IAsyncRunner async) {
        this.async = async;
    }
    readonly IAsyncRunner async;
}

For this example, imagine we want to do heavy image processing in response to a file being uploaded. Our action method will be:

public ActionResult UploadImage(HttpPostedFileBase image) {
    image.SaveAs("example.jpg");
    async.Run<ImageResizer>(resizer => resizer.Resize("example.jpg"));
    return RedirectToAction("UploadFinished");
}

That's a nice short method, but let's analyse the details.

First, we synchronously write the raw image data to disk. Then we call then async runner's Run method. We provide the type of the object to be invoked and a delegate to run. The async runner will start a new background task, create an ImageResizer object and call the given delegate.

In the meantime the action method is free to return a response to the user.

The AsyncRunner

Let's move onto to the actual AsyncRunner implementation. I'm using Autofac, but the code could be adapted for use with any IoC container.

public class AsyncRunner : IAsyncRunner
{
    public void Run<T>(Action<T> action)
    {
        var app = GetApplicationContainer();
        Task.Factory.StartNew(delegate
        {
            // Create a nested container which will use the same dependency
            // registrations as set for HTTP request scopes.
            using (var container = app.BeginLifetimeScope(WebLifetime.Request))
            {
                var service = container.Resolve<T>();
                action(service);
            }
        });
    }

    IContainer GetApplicationContainer()
    {
        // Use Autofac's ASP.NET integration to get the application-wide
        // container that exists in the ApplicationInstance.
        // See the Autofac documentation for more about this.
        var accessor = ((IContainerProviderAccessor)HttpContext.Current.ApplicationInstance);
        return accessor.ContainerProvider.ApplicationContainer;
    }
}

The AsyncRunner uses Autofac to create an instance of the requested type T. This happens inside a new "lifetime scope". By using Autofac to create the object, that object can also declare dependencies to be provided by the container.

The .NET 4.0 Task Parallel Library is used to start a new task to run within, rather than worry about creating threads manually.

The end result is a clean way to start asynchronous tasks, whilst still being able to use Autofac's excellent features.

aboutcode.net

Automating Chrome on Windows with JavaScript using Selenium's WebDriverJS

Installing the tools

A basic browser automation script

Learning more

Saving my sanity with browser-automation testing?!

The set-up

Creating AngularJS controller classes with TypeScript

Automatic JSON date parsing with AngularJS

Working Demo

Twitter Bootstrap control-group directive for AngularJS

Validation styling

Other improvements

Demo

eBook Review - Twitter Bootstrap Web Development How-To

Load images with jQuery Deferred

Using jQuery Deferred

Implementing $.loadImage

Google Chrome extensions using KnockoutJS

Sandboxing your application

Loading the sandboxed application

Communicating with the application

Full sample code

Twitter Bootstrap Modals and Knockout.js

What you'll learn

View model flow

Twitter Bootstrap Modal

Rendering modal templates

The view models

The showModal function

Extensions and ideas

Full sample code

Thanks for reading

Zero Configuration Asp Net Modules And Handlers

Testing Temp Directory

Efficient Encapsulation Of Javascript Objects

Annotated source for defineClass

Proxy Object

Extensions

Dear ASP.NET, we need to talk about JavaScript

JavaScript

CoffeeScript

HTML Templates

Client-side Asset Management

Knapsack - Automatic JavaScript and stylesheet dependency management for ASP.NET

Managing JavaScript

Existing Solutions

What I want to see

Ordering the scripts

Managing scripts

Solution?

Caching versioned static files with ASP.NET MVC and IIS7

Using max-age

Versioning URLs

Generating versioned URLs

That's it!

MVC Property Binder

Git Forked

CDNCatalog Updated

Handling Not Found with ASP.NET MVC3

Introducing NotFoundMvc

MVC routing for public facing web applications

Everything is an Area

Displaying a flash message with ASP.NET MVC

The Wrong Way

A Better Way

Bandage - Add properties to view models at runtime

Introduction

Use Case

Say hello to Bandage

Behind the curtain

Try Bandage for yourself

Going Postal - Generating email with ASP.NET MVC View Engines

Preamble

Postal in action

Get the code

List GitHub projects using JavaScript

Preamble

Get the code

OpenWrap - Package management for .NET

The `showModal` function