PongR part 3: client side


Heads up!

The blog has moved!
If you are interested in reading new posts, the new URL to bookmark is http://blog.valeriogheri.com/


In part 1 of “PongR – my first experience with HTML5 multiplayer gaming” , I talked about the spirit of this project, the system architecture, technologies used and the design of the game (remember the server authoritative model?)

In part 2 I talked about the server side code and the server loops

This is part 3 and I will talk about the client side code, the client loops and how we draw basic (no sprites, only basic shapes) images on a canvas.

Code and Demo

As always, the code is fully published on github [https://github.com/vgheri/PongR] and a (boring!) demo is available at http://pongr-1.apphb.com . If you don’t have anyone to play with, just open two tabs and enjoy!

Project structure and technologies used

As a quick recap, this project has been realised using Asp.Net MVC, HTML5 (Canvas), Javascript, C#, SignalR for client/server real-time communication and qUnit for javascript unit testing.

PongR is a multiplayer HTML5 game, and this means that the client itself is doing a good amount of work.
The engine is replicated both on the server and on the client, as we have seen in the first part of this article when I talked about the server authoritative model + client side prediction that force us to add logic onto the client.
In the server this logic is built into a class named “Engine” and later on we will go into more details.
In the client this logic is built into a javascript module named PongR.

Javascript  code structure and unit testing

Most of the Javascript client side code is contained into a folder called Js, whose structure is shown below:

the module PongR is inside the file PongR.js. This module exports a public prototype with two public functions needed to setup an instance of the game and to connect to the server.

pongR.PublicPrototype.createInstance = function (width, height, username) { … }
pongR.PublicPrototype.connect = function () { … }

Furthermore the public prototype exports also a set of functions that have been unit tested using qUnit [www.qunitjs.com].
qUnit is very easy to use and the way I set it up is very neat: you can find all the details in this awesome article http://freshbrewedcode.com/jonathancreamer/2011/12/08/qunit-layout-for-javascript-testing-in-asp-net-mvc3/
Basically what you get is an easy way to share certain pieces of the tests layout in an ASP.net MVC3 application, with the possibility to have all the links to start your different tests grouped into one HTML page, being able to start them with just one click.
The downside of doing things this way is that the functions we want to unit test need to be visible from outside the module. In order not to pollute the public prototype too much, the module exports a UnitTestPrototype object, which will contain the references to the functions that I want to unit test.

var pongR = {
    PublicPrototype: { UnitTestPrototype: {} }

All the unit tests are contained into PongR_test.js.
A quick example:

And when runned, this is what you get:

Finally, I’m going to talk about RequestAnimationFrameShim.js later in the article, when I’ll focus on the Canvas element.


Other than what we already saw, this module defines several View Model, related to objects that needs to be simulated. Below we can see a basic diagram of the objects and their connections:

The main object here is clearly Game, as it contains the whole state of a match.
Settings is another interesting enough object, it holds a few configuration variables that are mostly used for client prediction and interpolation (I will cover this topic later on in the post).
These models are widely used by the client logic: for example the physics update loop directly modifies these models at every simulation step.
And this leads us to discuss about the client side update loops.

Client side update loops

Let’s restart the flow and let’s see more in detail what is happening:
when a client enters its username and posts the form, the system redirects the client to the page where the actual game will be displayed. This page will load all the necessary javascript libraries and modules, as well as PongR, and will then perform this piece of code on the document onready event:

createInstance sets up the basic configuration of the game and creates the variable that will host the SignalR object, pongR.pongRHub, and all related callbacks.
Once the SignalR object has been correctly populated, we can invoke the .connect() function on PongR, that will start the SignalR connection and on success we invoke the joined() function, which will be where the server will process the client.
We need to have something after start() because in the server side handler the round trip state is not yet available.
When 2 players are connected and waiting, the server sends an init message to both clients that is handled by the client by the following callback:


This code initiliases a new Game, the canvas on which the game will be drawn on, an empty list of server updates that will be received throughout the game and the default delta time set to 0.015 ms that corresponds to 66 fps, a keyboard object, which is a slightly modified version of the THREEx keyboard library that I edited to serve my purposes here, and draws the initial scene (the field, the players and the ball).
After completing initialisation, we can perform a 3 seconds countdown so that the match doesn’t start all of a sudden and the players are not yet ready.
At the end of the countdown the startGame function is invoked.
This function is very important because it starts the two client loops responsible of handling the game inputs and rendering.

function startGame() {

Client side loops

Client physics update loop

Exactly as the server was running a physics update loop, the client is also running a similar loop.
This loops interacts with and modifies directly the View Models that I described earlier.

function startPhysicsLoop() {
    physicsLoopId = window.setInterval(updatePhysics, 15);

This loop runs every 15msec and is responsible for

  • updating at each round the delta time, used to compute the movements of the players
  • updating the position of the client
  • updating the position of the ball
  • checking for possible collisions between the ball and the objects of the game, players and ball. If a collision is detected, than the position and the direction of the ball are updated as well.


Despite the fact that the source I used to create this project puts the collision-checking code into the client update loop, I moved it inside the physics update loop for simplicity. This is obviously not an ideal solution if you want to play sounds on collisions, for example, given that the sound should be played by the update loop.

Client update loop

This loop, unlike the physics loop, is scheduled using a function recently introduced into modern browsers, RequestAnimationFrame.

function startAnimation() {
    requestAnimationFrameRequestId = window.requestAnimationFrame(startUpdateLoop);

You can read in detail about this function here  and more here  .
Basically instead of using setTimeout or setInterval, we tell the browser that we wish to perform an animation and requests that the browser schedule a repaint of the window for the next animation frame. Reasons why RequestAnimationFrame is better than old style setTimeout and setInterval for drawing purposes are clearly stated in the above link, but I think it’s important to quote them here:

The browser can optimize concurrent animations together into a single reflow and repaint cycle, leading to higher fidelity animation. For example, JS-based animations synchronized with CSS transitions or SVG SMIL. Plus, if you’re running the animation loop in a tab that’s not visible, the browser won’t keep it running, which means less CPU, GPU, and memory usage, leading to much longer battery life.

Because this function has been recently introuced, it may happen that some browser still don’t support it and that’s the reason of that RequestAnimationFrameShim.js file that we saw at the beginning. It’s a piece of code found on Paul Irish’s blog aticle mentioned above, so credits go to him.
Let’s see the code:

Initially I check that we are not in a post-goal condition, because after a goal a 3 seconds countdown will be performed and we don’t want to update any of our internal data structures during this time.
If we are not, then we can simulate a new step of the game

At every step the canvas must be redrawn, therefore I can safely clear it.
As this game is fairly simple it won’t impact our performances, otherwise it could have been better to have multiple specialised overlapping canvas, where for example we could use one to draw the background that never changes, and therefore needs not to be cleared & redrawn at each step, and so forth…
Furthermore, I need to process client inputs (if any) and accordingly update a meta-structure that contains a list of commands (“up”/”down”). This meta-structure will then be used by the client physics loop and converted in movements.
Every input processed at each loop is stored in a list of commands (pongR.me.inputs) and assigned a sequence number that will be used when the server will acknowledge already processed inputs. For example, if the server acknowledges input 15, then we can safely remove from the buffer all inputs with sequence number equal to or lower than 15, and reapply all non yet acknowledged inputs (remember the client side prediction model?).
Every input is packed and immediately sent to the server to be processed.

if (!pongR.settings.naive_approach) {

function interpolateClientMovements is a bit tricky and you can read the code by yourself for a better understanding (or even better you can check the blog article where I took this from), but basically it is trying to interpolate the different positions of the opponent in time so that at each redraw its movements will result more continuous and natural to the eyes of the player.
Imagine that the opponent is currently at position (50,50) and then finally we receive its new position at (50,100), if we naively assign this new position to the opponent, what we will see on the screen is a big leap from last frame and it’s obviously something we don’t want.
I have to say that my implementation is not working that well at the moment, but the idea is there.
Finally, after having handled all inputs, I can draw the new frame by drawing each object on the screen.

Server authoritative model in practice

Each time the server runs its own update loop, the clients receive an update packet.
Each client is then responsible for processing it and updating its internal structures so that the next time the update loops will run, they will see an updated snapshot of the game as dictated by the server.
The function responsible to handle all of this is the SignalR callback updateGame.
Let’s see it in detail:

As I mentioned in part 1 of this blog article, it’s the server responsibility to simulate game state changing events, and a goal event is one of this kind!
This should clarify the meaning of the first lines of code: the client only knows that a goal happened because the score changed!
Then, based on this condition, we need to perform two different tasks:

  1. If one of the two players scored, we need to update the scores (both internally and on the screen), reset the positions of all the objects drawn on the screen, reset the state of the keyboard object (we don’t care of all the keystroke pressed after a goal!) and finally perform a countdown that will start the match once again.
  2. Otherwise
    1. We need to apply client side prediction to update our client position, re-processing all those inputs which have not been acked by the server yet
    2. If we are not using a naive approach we do not directly update the other player position, but we simply update some of its internal properties and then we push the just received update packet into the updates buffer, so that it will be used in the update loop for interpolation
    3. We update the information related to the ball  object

It is interesting to note that the updates buffer is not infinite and we limit it to cover 1 seconds of server updates.

Final considerations and next step

This was my first attempt at creating a game and adding multiplayer didn’t make the task easier for sure!
The graphic is really basic, the game itself is not that entartaining, the network lag is clearly affecting the user experience mostly due to a not optimised networking code and to the impossibility of using WebSockets (AppHarbor doesn’t support them yet), but nevertheless it was very funny and I learned plenty of stuff while working on this project.
I have to say that offering the clients a seamless game over the wire has probably been the hardest part of it, and I’m sure there are things which are not working like they should in my code.
Also I think that Asp.Net MVC doesn’t offer the best in class experience to realise this sort of web app (as expected), whereas I see much more fitting Node.Js because of its event-driven nature: if you think about it, almost everything happening in a game can be seen as an event.
Last but not least, using a single codebase and a single language can greatly help to speed up the process.
I couldn’t cover everything I wanted to in these three posts, they are already monster size, so I encourage you to clone the repository and dig into the code to find everything out (like for example delta-time implementation and time synchronisation).
In the near future I would like to rewrite this project entirely in Javascript using Node.Js and, enhancing the user experience ameliorating the graphics using sprites, making the game funnier (e.g. possibility to use bonuses), adding sounds, upgrading SignalR to 1.0 etc…


That’s all about PongR, I hope this can help someone


PongR part 2: server side


Heads up!

The blog has moved!
If you are interested in reading new posts, the new URL to bookmark is http://blog.valeriogheri.com/


This is part 2 of “PongR – my first experience with HTML5 multiplayer gaming”  (https://thewayofcode.wordpress.com/2012/11/05/pongr-my-first-experience-with-html5-multiplayer-gaming/)

Code and Demo

As always, the code is fully published on github [https://github.com/vgheri/PongR] and a (boring!) demo is available at http://pongr-1.apphb.com . If you don’t have anyone to play with, just open two tabs and enjoy!
Following a screenshot of the game:


Initial countdown before the game starts

Project structure and technologies used

As a quick recap, this project has been realised using Asp.Net MVC 3, HTML5 (Canvas), javascript, C#, SignalR for client/server real-time communication and qUnit for javascript unit testing.

PongR is a multiplayer HTML5 game, and this means that the client itself is doing a good amount of work.
The engine is replicated both on the server and on the client, as we have seen in the first part of this article when I talked about the server authoritative model + client side prediction that force us to add logic onto the client.
In the server this logic is built into a class named Engine and later on we will go into more details.
In the client this logic is built into a javascript module named PongR.

What we’ll see

While writing this second part of the post, I realised that tackling both the server and the client side in one single post will result in a wall of text.
Therefore in part 2 I will start covering the server side code, that is the authoritative source for our game.
Finally in part 3 I will cover the client side code, and this will allow me to dive deeper into HTML5 canvas, qUnit and so on.
So, let’s start!

Connecting to the server

I think that an intuitive way to dive into the code and understand it, is to to navigate the flow of the system: let’s pretend there are no matches currently played on the server, and that we are a client that lands on PongR page.
When the client enters its username and posts the form, the system redirects the client to the page where the actual game will be displayed, PongR.cshtml. This page will load all the necessary javascript libraries and modules, PongR comprised, and will then perform this piece of code on the document onready event:

The Joined() method is inside the PongRHub class, on the server, and will accomplish the following tasks:

  1. Add user to list of connected users
  2. If waiting list is empty add user to waiting list
  3. Else find an opponent (first in the waiting list) and remove him from the waiting list
  4. Create room and assign both users
  5. Create a group for this room
  6. Setup match (playRoom Id, initial ball direction, player on the left and right etc…)
  7. Notify the group the match can start
  8. Add the game to the list of games that the Engine must simulate

Now, the first time I implemented this method I had a problem in between point 5 & 7: sometimes the clients didn’t receive the signal from the server to setup the match.
So I went back to the project’s wiki and I browsed the source code and I understood where the problem lies: when the server invokes Groups.Add(), it sends a signal to the client and notify it about its appartenance to a certain group.
Therefore sometimes I had race conditions where the second signal arrived before the first one, causing the client to drop the message.
I quickly and roughly fixed the issue adding a Thread.Sleep() call after the Groups.Add calls.
Here is the code for Joined():

I could have found a more elegant solution adding one more call after the joined to split the work, but the focus of this project is not SignalR per se, so I guess it’s ok anyway…
Next I signal clients that the match can start along with the game options, like initial direction of the ball, players info etc., and finally enqueue the game on the server so that its state will start to be processed.

// sends a message only to the clients belonging to the group, invoking the function setupMatch() that is part of the PongR module.

// Adds the freshly created game to the list of games to be simulated by the server

This is where our story splits in two parts: we now simultaneously have the clients AND the server playing the game.
How does it work? Again the theory behind what follows is taken from http://buildnewgames.com/real-time-multiplayer/ , which in turn comes from Valve’ Source Engine, I just adjusted it to my needs.
Basically both the server and the clients run two loops, and we call them:

  1. The physics update loop
  2. The update loop

Now these two loops do different things and run at different speeds depending if we are on the server or on the client.
Before moving on talking about the loops, it might be useful to describe what kind of messages the client is sending over to the server.
In PongR a client can only move up or down, and a sequence number is associated to each command to uniquely identify it.
So our payload will contain the following info:

  • the id of the game being played
  • the client id that just sent the command
  • the command
    • a sequence number
    • a string identifying the type of movement: “up” or ”down”

The meaning of the sequence identifier is related to the Client-side prediction mechanism and the input buffer that both the server and the client keep. Here are the steps:

  1. The client moves and stores into its buffer the input along with its id
  2. The client sends the input to the server
  3. The server enqueues the input into a buffer
  4. When the server processes the input, it removes it from the buffer
  5. When the server update loop runs (will see it later in more detail), it notifies the client of the latest input that has been processed
  6. The client can remove from its buffer all the input with ID lower than or equal to the one just ack’ed


Update Packet

Update Packet with sequence identifier acknowledgement

The payload size could be slimmed down by a lot, but that is again another story (for some ideas, take a look here: [www.buildnewgames.com/optimizing-websockets-bandwidth ] )
So let’s start with the server, the authoritative source of our game.

The server loops

To run the loops at fixed intervals, I used the System.Timers.Timer object, and I set them up like this in the Global.asax:

In the second gist we also see the handlers that will run when the Elapsed event is raised.

The server physics update loop

The server physics update loop runs around 60 times per second, that is every 15 msecs.
Its job is to update, for every tick of the simulation, players and ball position based on the inputs received by the clients and on the law of the physics of the game.
Let’s see what a loop round looks like:

MovePlayer() and UpdateBallPosition() are relatively simple so I won’t show them here.
Shortly, the former modifies the Y coordinate of the player and its direction (up/down), based on the inputs that it has received, while acknowledging every processed input sequence number, and the latter simple modifies the (X,Y) coordinates of the ball based only on its angle (that implictitly gives us the direction). For every step of the simulation, both the ball and the players (if any input arrived) will move by a fixed amount of pixels.
Browsing the code you will notice that both the player and the ball movement are based on something called DELTA_TIME. This is related to the concept of framerate independence and I invite you to read more about that here http://www.scirra.com/tutorials/67/delta-time-and-framerate-independence/page-1.
Briefly, quoting the link above:
“Framerate independent games are games that run at the same speed, no matter the framerate.”

Moving on to

var goal = CheckGoalConditionAndUpdateStatus(game);

we see that it’s the server  who is checking if we have a goal situation, and if it’s the case, we update the score of each player (important, and later we’ll see why), add the timestamp of this event to a collection of goal timestamps and then we proceed to restart the game after a goal, that is really resetting positions of players and ball to initial state and choosing randomly the new initial ball direction.
I’m storing the goal timestamp because on the client we provide visual feedback of a goal, running a countdown after each so that the user has the time to understand what is going on and get ready for the next ball to play. During the countdown the ball won’t obviously move, therefore the server must not continue to simulate as well during this time.
We can see this check implemented in the outer physics loop, that is the method actually invoked by the Time elapsed event handler:

That’s it for the server physics update loop.

The server update loop

The update loop runs every 45 msecs, around 22 times per second, so at a much slower rate then the physics loop.
It’s all about finding a good trade-off between accuracy of the simulation (faster update rates) and network usage and performance (slower update rates).
The update loop job is to send the updated state of the game to the right clients.
To do that, I used an external class, called Notifier, which has one public method that will use SignalR to invoke a javascript function on the client even if we are outside of the context of our Hub. This is a very cool SignalR feature, as it allows for a lot of flexibility. Let’s see how it’s done:

The following line will send the message to the two clients that are part of the SignalR group



That’s it for part 2 of this article. We have covered the connection process and the server update loops. We have seen all the workarounds used to cope with SignalR Groups and to skip simulation when one of the player scored in a match, so that the clients can display a countdown before restarting the match.
Part 3 will be the last and we’ll take a look at the client side code, even though you can start by yourself cloning the repository on github.

ChatR: just another chat application using SignalR


Heads up!

The blog has moved!
If you are interested in reading new posts, the new URL to bookmark is http://blog.valeriogheri.com/


Update (30 November, 2012): David Fowler (SignalR co-creator) has made ChatR into an example application downloadable via Nuget to show SignalR beginners how to quickly build a chat web app.
He forked the project on GitHub and updated the code base to the latest version of the library, 1.0Alpha2, and then sent me a pull request that I accepted and merged into the master branch.
Therefore the code that you see now in the latest commit on the master branch is slightly different than the one shown in this post, but this is not a problem, you just need to go back in time in the history of the commits to find exactly what is shown here if you really want to, otherwise just dive into the new code!

Update (17 November, 2012): this blog article is related to version 0.5.2. In these days the SignalR team is working on version 1.0 and has released an Alpha. There are quite a lot of significant changes in the API, but the concepts at the basis still apply.
I hope to be able to post an update article when 1.0 is released.

There’s a lot of buzz these days around SignalR (http://signalr.net/) and more in general around real time communication techniques for the web (http://www.webrtc.org/).
There are many scenarios where real time can be embedded in web applications in a way that is actually useful for the user, but the most easy to understand scenario is the good old chat 🙂
That’s why today I’m going to write about…


A chat web application! Yes, I know it’s not the most original example, but it’s still a good starting point to excercise the fundamentals of the framework.
The user will be able to choose a username and then join the (single room) chat, where he/she will be able to chat with the others and see a list of currently connected users.
This list will obviously update itself everytime someone joins or disconnect the chat.

Source code and demo

As always the code for this tutorial is published on GitHub at https://github.com/vgheri/ChatR
A working demo is deployed on the fantastic AppHarbor at http://chatr-1.apphb.com  (if you want to run a test, simply load up new tabs… SignalR is not relying on Sessions so it will be safe). 


This project relies on Asp.Net MVC 3 for the general architecture and the basic client-server communication.
As anticipated, I’ll be using SignalR for real time client-server communication, Twitter’s Bootstrap for basic UI layout and CSS and Knockout Js (knockoutjs.com) to automatize the view.

Before starting, I’d like to spend a few words about SignalR: it’s growing up as a solid library to use in order to build production code and it’s dead easy to use (https://github.com/SignalR/SignalR/wiki) once you grasp the fundamentals (which I’ll cover later on). It not only gets the job done, but also sports an awesome client-server async communication pattern, that makes really easy to invoke methods from Js to C# and viceversa (there is even someone who proposed to use it for general purpose communication http://www.novanet.no/blog/yngve-bakken-nilsen/dates/2012/7/clean-up-your-mvc-app-with-signalr/)
If you are interested in understanding more about the internals, I suggest you clone the repository on GitHub (https://github.com/SignalR/) and read something like http://ayende.com/blog/93185/reviewing-signalrndash-part-ii.


This application will feature a 1-click process to join the chat:

Step 1: landing page with a form to enter username
Step 2: chat page

The landing page is really simple, just a few text elements and an HTML form with an input text and a submit button that will trigger a HTML POST handled by the server via a MVC action.


I’m going to use 2 objects as Domain models and 1 repository object to store users currently connected to the system.
Let’s see them briefly:
ChatUser has two properties, Id and Username. The former uniquely identifies a client during a session and is assigned by SignalR.
ChatMessage is super easy and has a minimal set of properties: username (I could have used the ChatUser object, but because I’m displaying just a username and not the user id, I chose to transfer the minimum set of information), content and timestamp.
InMemoryRepository implements the Singleton pattern and helps clients retrieve the list of users.

Basic UI structure

Super simple and clean: a title bar on the top of the page that holds the name of the app, a container on the left that holds the usernames of currently connected users, a container, side by side with the previous one, that holds the chat messages and below an input box to enter a message with a submit button.
All the client-server communication round-trips here are handled by SignalR.
To dynamically update the UI, I’ve used Knockout Js and its data-binding declarations.

Javascript namespace and Knockout view models

I chose to create a separate Js file to declare a namespace and the Knockout viewmodels.
Therefore I created a separate folder called “Js” and a javascript file called chatR.js.
The code is pretty straightforward, as you can see:

The rest of the javascript code is inside chat.cshtml as I needed to access the Model binding engine to retrieve the username chosen by the user.


Server side code

Let’s start with the server side part of SignalR.
Do  you remember what I mentioned earlier in the post, that this library sports a great communication pattern that makes really easy to call C# methods from Javascript and viceversa? Well, the C# methods that we can call from the client side are those declared (as public) in the so called Hub.
What is a Hub? Well, a Hub is an abstraction that, to cite the Wiki,  “provides a higher level RPC framework over a PersistentConnection. If you have different types of messages that you want to send between server and client then hubs is recommended so you don’t have to do your own dispatching”.
SignalR offers two options to build a RTC app, leaving to the developer the choice between two built-in objects: Persistent Connections and Hubs.
It took me a while to fully understand what are the differences between these two, and why choose one over another.
Basically Hubs allow you to dispatch whatever object you want to the server, taking care of JSON serialization and deserialization, integrate model binding and are easier to setup, as you won’t have to write additional code to manually register additional routes (the SignalR specific routes). (You may want to read this question on SO, with words from David Fowler, creator of SignalR:  http://stackoverflow.com/questions/9280484/signalr-why-choose-hub-vs-persistent-connection).
I think it’s pretty safe to say that if you are writing a common web application or .Net application, you’ll be fine with Hubs.

N.B It’s imporant to note that Hubs are created on a “per request” basis, so no static stuff in it should be declared.

To start with, create a Hubs folder and create a new class that derives from Hub.
Here I called mine “ChatHub” and I defined the methods that will be used by the clients:
GetConnectedUsers: retrieves the list of currently connected users
Joined: fired when a new client joins the chat. We add the user to the repository and notify all the clients (even the newly joined) that this new client connected.
Send: broadcasts the message to all the clients (plus some extra work, like formatting links and youtube urls embedded in the messages, showing them as active links and embedded video player respectively. This part is mostly taken by the Jabbr codebase, thanks again David Fowler 🙂 )

Here’s the code:

As you can see, there’s something more: this class implements an interface called IDisconnect, part of SignalR, which allows us to handle the Disconnect() event fired when a user leaves the application. Again what we do here is remove the user from the repository and notify the other clients of the event.
There is another interface, called IConnected, that allows us to catch connection events like Connect and Reconnect, but I chose not to use them because unfortunately (at least in Connect) the round-trip state (see https://github.com/SignalR/SignalR/wiki/SignalR-JS-Client-Hubs) is not available, therefore I cannot access the state set on the Hub with information like the username set on the client that caused the event to fire.
Later on I’ll explain in more detail with code.
This is also the reason why I have a Joined event handler, because I need an event handler, fired after the Connect event, where I can access the round-trip state. Just for the record, Jabbr uses the same philosohpy, not implementing IConnected.
Finally, as you can see almost all of the methods have a void return type, but one: GetConnectedUsers has a ICollection<ChatUsers> return type and this means that only the client invoking the method will get the data back and furthermore the library will handle the JSON serialization and deserialization of the collection.
Alternatively I could have used Caller.callback and set a void return type to the method.

Client side code

On the client side, the first important thing to note is the order of the script references:
1) jQuery 2) jQuery.signalR 3) <script src=”signalr/hubs” type=”text/javascript”></script>

The last one is important because navigating to /signalr/hubs will dynamically generate the script based on the hubs declared on the server. Each hub on the server will become a property on the client side $.connection, e.g. $.connection.myHub.

Let’s see now how to hook up the client and the server:

It’s important to note that all Hub names (methods and class name) are in  camelCase, so for example
var chatHub = $.connection.chatHub;   is creating the proxy to invoke server code.

The next statement,
chatHub.username = currentUser.username;
is setting the round-trip state on the Hub, in this case I’m setting the username so that it will be accessible from the server and I’ll be able to add this user to the list of currently connected clients.

Following we have client-side event handlers, as invoked by the server (remember? Clients.onMessageReceived(message); )

We also apply knockout bindings so that the UI will start updating itself as the ViewModels change.
Finally we have the code block to start the SignalR connection and invoke two Hubs method:

// Step 1: Start the connection
// Step 2: Get all currenlty connected users
// Step 3: Join to the chat and nmotify all the clients (me included) that there is a new user connected
            .done(function () {
                              .done(function (connectedUsers) {
                                   ko.utils.arrayForEach(connectedUsers, function (item) {
                                      users.contacts.push(new chatR.user(item.Username, item.Id));
                               }).done(function () {

method $.connection.hub.start provides two callbacks, done and fail.
So in the code above I’m saying that if the connections is successfully estabilished, we can now try to retrieve the list of connected users and if this worked too, we can notify all the clients that this new client connected via chatHub.joined().
At this point the round-trip state will be available and therefore we will be able to register a new User, along with its connection ID and username.

One final note: by default DateTime is serialized by SignalR using ISO8601 format (http://en.wikipedia.org/wiki/ISO_8601), which is ok to parse for Chrome and latest browsers, but, guess what?, not for IE 9 and older versions. That’s why I had to search the web for a nice and quick solution, that you can find in the source code on GitHub.

Useful links

ChatR on GitHub: https://github.com/vgheri/ChatR
ChatR on AppHarbor: http://chatr-1.apphb.com
SignalR Wiki: https://github.com/SignalR/SignalR/wiki/Hubs
Hubs vs Persistent Connections: http://stackoverflow.com/questions/9280484/signalr-why-choose-hub-vs-persistent-connection
Useful tutorial: http://www.amazedsaint.com/2011/11/introduction-ksigdo-knockout-signalr-to.html
Jabbr on GitHub: https://github.com/davidfowl/JabbR

Image voting system using jQuery, Bootstrap and Asp.Net MVC 3, or how to create a jQuery plugin


Heads up!

The blog has moved!
If you are interested in reading new posts, the new URL to bookmark is http://blog.valeriogheri.com/


I was working on a project were one of the requirements was that users had to select a set of images out of a bunch of them, to be furtherly reviewed and commented.
While working on the implementation, I had a sudden idea: I’m going to write for my blog a simple image voting system packed as a jQuery plugin! And so iLikeIt! was born.
The link between the project and the blog article has been Twitter’s Bootstrap, and precisely the Carousel component, as I was using it to iterate between the images.

Live demo and source code

I’ve always wanted to be able to offer live demos of my web applications, and I finally found a fantastic (free) app hosting, appharbor, which also integrates perfectly with Github, so that when I push my changes to Github, it automatically pushes them to appharbor and the new version gets immediately and automatically deployed
on the server!
Click to reach the live demo of iLikeIt!
As always my code is hosted on Github and is free to fork, download etc… (link).

iLikeIt! Screenshot

iLikeIt! screenshot

What iLikeIt! is

iLikeIt! is a simple image voting system that can be used as a classic jQuery plugin, using Bootstrap and jQuery (of course) as base components, and Asp.Net MVC 3 as the web framework to handle server side computation, even though the server side part is really less important here.
The vote is visually expressed with classic “stars” icons, and is 5-stars based.

UI and UX

The idea is to keep the page simple, focusing only on the images and the voting system.
The image rotation is based on a carousel styled component, and to cast a vote a user simply has to mouse over the image and the panel to vote will fade in in the middle of the image, allowing the user to rate the image by clicking on a star.
After the user has casted his vote, the system will display the average rating for the image and won’t allow the user to change his vote (or not until the user refreshes the page… ehi I told you this is a simple system, but you’re free to modify it by cloning and adapting the source code to your needs!).
I know mouse over is not good this days due to mobile experience, and that’s why I will try and cover this topic (and fix the design) in one of my next post.

How to

The HTML part

I wanted the plugin to be dead simple to use, with a jQuery classic approach such as $(“…”).myPlugin().
In the following Gist you can see the HTML code of the View that is needed to use iLikeIt!

The main idea is that from the HTML point of view, all that is needed is to setup the Bootstrap’s Carousel component filled in of all the images you need (if you don’t know about Bootstrap and how to setup a Carousel, please read this http://twitter.github.com/bootstrap/javascript.html#carousel ).
It is very important to specify the IDs of the images, as they will be posted to the server to identify the image being voted!
Then, at the bottom of the page, in the script portion, we need to initialize the plugin simply writing

As you can see I’m passing an object called options to the plugin, which contains the URL used for Ajax POST actions to the server.

The javascript part

The baisc idea is to display a small div in the middle of the carousel, between the controls for sliding the images, where we display the star icons and the rating description, so that the user is facilitated when voting.
Here is the js file, which I’ll be covering in more detail immediately after:

The code is contained within an anonymouse closure, thus granting privacy and state throughout the lifetime of the application. You may notice that at the top there is a small bit of code commented out, that is because at the beginning I had decided to use the Module pattern (http://addyosmani.com/resources/essentialjsdesignpatterns/book/#modulepatternjavascript and http://www.adequatelygood.com/2010/3/JavaScript-Module-Pattern-In-Depth), but then I chose to simplify the usage of the plugin and changed my mind for anonymouse closure.
The usage of iLikeIt! as a jQuery plugin is possible because of the following code block

where I add iLikeIt to the set of functions that is possible to access using jQuery “$” notation.
When called, this function creates and injects the HTML to display the voting panel into the Carousel, and then hooks up all the events that are needed, like mouseenter for the voting panel, mouseover, mouseout and click for the star icons.
Whenever a user goes with the mouse over a star icon, a mouseover event will be triggered and handled by the function displayRating

which retrieves the active image (using the “active” class attribute that Bootstrap places on the current carousel item) and checks if the image has not yet been voted (more on that later). If that’s the case, then the this function is going to replace all the necessary empty icons with the full star icon, thus providing a visual feedback to the user, along a short text description of the current vote. To easily do this I enumerated the IDs of the star icon with a crescent numbering: the first, that corresponds to vote “1”, has an ID = “1” and so on till 5.
When the user has made up his mind, he can click on the icon that better expresses his thoughts about the image and the mouse event “click” will be triggered and handled by the function registerVote

This function performs an Ajax POST to the server, sending out the ID of the image and the string representation of the vote.
On success, we need to mark this image as “already voted”, and to do this I’m using the jQuery function “data()”
votedImage.data(“vote”, msg);
where msg holds the average rating that is sent back with the server response, and this value is displayed to the user by calling the preloadRating function.
I think this covers pretty much everything that is important.
The server side code is really short and not significant, but should you want to take a look at that, you can download the source.


We have seen how to create a simple jQuery plugin to build a simple image voting system, and how to use the anonymous closure construct to isolate and organize your javascript code.

Have fun,


Architecting a MVC web application with Knockout


Heads up!

The blog has moved!
If you are interested in reading new posts, the new URL to bookmark is http://blog.valeriogheri.com/


One of the most recurring questions I see on StackOverflow (for example here) and the likes is about best practices for architecting MVC web applications and about integration with “this” or “that” javascript framework without messing up the whole design.
So I decided to share my thoughts on this, because I know how confusing and hard it can be, especially for beginners, to put all the pieces of the puzzle together.
I chose to take Knockout as an example because I like its MVVM approach and the learning curve is not so steep.
Finally, as always, the foundations of this article lie in my own personal experience mixed with all the books and articles I read, therefore this article might be quite simplicistic or naive to someone with much more experience than me, or maybe someone else will just disagree.
In every case, feel free to express what you think!


Asp.Net MVC and similar frameworks are cool and powerful, they often offer nice and easy predefined project structures and convetions, so why bothering making things more complex?
Well, conventions are surely great, but when it comes to projects that have more than a few classes, views or controllers, or projects that relies on other teams work, or simply projects that want to adopt a more structured architecture, the basic project template just isn’t flexible enough.
MVC is an architectural pattern about the Presentation layer and how it connects to the Application layer, but what about the rest of the application? How do we further logically divide the software? And how do we connect these logical parts?


The standard solution to the questions mentioned above is to use a layered architecture, few and fairly standard in their definition. To enforce well known principles like high coesion, do not repeat yourself etc, each of these layer specialises in a particular aspect of the software.
Each layer speaks a language, usually (with some exceptions, as we will see later) the language of the domain the software is related to, and uses layers beneath to fulfill some task.
The general diagram for the architecture I will talk about is the following:



The focus of this article is on the Presentation Layer, its integration with Knockout and the connection between the Presentation and the Application layer.

View Model

By definition, the M in MVC stands for Model, but what is exactly the Model we are talking about? The Asp.Net MVC doesn’t constraint the developer to define what M stands for, it could be a Domain Model object (using any kind of pattern, Active-Record, Entity, Value etc…) or it could be something else.
In the solution proposed in this article, the M stands for View Model.
This View Model is not to be confused with the Domain Model, that is the core language of the real world problem our application is trying to solve.
It is instead the language of the Presentation layer, used by Views (our HTML pages) and the Controllers (can be code-behind or Controller objects).
The MVC default project structure that we find in Visual Studio, for example, with its “Model” folder can easily mislead us on this, leading us to mix both worlds not even being aware of that!

What a View Model is

A View Model object is crafter around a specific View and should contain only the elements the View needs to display and optionally validation rules.
Every View should be strongly typed to a View Model object, so that you don’t have to mess up with loose strings or similar, being able instead to work with the MVC scaffolding engine, strongly typed variables and all the HTML helpers while building up your View.
I think it is a good practice to name the View Model object after the View and the specific action, for instance EditCustomerViewModel or CreateCustomoreViewModel, so that it’s easy to do the association between the View and the View Model object.
View Model objects often aggregate Domain Model objects or viceversa may map to only a subset of a Domain model object’s properties, and they may also contain View specific validation rules (for example Asp.Net MVC 3 comes with lots of built-in Data Annotation attributes that we can use to decorate classes or properties to express requirements about fields, data format etc…).
Let’s take as an example a page where the user can Create a new customer: we won’t display a field for customer ID whereas in the corresponding Edit page we may display it as a read only field.
This difference is well expressed using two distinct Views and two distinct View Models, each with different properties and attributes that adapt to the page.
It may seem like a lot of additional work to write two different Views and View Models, but it will pay you back in terms of ease of maintenance and clarity of intents when sharing the work with other people.
Furthermore by following this approach our Views contains no logic to handle different cases like “Edit” and “Create”, they just worry about data visualization like they should.


Lots of javascript framework that help developers delivering a dynamic and interactive user experience are available these days, automating the task of writing repetitive javascript code to hook up DOM objects and events handlers, at the cost of the initial learning curve and the additional code to setup it.
I chose Knockout, which brings the MVVM pattern to the web, because the declarative bindings. are easy to understand and use, it’s easy to extend, it’s very well documentend, the website is full of useful examples and the additional amount of code to setup the framework is not too much.
Knockout requires the developer to write a javascript View Model (from now on referred as Knockout View Model) per each View we want to use it in and the declarative data bindings on each DOM element we want to observe. Once this is done, Knockout can keep track of the state of the controls displayed in the page. Whenever the user will change the state of whatever “observed” control in the page, the underlying Knockout View Model will automatically update itself.
This feature is killer for example if you’re writing a Single Page Application: one full load when the user requests the page for the first time, and every other interaction is an Ajax call where we already have the page state ready for use in javascript.
At this point you may ask: another view model? Didn’t we already have a Domain Model and a View Model?
Yes, that’s true, but every model has its own scope, and the Knockout View Model scope is to contain the presentation display logic and the state of the observed controls.
The View Model is used by the Controller Action that is responsible for loading the View the first time: it will databind the View to the View Model, so that the page is initialized quickly without the need to perform Ajax calls to load data from the server.
If the View is smartly initialised with data coming from the View Model, for example pre-ticked checkboxes, pre-filled textboxes , pre selected item in select list etc… our Knockout View Model won’t know about them unless we explicitely assign every initial values.
One way to do it is by Json encoding the bounded View Model and then assigning each pre-defined value to the Knockout View Model variable containing the observable value.
For example:

var boundedViewModel = @Html.Raw(Json.Encode(Model));
var viewModel = {
selectedCity: ko.observable(boundedViewModel.DefaultCity);

The Application Layer

Also known as middle tier, it works with Domain Model objects, the Repository and other Foundation services, to work out Presentation layer requests.
To be able to communicate, the Application and Presentation layer share the same language, the View Model objects.
If they were part of the Presentation layer, as suggested by the “Model” folder that we find in the default Asp.Net MVC project, the Application would need to have a reference to it to manipulate them, thus creating a circular reference!
To avoid such a problem we create a separate dll containing View Models, referenced by both the Presentation and the Application layer.
It is then the Application layer responsibility to translate from View Model to Domain Model objects and viceversa.
For this task it is possible and strongly suggested to use automated tools to do the mapping for us, such as AutoMapper for .Net (it is also available on NuGet).
By delegating this task to the Application, the Presentation layer is free from any mapping logic and from any reference that is not directly involved in its core business.

Closing thoughts

In this article we have seen a flexible solution to architect a MVC web application by
introducing a new object Model, the View Model, and its rules that together create an ad-hoc language for the Presentation layer that will help us in the task of building elegant front-ends and to an easier integration with javascript frameworks such as Knockout.


Lots of inspiration for this article comes from the following articles:

  1. http://msdn.microsoft.com/en-us/magazine/hh456393.aspx , where you’ll be able to find also more info on the Domain Model and the Repository layer.
  2. http://lostechies.com/jimmybogard/2009/06/30/how-we-do-mvc-view-models/
  3. http://www.methodsandtools.com/archive/archive.php?id=97

KnockoutJS data-bind for a set of drop down lists


Heads up!

The blog has moved!
If you are interested in reading new posts, the new URL to bookmark is http://blog.valeriogheri.com/


In my current project I’m building a Single Page Application using Asp.Net MVC 3, jQuery and KnockoutJS.
As part of the UI, I had to build a part of it where the number of dropdown lists associated to a certain product are not known at design time, as the Model is based on an XML resource.
So I was facing the problem of keeping track of all the selected values (and the state of the rest of the UI as well) for each dropdown and without the possibility to use the MVC Model Binding feature because I had to use Ajax (no form submit and thus page re-loading).
After taking a look at what is currently out there to help the developer in this task, I decided to try knockout.js, a nice MVVM javascript framework, to help me keeping track of the state of the UI without writing lot of javascript code.
I’m not going into the concepts behind this framework, neither into details for beginners because they have a great tutorials on their website and nice documentation too, so I couldn’t do better even if I would.

Let’s see a simple example that shows how I solved this problem (I had to ask a question on stackoverflow to seek help as I was stuck. If you are interested, here is the link)

Nothing special here, the controller is just injecting some dummy data into the ViewData to fill in the drop down lists and give the illusion that the number of menus is not fixed.

        public ActionResult Index()
            var numberOfDropDownMenus = 5;
            for (var i = 0; i < numberOfDropDownMenus; i++)
                var selectList = new SelectList(this.GetDummyItems(i), "Id", "Name", -1);
                ViewData["Options_" + i] = selectList;
            ViewData["DropDownMenus"] = numberOfDropDownMenus;
            return View();


Let’s start with the knockout view model: for this specific page I’m just interested in the selected value for each ddl, nothing else, so my view model will be just as simple as this:

var initialValues = [];
    var n = @Html.Raw(Json.Encode(ViewData["DropDownMenus"]));
    for (var i = 0; i < n; i++) {

var viewModel = {
        selectedValues: ko.observableArray(initialValues)

The above code means that our view model has only one item, selectedValues, which is an observable array of observables (initialValues is in fact an array of observables).

Why not simply use an observableArray? Because we want each item of the array to reflect the currently selected value for a specific DDL, and therefore it must be an observable value so that knockout can automatically update its value whenever the user changes something.

It will be clearer if we look at how we data-bind each DDL to an observable value into the observable array:

@for (var i = 0; i < (int)ViewData["DropDownMenus"]; i++)
    @Html.DropDownList("DropDown_" + i, (SelectList)ViewData["Options_" + i],
                                new { data_bind = "value: selectedValues()[" + i + "]" })

The trick here is to use a positional databinding:

new { data_bind = “value: selectedValues()[” + i + “]” }

If i is 0, this will be evaluated for example as
new { data_bind = “value: selectedValues()[0]” }

The currently selected value for the first DDL will be stored in the first position of the observable array!

User interface and test output

User interface and test output

In the screenshot above we can see that the array is changing accordingly with the changes applied to the UI.
(To show the test output, I used the following syntax: <div data-bind=”text: ko.toJSON(selectedValues)”></div> It’s important to use ko.toJSON since selectedValues contains observables, not simple values)

Then, if we want to send data to the server (and we want), we can do like the following

$(document).ready(function () {
        $("#fakePost").click(function () {
            var viewModelToJSON = ko.toJSON(viewModel); //Serialize the viewmodel
           $.post("/Home/MyAction", { JSONviewModel: viewModelToJSON }, myCallback);

And on the server we can deserialize the string using our own favourite library.
For the sake of simplicity I used the built in javascript serializer:

public JsonResult MyAction(string JSONviewModel)
            var jss = new JavaScriptSerializer();
            var selectedValues = jss.Deserialize(JSONviewModel);
            return Json("Ok");

where ViewModel is a simple C# object useful for easy de-serialization and to communicate with an hypothetic Application Layer

public class ViewModel
        public List selectedValues { get; set; }

That’s all!
Obviously this is a super simplified example, but I hope it helps if someone has to face the same problem as me in the future.



About the mass assignment vulnerability in Asp.Net MVC framework


Heads up!

The blog has moved!
The new URL to bookmark is http://blog.valeriogheri.com/


Following what happened to github in the past days (someone was able to hack a github repository exploiting a Ruby on Rails vulnerability to proof the point that this is in fact a vulnerability of the framework and a very dangerous one) there has been a lot of buzz and discussion in the web about  it and also about Asp.Net MVC framework, if it suffers from the same vulnerability and if it is to be considered a vulnerability in the first place.

What could actually happen using Asp.Net MVC model binding feature is explained very well in this blog article by Josh Bush, so I won’t repeat it.

A good solution to this problem is already offered by the framework, DataAnnotations! I’m using the same ViewModel as in Josh Bush’s example, with an extra row at the beginning:

[Bind(Exclude = "IsAdmin")]
public class User {
    public int Id { get; set; }
    public string UserName { get; set; }
    public string FirstName { get; set; }
    public string LastName { get; set; }
    public bool IsAdmin { get; set; }

By using the Bind attribute, [Bind(Exclude = “IsAdmin”)], we are explicitly asking the framework not to update the value of property IsAdmin when we use the UpdateModel(user) instruction.

So even if the attacker will attempt to change the query string in the URL, the Model Binder will simply not use it for this particular property and your system will be “safe”!


Drag and Drop asynchronous file upload with HTML 5, File API, XMLHttpRequest and Asp.Net MVC 3


Heads up!

The blog has moved!
The new URL to bookmark is http://blog.valeriogheri.com/


Hello everyone, today I’m going to talk about Drag ‘n Drop in modern web applications (someone said HTML5?).
I got interested in this topic because of a project I’m currently working on: we have a page where the user has to upload an Excel file to load some info into the system and instead of having just a page with the old-fashioned input for browsing the filesystem to pick a file and then press submit, we decided it would have been fun & useful to allow the user to drag and drop the desired file into the page, similar to what you can do with Gmail attachments. After googling, I found out that HTML 5 draft specification includes some new cool features that allow us to easily create a system that gets the job done in a pretty straightforward way. There are already a good number of (jQuery and non) plugins out there that do get the job done (in a much more clever way than my demo does), but I think it can be good fun and very useful to learn how to do it yourself first.


I’m going to showcase a simple Asp.Net MVC 3 web app that lets a user drag one image file at a time from the desktop and drop it into a special “drop zone” into the web page. The system will then take care of uploading it to the server and, if upload was successfull, it will display to the user the link to access the uploaded image.
As always all the source code is hosted on github at the following URL: https://github.com/vgheri/HTML5Drag-DropExample

What I’ll use

  • Asp.Net MVC 3
  • HTML 5 DnD API, File API and XMLHttpRequest object to handle drag&drop and async file upload
  • jQuery (version 1.7.1 is the latest version at the moment)
  • Bootstrap for UI widgets

Important note

HTML5 and the FileAPI are still draft versions and as such they are subject to change until the final revision comes out and are not supported in all major browsers.
To see exactly what can be used and what not, take a look at the following two websites: http://caniuse.com/  http://html5please.us/.
All the code you will find below has been tested under Google Chrome 16 and IE 9.
Conceptually we can divide the async file upload operation in two different and consecutive moments:

  1. Drag and drop
  2. Async file upload and View update

Part 1: Drag and Drop

This part is all about creating a webpage with a really simple layout: just one dropbox (HTML5 DnD API) where the user can drop an image.
After dropping the image, the web page will load the dropped file in memory (using JS FileAPI) and will show to the user a table with a thumbnail, some basic information like filename and size and a progress bar to provide feedback to the user about the upload operation.
As you can see in the below screenshot, the page I’m going to build is really simple:
Landing page as displayed by Chrome

Landing page as displayed by Chrome

We can start creating something very simple but not that ugly using Bootstrap (I won’t show the Layout code here, you can download the source on github) and the Index page at the beginning looks something like this:

<form id="fileUpload" action="/Home/Upload" method="POST" enctype="multipart/form-data">

    <!-- Main hero unit for a primary marketing message or call to action dropzone="copy f:image/png f:image/gif f:image/jpeg" f:application/vnd.openxmlformats-officedocument.spreadsheetml.sheet f:application/vnd.ms-excel-->
    <div id="dropbox" dropzone="copy f:image/png f:image/gif f:image/jpeg" class="hero-unit">
        <h2 id="droplabel">Drop zone</h2>
        <p id="dnd-notes">Only images file type are supported. Multiupload is not currentrly supported. Once you will drop your image in the dropzone, the upload will start.</p>
        <table id="files-list-table">
                    <th>File name</th>
                    <th>File size</th>
                    <th>Upload status</th>
                    <td id="td-img-preview" class="tableData">
                        <img id="preview" src="" alt="preview will display here" />
                    <td id="td-file-name" class="tableData"></td>
                    <td id="td-file-size" class="tableData"></td>
                    <td id="td-progress-bar" class="tableData">
                        <div id="progressBarBox" class="progress progress-info progress-striped">
                          <div class="bar"></div>

        <div id="multiupload-alert"class="alert alert-error">
            <h4 class="alert-heading">Warning!</h4>
            <span id="multiupload-alert-message"></span>
        <input id="fileSelect" type="file" name="fileSelect" />
        <p><button id="fallback-submit" type="submit" class="btn btn-primary btn-large">Upload</button></p>
We start to see the first HTML5 thing here with the “dropzone” attribute:
<div id="dropbox" dropzone="copy f:image/png f:image/gif f:image/jpeg" class="hero-unit">
As the draft specification says, it’s purpose is to tell the browser that this element will accept files Drag&Drop.
This attribute can be placed on every HTML element.
Its value specifies which action must be taken upon dropping the file and which MIME types are accepted.
Possible values are:

  1. copy
  2. move
  3. link
I used copy, which indicates that dropping an accepted item on the element will result in a copy of the dragged data, and this value is also the default behaviour.
The second part of the value, “f:image/png f:image/gif f:image/jpeg” indicates the accepted MIME types.
That being said, as of now the dropzone attribute is not currently supported in any of the major browsers, this means that we have to find another way to do it.
Luckily enough, some major browsers support the javascript events related to DnD, like:
drop, dragover or dragexit, so the “logic” will be handled using  javascript!
You can see I also added a classic input type=”file” along with a submit button:
<input id="fileSelect" type="file" name="fileSelect" />
        <p><button id="fallback-submit" type="submit" class="btn btn-primary btn-large">Upload</button></p>
This is there to provide compatibility whenever DnD or FileAPI or async upload (XMLHttpRequest object) are not supported by the browser, as it’s the case for IE9, so we are just fallin back to classic file upload and the user is still able to use the service.
Whenever a fallback is needed, the page displays like the below image
Landing page as displayed by IE9

Landing page as displayed by IE9

So, how do we handle the DnD events and how do we detect if the browser supports FileAPI and async upload?
<script type="text/javascript">
    var fileName = null;
    var fileToUpload = null;

    $(document).ready(function () {
        // init the widgets

        // Check if FileAPI and XmlHttpRequest.upload are supported, so that we can hide the old style input method
        if (window.File && window.FileReader && window.FileList && window.Blob && new XMLHttpRequest().upload) {
            var dropbox = document.getElementById("dropbox")
            // init event handlers
            dropbox.addEventListener("dragenter", dragEnter, false);
            dropbox.addEventListener("dragexit", dragExit, false);
            dropbox.addEventListener("dragleave", dragExit, false);
            dropbox.addEventListener("dragover", dragOver, false);
            dropbox.addEventListener("drop", drop, false);
        else {

    function dragEnter(evt) {

    function dragExit(evt) {


    function dragOver(evt) {


The check happens here:
// Check if FileAPI and XmlHttpRequest.upload are supported, so that we can hide the old style input method
        if (window.File && window.FileReader && window.FileList && window.Blob && new XMLHttpRequest().upload)
The first 4 conditions are related to the JS File API, whereas the last is about the async upload. Then if the check is positive, we hide the classic file upload mode and we add event handlers for the dropbox to handle DnD
var dropbox = document.getElementById("dropbox")
// init event handlers
dropbox.addEventListener("dragenter", dragEnter, false);
dropbox.addEventListener("dragexit", dragExit, false);
dropbox.addEventListener("dragleave", dragExit, false);
dropbox.addEventListener("dragover", dragOver, false);
dropbox.addEventListener("drop", drop, false);
Important note: it is not sufficient to just add a handler for the drop event, as it will not properly fire if the others are not set (like WPF DnD events).
I use the dragover and dragexit handlers to modify the dropbox appearance.
Now on to the drop event handler:
function drop(evt) {

        var temp = $("#multiupload-alert");
        // If there is an alert message displayed, we hide it
        var files = evt.dataTransfer.files;
        var count = files.length;

        // Only call the handler if 1 file was dropped.
        if (count == 1) {
        else if (count > 1) {
            var message = "Multiupload is not currently supported. Choose only one file.";
We retrieve the dropped file in the following line of code
var files = evt.dataTransfer.files;
Then if the user dropped only one file, we can go on parsing
function handleFiles(files) {
        var file = files[0];
        if (file.type.match('^image/')) {
            fileToUpload = file;
            fileName = file.name;
            var reader = new FileReader();

            // init the reader event handlers
            //reader.onprogress = handleReaderProgress; Commented out as we don't really need it
            reader.onloadend = handleReaderLoadEnd;

            // begin the read operation
        else {
            var message = "File type not valid. Only images are allowed.";
What I do here is to select the first (and only) element from the files array and check that it is of type image (remember that the dropzone attribute doesn’t work).
If the type matches, I can instantiate a new object of type FileReader().This interface provides such an asynchronous API.
The FileReader object has several events that can be catched (http://www.w3.org/TR/FileAPI/#event-handler-attributes-section)
event handler attribute event handler event type
onloadstart loadstart
onprogress progress
onabort abort
onerror error
onload load
onloadend loadend
For the purpose of this tutorial I will just handle the loadend event with the following line of code
reader.onloadend = handleReaderLoadEnd;

FileReader includes four options for reading a file, asynchronously:

  • FileReader.readAsBinaryString(Blob|File) – The result property will contain the file/blob’s data as a binary string. Every byte is represented by an integer in the range [0..255].
  • FileReader.readAsText(Blob|File, opt_encoding) – The result property will contain the file/blob’s data as a text string. By default the string is decoded as ‘UTF-8’. Using the optional encoding parameter it is possible to specify a different format.
  • FileReader.readAsDataURL(Blob|File) – The result property will contain the file/blob’s data encoded as a data URL.
  • FileReader.readAsArrayBuffer(Blob|File) – The result property will contain the file/blob’s data as an ArrayBuffer object.
I’m going to use readAsDataURL() so that I can assign the result of the read operation as the source of the image HTML element I use as a preview.
When the read operation is finished, the loadend event is raised and the following piece of code is executed
function handleReaderLoadEnd(evt) {
        var img = document.getElementById("preview");
        img.src = evt.target.result;
        var fileName = fileToUpload.name;
        if (fileName.length > 20) {
            fileName = fileName.substring(0, 20);
            fileName = fileName + "...";
        var size = fileToUpload.size / 1024;
        size = Math.round(size * Math.pow(10, 2)) / Math.pow(10, 2);
        $("#td-file-size").text(size + "Kb");
The key here is the result attribute of the FileReader interface.
Having used the readAsDataURL() method, the specification says that
“On getting, if the readAsDataURL read method is used, the result attribute MUST return a DOMString that is a Data URL [DataURL] encoding of the File or Blob‘s data.”
That’s why I’m able to do the following:
var img = document.getElementById("preview");
img.src = evt.target.result;

The rest of the code is to show basic file info to the user into a tabular format.

Part 2: Async file upload and View update

While the file is being read into memory, I can asynchrounously upload the droppped file to the server using the following code
// Uploads a file to the server
    function UploadFile(file) {
        var xhr = new XMLHttpRequest();
        xhr.upload.addEventListener("progress", function (evt) {
            if (evt.lengthComputable) {
                var percentageUploaded = parseInt(100 - (evt.loaded / evt.total * 100));
                $(".bar").css("width", percentageUploaded + "%");
        }, false);

        // File uploaded
        xhr.addEventListener("load", function () {
            $(".bar").css("width", "100%");
        }, false);

        // file received/failed
        xhr.onreadystatechange = function (e) {
            if (xhr.readyState == 4) {
                if (xhr.status == 200) {
                    var link = "<a href=\"" + xhr.responseText + "\" target=\"_blank\">" + fileName + "</a>";

        xhr.open("POST", "/Home/Upload", true);

        // Set appropriate headers
        xhr.setRequestHeader("Content-Type", "multipart/form-data");
        xhr.setRequestHeader("X-File-Name", file.fileName);
        xhr.setRequestHeader("X-File-Size", file.fileSize);
        xhr.setRequestHeader("X-File-Type", file.type);

        // Send the file
This method is all about the XMLHttpRequest object, which to quote the W3.org spec “allows scripts to perform HTTP client functionality, such as submitting form data or loading data from a remote Web site.”
I use the XMLHttpRequest to send the file in async mode to the server, but before I actually start to send the file, I need to subscribe to a few events which will allow me to give the user feedback about the operation progress.
xhr.upload.addEventListener("progress", function (evt) {
            if (evt.lengthComputable) {
                var percentageUploaded = parseInt(100 - (evt.loaded / evt.total * 100));
                $(".bar").css("width", percentageUploaded + "%");
}, false);
It is important not to confuse the XMLHttpRequest.upload progress event with the XMLHttpRequest progress event, as they serve different purposes.
Having subscribed to this event, I’m able to give feedback to the user about upload operation status.
// File uploaded
        xhr.addEventListener("load", function () {
            $(".bar").css("width", "100%");
        }, false);

        // file received/failed
        xhr.onreadystatechange = function (e) {
            if (xhr.readyState == 4) {
                if (xhr.status == 200) {
                    var link = "<a href=\"" + xhr.responseText + "\" target=\"_blank\">" + fileName + "</a>";
Subscribing to the load event, I’m able to know when all the bytes have been sent.
onreadystatechange is an attribute that represents a function that must be invoked when readyState changes value.
The readyState attribute has 5 possible values
0 Uninitialized
The initial value.
1 Open
The open() method has been successfully called.
2 Sent
The UA successfully completed the request, but no data has yet been received.
3 Receiving
Immediately before receiving the message body (if any). All HTTP headers have been received.
4 Loaded
The data transfer has been completed.
I want to know when the file has been sent and processed by the server
if (xhr.readyState == 4) {
        if (xhr.status == 200) {
                   var link = "<a href=\"" + xhr.responseText + "\" target=\"_blank\">" + fileName + "</a>";
status code 200 means Success, so I can safely read the server response using the responseText property.
I’m using this property to hold the virtual path to the uploaded image, so that the user will be able to retrieve the link to access the remote resource by clicking the link.Now that everything is setup, I can open a connection in async mode (the last parameter), specifying which Controller and which Action will handle the POST
xhr.open("POST", "/Home/Upload", true);
and finally I can start sending bytes
Now all there is left to do is to write the server side code that will receive the file, save it locally and reply to the client with the virtual path to access the resource.
We just have a small problem to deal with: how do we retrieve the posted file when we use XMLHttpRequest.send() method?
HttpPostedFile in this situation will be null, as the content is not held into Request.Files object, but instead it is stored into Request.InputStream as a stream of bytes!
        public string Upload()
            UploadedFile file = RetrieveFileFromRequest();
            string savePath = string.Empty;
            string virtualPath = SaveFile(file);

            return virtualPath;

        private UploadedFile RetrieveFileFromRequest()
            string filename = null;
            string fileType = null;
            byte[] fileContents = null;

            if (Request.Files.Count > 0)
            { //we are uploading the old way
                var file = Request.Files[0];
                fileContents = new byte[file.ContentLength];
                file.InputStream.Read(fileContents, 0, file.ContentLength);
                fileType = file.ContentType;
                filename = file.FileName;
            else if (Request.ContentLength > 0)
                // Using FileAPI the content is in Request.InputStream!!!!
                fileContents = new byte[Request.ContentLength];
                Request.InputStream.Read(fileContents, 0, Request.ContentLength);
                filename = Request.Headers["X-File-Name"];
                fileType = Request.Headers["X-File-Type"];

            return new UploadedFile()
                Filename = filename,
                ContentType = fileType,
                FileSize = fileContents != null ? fileContents.Length : 0,
                Contents = fileContents

I’m not displaying the code for method SaveFile()  and class UploadedFile, you can download the suource code should you need it.

And this is the result:




With this post I just scratched the surface, there’s much more about FileAPI and XMLHttpRequest: for example using FileAPI it is possible to pause and resume an upload as it supports file chunking.
A useful jQuery plugin that leverage the full potential of the technologies shown here is available at http://blueimp.github.com/jQuery-File-Upload/

Custom Unobtrusive jQuery Validation with Data Annotations in MVC 3


Heads up!

The blog has moved!
The new URL to bookmark is http://blog.valeriogheri.com/


MVC 3 introduced what is called Unobtrusive Client Validation. This feature relies on jQuery and HTML5 custom data attributes. It is very powerful and not so hard to use… with the right tutorial to follow 🙂
It’s also very useful because it leverages the power of Data Annotations,  a clean way to express View Model rules in my opinion.
Let’s start the tutorial with a bit of theory (if you’re not interested, you can skip it and go straight to the paragraph “The tutorial”  and download the source code from https://github.com/vgheri/DateCustomValidationExample)

What is a custom data attribute

“As per HTML 5 draft specification a custom data attribute is an attribute in no namespace whose name starts with the string “data-“, has at least one character after the hyphen, is XML-compatible, and contains no characters in the range U+0041 to U+005A (LATIN CAPITAL LETTER A to LATIN CAPITAL LETTER Z). Custom data attributes are intended to store custom data private to the page or application, for which there are no more appropriate attributes or elements. These attributes are not intended for use by software that is independent of the site that uses the attributes. It would be inappropriate, however, for the user to use generic software not associated with that music site to search for tracks of a certain length by looking at this data. This is because these attributes are intended for use by the site’s own scripts, and are not a generic extension mechanism for publicly-usable metadata. Every HTML element may have any number of custom data attributes specified, with any value. JavaScript libraries may use the custom data attributes, as they are considered to be part of the page on which they are used.”

This means that any attribute whose name starts with “data-” will be treated as a storage area for private data.
This allows you to write valid HTML markup (passing an HTML 5 validator) while, simultaneously, embedding data within your page.

MVC 3 + jQuery

MVC3’s new jQuery Validation mechanism links jQuery Validation and Validation Attributes Metadata. The magic happens in the jquery.validate.unobtrusive file that takes all data- attributes and works with them.
To exploit this mechanism, we need to create our own Custom Validation Attributes as we’ll see in this article.

How MVC generates the data- attributes:

The custom data attributes are generated by helpers methods like Html.TextBoxFor(), as it knows already all the Data Anotations that the field needs, and if Unobstrutive setting is true (by default in MVC 3) it will generate all data- that he needs.
For each client validation rule(we’ll get there), an attribute is added with data-val-rulename=”message”. Then, for each parameter in the client validation rule, an attribute is added with data-val-rulename-paramname=”paramvalue”.

The tutorial

In this tutorial we will create a custom validation that checks if a certain date is greater than another date entered by the user in a form. For the purpose of this tutorial we will create a model consisting of one class, Project, that obviously has a start date and an end date. Our goal is to force the user to enter an end date greater than the start date of the project.
To better clarify how to create a custom validator, this tutorial is divided in two steps: first we will provide server side validation, and on top of that we will add client side validation.

Step 1: Server side validation

First we create the model

using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;
using System.ComponentModel;
using System.ComponentModel.DataAnnotations;
using System.Web.Mvc;

namespace DateCustomValidationExample.Models
    public class Project
        public string Name { get; set; }

        public string ProjectManager { get; set; }

        [DisplayName("Start date")]
        [DisplayFormat(DataFormatString = "{0:MM/dd/yyyy}", ApplyFormatInEditMode = true)]
        public DateTime StartDate { get; set; }

        [DisplayName("Estimated end date")]
        [DisplayFormat(DataFormatString = "{0:MM/dd/yyyy}", ApplyFormatInEditMode = true)]
        [DateGreaterThan("StartDate", "Estimated end date must be greater than the start date of the project")]
        public DateTime EndDate { get; set; }
Note that we already added our custom data attribute data annotation even if it’s not yet created. In my opinion this helps us to think more about how we want to use it rather than how it should be built.
Ok, we defined how we want to use the attribute, now we must create it:
using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;
using System.ComponentModel.DataAnnotations;
using System.Web.Mvc;

namespace DateCustomValidationExample.Models
    [AttributeUsage(AttributeTargets.Property, AllowMultiple=true)]
    public class DateGreaterThanAttribute : ValidationAttribute
        string otherPropertyName;

        public DateGreaterThanAttribute(string otherPropertyName, string errorMessage)
            : base(errorMessage)
            this.otherPropertyName = otherPropertyName;

        protected override ValidationResult IsValid(object value, ValidationContext validationContext)
            ValidationResult validationResult = ValidationResult.Success;
                // Using reflection we can get a reference to the other date property, in this example the project start date
                var otherPropertyInfo = validationContext.ObjectType.GetProperty(this.otherPropertyName);
                // Let's check that otherProperty is of type DateTime as we expect it to be
                if (otherPropertyInfo.PropertyType.Equals(new DateTime().GetType()))
                    DateTime toValidate = (DateTime)value;
                    DateTime referenceProperty = (DateTime)otherPropertyInfo.GetValue(validationContext.ObjectInstance, null);
                    // if the end date is lower than the start date, than the validationResult will be set to false and return
                    // a properly formatted error message
                    if (toValidate.CompareTo(referenceProperty) < 1)
                        validationResult = new ValidationResult(ErrorMessageString);
                    validationResult = new ValidationResult("An error occurred while validating the property. OtherProperty is not of type DateTime");
            catch (Exception ex)
                // Do stuff, i.e. log the exception
                // Let it go through the upper levels, something bad happened
                throw ex;

            return validationResult;

Notice how the attribute extends ValidationAttribute and overrides IsValid method, in which we perform the custom validation.

Now we need aController and aView to test the validation.

Create a HomeController with a simple Index action method, build the project and then add a strongly typed View bound to our model, choosing the “Create” item into the scaffolding  menu.
To simplify user interaction, we will use the standard  jQuery datepicker component to let the user choose the dates.
In order to use it, we must add the following references to our page (or into the master layout page)
<script src="../../Scripts/jquery-1.x.x.js" type="text/javascript"></script>
<script src="../../Scripts/jquery-ui-1.x.x.js" type="text/javascript"></script>
<link href="../../Content/themes/base/jquery.ui.all.css" rel="stylesheet" type="text/css" />
Where x.x is the version you currently have installed.
To bind the datepicker method to our input fields, we use the following jquery code
    $().ready(function () {
        return false;

Then, in order to use server side validation, we need to add the following code to our HomeController to handle form submit

// POST: /Home/
public ActionResult Index(Project model)
   return View(model);
If we run the project and inspect the HTML emitted, this is what we see:
HTML5 emitted  with the server side validation

HTML5 emitted with the server side validation

As expected there is no custom data attribute related to our custom rule.

Then we can insert two dates that will trigger the error message and we get the error message as we expected
Validation error message

Validation error message

That’s it for server-side validation.

Client side validation

Now on to the second part of this tutorial, where we will achieve client side validation.
Before we start, a few important notes (taken directly from the blog  of one of the developers of Asp.Net MVC 3)

jQuery Validate requires your input elements to be inside of a <form> element in order to be validated. In addition, MVC 3 requires that you have called Html.BeginForm() to render this form, so that it can find its book-keeping object to help render the HTML attributes.

Writing a client-side validator involves two steps:

  1. adding one more method to our DateGreaterThanAttribute
  2. writing some jQuery code to create a validation rule and what is called an adapter, which takes the parameter values from the HTML attributes and turns it into jQuery Validate metadata.
Note that we need to write a custom adapter since the default collection doesn’t come with what we need! Otherwise, there is an adapter collection available at jQuery.validator.unobtrusive.adapters.
Let’s go back to our DateGreaterThanAttribute class and modify it so that it implements the IClientValidatable, which, as MSDN says, provides a way for the ASP.NET MVC validation framework to discover at run time whether a validator has support for client validation.
Since we are implementing it, we need to write the method GetClientValidationRules like the following:
public IEnumerable<ModelClientValidationRule> GetClientValidationRules(ModelMetadata metadata, ControllerContext context)
            //string errorMessage = this.FormatErrorMessage(metadata.DisplayName);
            string errorMessage = ErrorMessageString;

            // The value we set here are needed by the jQuery adapter
            ModelClientValidationRule dateGreaterThanRule = new ModelClientValidationRule();
            dateGreaterThanRule.ErrorMessage = errorMessage;
            dateGreaterThanRule.ValidationType = "dategreaterthan"; // This is the name the jQuery adapter will use
            //"otherpropertyname" is the name of the jQuery parameter for the adapter, must be LOWERCASE!
            dateGreaterThanRule.ValidationParameters.Add("otherpropertyname", otherPropertyName);

            yield return dateGreaterThanRule;

Important: The metadata expressed for this rule will be used by the runtime to emit the HTML5 data-val custom attributes!

Now we need to create the jQuery validation function and the jQuery adapter.
We can create a separate .js file, thus we can reuse the code.
Let’s create a new Folder into /Scripts and call it “Custom”, then let’s create a new script called CustomValidation.js.
Let’s see the code:
/* File Created: January 16, 2012 */

// Value is the element to be validated, params is the array of name/value pairs of the parameters extracted from the HTML, element is the HTML element that the validator is attached to
$.validator.addMethod("dategreaterthan", function (value, element, params) {
    return Date.parse(value) > Date.parse($(params).val());

/* The adapter signature:
adapterName is the name of the adapter, and matches the name of the rule in the HTML element.

params is an array of parameter names that you're expecting in the HTML attributes, and is optional. If it is not provided,
then it is presumed that the validator has no parameters.

fn is a function which is called to adapt the HTML attribute values into jQuery Validate rules and messages.

The function will receive a single parameter which is an options object with the following values in it:
The HTML element that the validator is attached to

The HTML form element

The message string extract from the HTML attribute

The array of name/value pairs of the parameters extracted from the HTML attributes

The jQuery rules array for this HTML element. The adapter is expected to add item(s) to this rules array for the specific jQuery Validate validators
that it wants to attach. The name is the name of the jQuery Validate rule, and the value is the parameter values for the jQuery Validate rule.

The jQuery messages array for this HTML element. The adapter is expected to add item(s) to this messages array for the specific jQuery Validate validators that it wants to attach, if it wants a custom error message for this rule. The name is the name of the jQuery Validate rule, and the value is the custom message to be displayed when the rule is violated.
$.validator.unobtrusive.adapters.add("dategreaterthan", ["otherpropertyname"], function (options) {
    options.rules["dategreaterthan"] = "#" + options.params.otherpropertyname;
    options.messages["dategreaterthan"] = options.message;

Let’s look at it in more details:
$.validator.addMethod("dategreaterthan", function (value, element, params) {
    return Date.parse(value) > Date.parse($(params).val());
The first parameter for addMethod is the name that identifies the rule and can be different from what we used inside GetClientValidationRules => dateGreaterThanRule.ValidationType = “dategreaterthan”;
In this example is the same, but you can change it.
The second parameter is the actual validator, in this case simply a comparison between two dates.

The adapter instead is tightly coupled with GetClientValidationRules implementation, therefore the first parameter must match the name we used in the code of our custom attribute for the validationType.

The second parameter is an array of parameters name.

In our case we only added one parameter

dateGreaterThanRule.ValidationParameters.Add("otherpropertyname", otherPropertyName);
so our array will have only one parameter. Should we have more, it would look like [“param1”, “param2”, ….]
The third parameter is a function which is called to adapt the HTML attribute values into jQuery Validate rules and messages.
options.rules["dategreaterthan"] //"dategreaterthan", the key to identify the rule, must match what we used in the addMethod as first parameter.
options.rules["dategreaterthan"] = "#" + options.params.otherpropertyname;

we use the # so that the value stored will be something like “#StartDate”, that is ready to be consumed by the validation rule previously wrote to get the value out of the StartDate field.

The javascript is done! Now let’s go back to our View because we need to add all the references we need to run the unobtrusive validation:
<script src="../../Scripts/jquery.validate.js" type="text/javascript"></script>
<script src="../../Scripts/jquery.validate.unobtrusive.js" type="text/javascript"></script>
<script src="../../Scripts/MicrosoftMvcAjax.js" type="text/javascript"></script>
<script src="../../Scripts/Custom/CustomValidation.js" type="text/javascript"></script>

Everything’s done and now we can run the app. If we inspect the HTML that has been emitted this is what we see

HTML emitted with client side validation

HTML emitted with client side validation

and if we run the application we will see the same error message as before, with no form submit!

The source code is available on my github at the following URL: https://github.com/vgheri/DateCustomValidationExample

That’s all for the unobtrusive custom validation with MVC 3.

I hope this helps,