Simon Ince's Blog : JavaScript

A JavaScript Event Bus

simonince — Mon, 21 Dec 2009 17:39:00 GMT

I was working on a Proof of Concept recently that needed to support loosely coupled Ajax components. The idea is a common one – components need to be able to hook into an existing page without detailed knowledge of how the page works, and immediately start responding appropriately. This is basically using loosely coupled events as an extensibility mechanism. It is by no means a new concept – just check out things like Prism for an example!

After some consideration we came up with an approach that I like – it is actually very simple, but works great. In JavaScript we have very few issues to do with avoiding sharing the wrong types, marshalling to UI threads, etc... so the basic implementation is incredibly simple. We end up with a central "Event Bus" component that receives events and publishes them to a list of listeners... something that Sys.Component and its EventHandlerList is perfect to assist us with. The code I ended up with is below;

Type.registerNamespace('Sample')

Sample.EventBus = function() {

Sample.EventBus.initializeBase(this);

}

Sample.EventBus.prototype = {

subscribe: function subscribe(eventType, callback) {

this.get_events().addHandler(eventType, callback);

publish: function publish(eventType, arg) {

var handler = this.get_events().getHandler(eventType);

if (handler)

handler(arg);

}

Sample.EventBus.registerClass('Sample.EventBus', Sys.Component);

As you can see, this really is quite simple. We have the notion of an "eventType", that identifies the message type passing over the bus, and we have a single argument that can be used to carry a payload.

We could easily use strings to identify these event types, but I decided I'd like to use a static property – and a great way to register such a property is to pinch an idea from Microsoft Ajax's registerComponent method... so we end up with something like this;

Sample.EventBus.registerEventType =

function registerEventType(target, eventType) {

if (!target.Events)

target['Events'] = {};

target.Events[eventType] = eventType;

}

This is designed to allow us to "extend" some type definition with static properties that identify any events we're going to use. It seems logical that the extended type is also the type of the payload argument to the events... so all this now allows me to register my events like this;

// simple class to carry data values with event

Sample.Payload = function(dataValue) {

this.data = dataValue;

}

// definition of event types relevant to Payload class

Sample.EventBus.registerEventType(Sample.Payload, 'Update');

Sample.EventBus.registerEventType(Sample.Payload, 'Click');

... and then to publish and subscribe to Event Bus messages like this;

bus.publish(Sample.Payload.Events.Update, new Sample.Payload('Some Data'));

... and this...

bus.subscribe(Sample.Payload.Events.Update, function(arg) {

// perform some action

});

To make locating the bus simple, I have made it a Sys.Component, and retrieve it using a simple static helper function;

Sample.EventBus.get_Instance = function get_Instance() {

return Sys.Application.findComponent('SampleEventBus');

}

Of course, the subscribers could be in any component or script – as long as they have a reference to the Event Bus and the Payload class (and you could remove this dependency and use strings if you didn't like it) they can listen and respond. The Event Bus could get more intelligent if we liked – perhaps logging, tracing, translation, or scheduled execution (to split up subscriber execution, hence avoiding blocking the UI thread)... and much more.

This brings the power of a loosely coupled event extensibility mechanism to an HTML page with JavaScript, and it could of course be used to compliment equivalent server side behaviour. Easy, huh? What do you think?

A really simple sample site is attached... try tabbing out of the text box, and then click the button. There are two components listening for different events. Try adding another to test my script!

The Microsoft Ajax Content Delivery Network (CDN)

simonince — Thu, 22 Oct 2009 16:36:00 GMT

I keep looking for the URL’s to get Microsoft Ajax, jQuery, the MVC Ajax libraries and more from our new shiny CDN (check here if you’ve not heard of it)... and I can never remember where they are.

So this post is for my benefit, not yours J

The links to all scripts are at http://www.asp.net/ajax/cdn/.

Loading Scripts Late

simonince — Tue, 20 Oct 2009 19:52:00 GMT

On the ASP.NET ScriptManager control there is a useful little property that very few people have heard of called “LoadScriptsBeforeUI”. What does it do?

Well, simply put...

· When “true” (the default) it will render <script> tags for each script you reference using the ScriptManager at the top of your HTML.

· When “false” it will render these <script> tags at the bottom of your HTML.

Oh right. Why would I bother?

Well to put it simply it is because all browsers stop parsing and rendering HTML while they are downloading and executing scripts... which means if you put your <script> tags at the top of a web page none of your page will start to render until all scripts are downloaded and dealt with. The bottom line is that while your page is downloading scripts, the page is usually blank, and your user is wondering why the page is taking so long to load.

In a development environment this may not seem particularly important – but deploy your application to somewhere bandwidth and network speed are unknown, and it can often become an issue. Users don’t like sitting waiting for your site to respond, so you could be losing users!

Let’s see it

Let’s see what this looks like in action – download the attached sample solution and view the two pages. One downloads my scripts first; and I’ve made sure one of the scripts takes 5 seconds to load, so it is obvious how slow the page is. The other page loads the script last... and you’ll notice the page renders immediately, without waiting for the script.

Have a look at the HTML source and see where the references to TestScript.js and GetScript.ashx are.

The Gotcha

I’ve just showed you how to improve the perceived performance of your web site by changing one setting from “true” to “false”! Right?

But I’m afraid there is a catch. You’ll also notice there is a button on my test web pages. This is to demonstrate something important; you need to be very aware of when the scripts are being downloaded. This leads to two opposing issues;

1. If you have scripts that execute as soon as they’re downloaded, they probably assume that the DOM has been built. In this case, they usually must be rendered last. I’d recommend using page load events instead, so that you don’t have this requirement.

My sample demonstrates this; only when TestScript.js is loaded after the UI has been rendered does the button work, because TestScript.js assumes the button exists and attaches an event handler. If I put this in pageLoad instead it wouldn’t be an issue.

2. If you have event handlers embedded in your HTML that depend upon some framework scripts you’re downloading later, the user could click the button before your scripts have downloaded and the handler would error! This approach to wiring up event handlers looks something like this;

<button onclick="callMethod()">Click Me</button>

The solution here is to attach event handlers programmatically, as I have done in TestScript, but in the pageLoad event instead. You could even consider defaulting your buttons/controls to a "disabled" state, enabling them once you've attached the event handlers. This can sit well with the principles of Unobtrusive JavaScript and progressive enhancement if your controls have default non-script behaviours, so is a good practice anyway.

The End...

I think this shows a useful technique that can really improve users’ perception of your web site... as long as you design your use of script to work correctly. Enjoy!

Executing JavaScript after a Partial Render

simonince — Thu, 30 Jul 2009 00:01:00 GMT

I had a fun day debugging some ASP.NET plus jQuery this week, and came across something I’ve known is possible for some time, but that I’ve never actually needed to do... and that was to ensure a bit of JavaScript ran once an UpdatePanel had refreshed as part of a partial render.

It turns out that this is easy; all you need to do is register your JavaScript code block with some methods on ScriptManager, rather than using the standard ClientScript methods.

For example, consider the HTML below (I’ve omitted the rest of the page including the script manager, but it is in the download);

<asp:Button

ID="ClickMeButton"

runat="server"

Text="Click Me to Refresh Below"

onclick="ClickMeButton_Click" />

<asp:UpdatePanel

ID="MyUpdatePanel"

runat="server"

UpdateMode="Conditional">

<asp:AsyncPostBackTrigger

ControlID="ClickMeButton"

EventName="Click" />

</Triggers>

Last Updated:

<asp:Label

ID="UpdateTimeLabel"

runat="server" />

</ContentTemplate>

</asp:UpdatePanel>

</div>

</div>

Here we have a simple UpdatePanel, with a button that triggers the async postback. There is also an empty DIV with ID “log”.

In the server-side code of the button click event I have some code that looks a bit like this;

string time = DateTime.Now.ToLongTimeString();

ScriptManager.RegisterStartupScript(

UpdateTimeLabel,

typeof(Label),

"UpdateTimeLabelStartupScript",

CreateScript(time),

true);

The CreateScript function simply returns some JavaScript in a string that reads as follows (the {0} is replace with a time);

$('#log').append('Last Server Run: {0}<br />');

This uses jQuery to append a message to our “log” DIV.

There is also an alternative though; using the Sys.Application.add_load method to attach a page load script function, or creating a pageLoad JavaScript function that is a synonym for the same thing. I’ve done the latter;

function pageLoad() {

$('#log').append('pageLoad executed<br />');

}

This function is executed when the page initially renders and when every partial render completes. This means the content of my “log” DIV rapidly starts to look like this;

pageLoad executed

Last Run: 21:56:12

pageLoad executed

Last Run: 21:56:14

pageLoad executed

Last Run: 21:56:19

pageLoad executed

Easy huh?

I hope that adds some clarity to your options for executing script as the result of a partial postback. Check out the attached if you want to try it yourself.

Enforcing Unobtrusive JavaScript

simonince — Fri, 10 Jul 2009 21:07:00 GMT

Unobtrusive JavaScript is a concept that’s been around for quite a while, but it’s now finally starting to make its way into the mainstream. The basic idea is that you should separate your JavaScript from your HTML – so instead of;

<a href="Default.aspx" onclick="alert('Sorry, that is unavailable'); return false;" >Click Here</a>

You should have something like this;

<a id="ClickHereLink" href="Default.aspx">Click Here</a>

... with some matching JavaScript in another file somewhere;

function pageLoad() {

var link = $get('ClickHereLink');

$addHandler(link, 'click', preventClick);

}

function preventClick() {

alert('Sorry, that is unavailable');

return false;

}

I’m not here to tell you why this is so great, but the best discussion and walkthrough of issues I’ve found is this article on onlinetools.org, so check it out if you’re interested.

How do I enforce it?

Recently I found myself cursing some code I’d written a long time ago, when I found it littered with onclick and onload handlers. It was frankly a pain to work out how it works. It was at this point that I thought “I should write something to shout at me when I write don’t write unobtrusive JavaScript”.

Coincidentally I have also been doing some work on HTML parsing, and I have to say I’ve found the XPath-like features in the HTML Agility Pack to be incredibly useful. If you’ve never used it I’d recommend taking a look.

It occurred to me that this was the perfect tool to do what I wanted – so I set about creating a simple MSBuild task that uses the HTML Agility Pack to scan ASPX and ASCX files for Obtrusive JavaScript – basically a form of static code analysis. If you’re interested in customising MSBuild, check this out.

The implementation is very simple;

· It is derived from Microsoft.Build.Utilities.Task.

· There is a property that is an array of ITaskItems, flagged with a [Required] attribute, as a way to pass in a list of files to check.

· There’s a hard-coded (for now) list of validation XPath expressions, with matching explanations.

· In the Execute method override, it loops through all the files.

· For each file, it opens the HTML and applies every XPath to it.

· If there are any matches for the XPath, it creates a build failure.

The key to success here is the simplicity with which the HTML Agility Pack lets me use XPath to find elements. The following is the basics of my code;

HtmlDocument doc = new HtmlDocument();

doc.Load(path);

HtmlNodeCollection results =

doc.DocumentNode.SelectNodes(

validator.SearchXPath);

Easy huh? The XPath expressions themselves mostly look like this;

//*[@onkeypress]

This will match any HTML element that has an onkeypress attribute... which of course means that the developer has specified a JavaScript event handler in the HTML, and broken the rules of unobtrusivitiy (hey, if that’s not a word I’m having first dibs on inventing it J).

Remembering that we’re actually scanning ASP.NET mark-up, not pure HTML, we can also check for ASP.NET attributes that actually create JavaScript event handlers in HTML too;

//*[@onclientclick]

Again, this is not difficult. The tricky one appears when you realise that it is valid to have OnClick in ASP.NET code! Of course, an <asp:button> can have an OnClick attribute referring to the server-side event handler. I wondered about saying “match any with an onclick that don’t have a runat attribute”, but this isn’t quite accurate (HtmlControls can have runat=”server” too remember).

In the end I went for explicitly excluding the ASP.NET controls that I knew were OK to use OnClick;

//*[@onclick and not(

name()='asp:button' or name()='asp:bulletedlist' or

name()='asp:imagebutton' or name()='asp:imagemap' or

name()='asp:linkbutton')]

Finally, I wanted to check that there was no JavaScript inside the page HTML itself... even between <script> tags. In other words, the only valid <script> tags should reference an external file, as follows;

[Of course, you could also use the <asp:ScriptManager> control if you wanted to; in fact I’d prefer it]

To achieve this I check that there is nothing other than whitespace between the start and end script tags;

//script[string-length(normalize-space(text()))>1]

... and that’s it! As usual, the source code for this MSBuild Task is attached to this post, along with a demonstration Web App.

Wiring up the Task

Now we have a simple MSBuild task, all that is left to do is add it to a build. I created a new ASP.NET Web Application, right clicked the project file and chose “unload”, and then edited the XML manually.

The only bit I needed to add was as follows;

<UsingTask

AssemblyFile="..\JsBuildTasks.dll"

TaskName="ValidateUnobtrusive" />

<ValidateUnobtrusive

SourceFiles="@(Content)" />

</Target>

First I import my task (I’ve copied a Release build of the assembly to the parent directory above my Web App project). Next, I override the BeforeBuild target, and add an instance of my ValidateUnobtrusive task. I’ve passed in an expansion of all the Content files in the project. The task filters for *.aspx and *.ascx at the moment – if you wanted to add *.html that would be trivial.

Save the file, and right click it to choose Reload Project. At this point Visual Studio 2008 warns you about a customised MSBuild project file – just choose “Load Project Normally” and you’re away.

From this point on, whenever you build a project containing Obtrusive JavaScript you’ll see errors like these;

Error Use of the 'onclick' JavaScript event on 'a' tag in markup causes Obtrusive Javascript. You should attach this handler in script instead.

Error Failed on 'script' tag . A JavaScript region containing something other than white space was found. You should link to related JavaScript resources files rather than embed script in a page.

Conclusion

I think this works really well so far (although I’m at the early stages of trialling it); if you try it do let me know how you get on. One of the particularly cool things (that I haven’t tried yet as I’m working isolated on my laptop most of the time right now, and I’m short of time) is that this could be wired up into a Continuous Integration build, under Team Build – I guess that would be a good plan if you didn’t like running the validation as part of your local build, or if it starts to perform badly due to the complexity or size of your pages.

I also think it raises other questions and possibilities. For example; how about some static analysis of “.js” files themselves? Could this help check for Directly Accessible Scripts, for example?

Using Anchor Links with AJAX History

simonince — Wed, 24 Jun 2009 20:49:00 GMT

A customer asked me about doing this the other day, and I’d never come across it, although it seems obvious now! If I have a page that makes use of ASP.NET’s server-side ScriptManager AJAX history features but also want to link to an anchor on that page, I get problems.

For example, if I have a page like this;

... imagine (or try the download!) that I can click the “here” link to jump to an anchor defined further down the page as follows;

<h1><a id="bottom">Bottom</a></h1>

<p>

This is at the bottom.

Click <a href="#">here</a> to jump to the top.

</p>

Nothing complex... until I point out that the drop-down list and Person details are in an UpdatePanel, and that when the user selects a different user, server-side code such as the following is run (note that Person.All is a very basic repository of test data);

var selectedId =

Int32.Parse(PeopleList.SelectedItem.Value);

var selected =

Person.All.Where(p => p.Id == selectedId).Single();

if (PageScriptManager.IsInAsyncPostBack)

PageScriptManager.AddHistoryPoint(

PersonIdHistoryKey,

selectedId.ToString(),

String.Format("Viewing {0}", selected.Name));

This adds a “history point” to the URL that I can use to reload the correct Person should the user bookmark the page and revisit another time. The key here is how it encodes it – the fragment of the URL after the hash is used (note I’ve disabled the encryption for this post);

http://myserver/Default.aspx#&&PersonIdHistoryKey=3

Of course, if I now click on my “click here” link shown above, the target anchor (“#bottom”) will replace the AJAX history state data. If you want to see what I mean, download my demo solution and delete the component we’re about to write from the page.

A Solution

I thought about this for a while, and came up with an interesting and reusable solution. I created an ASP.NET Extender component that is used to “extend” the ScriptManager control. This extender emits an ASP.NET AJAX JavaScript behaviour that supplies some additional client-side functionality.

Specifically, when the behaviour is initialised, it performs the following actions;

// add a handler for the navigate event

var navigateDelegate =

Function.createDelegate(this, this.handleNavigate);

Sys.Application.add_navigate(navigateDelegate);

// when the page is loaded, scan for every link that

// targets a "#something" anchor and add a "click"

// javascript handler to it

var clickDelegate =

Function.createDelegate(this, this.handleClick);

Sys.Application.add_load(function() {

$('a[href^=#]').click(clickDelegate);

});

Basically we’re doing two things here – firstly, hooking up to the client-side “navigate” event that is fired when a page loads that has client-side History information embedded in the URL... this is done in the same way as for the server-side history portion we saw above, but after the # and before the && symbols. Have a read of this walkthrough for a bit more info on the client-side aspect to AJAX history.

Secondly we’re adding some code to run once the page has finished loading. This code uses a jQuery selector to find all “a” (anchor) tags for which the HREF begins with a # symbol. Once these have been identified, a click event handler is assigned to them all. This means we’re applying functionality to every link on the page that targets a local anchor mark with a single statement – nice!

There are then two more elements to the solution; handleClick (fired when the user clicks on one of these “a” tags), and handleNavigate (fired when a page loads that contains client-side history markers).

handleClick

When a user clicks on link to a local anchor (i.e. of the form “#something”) we run the following script;

var eventSource = args.target;

var parts = eventSource.href.split('#');

if (parts && parts.length > 1) {

var target = parts[1];

Sys.Application.addHistoryPoint({ jumpTo: target }, document.title);

if (target) {

var targetElement = $get(target)

if (targetElement)

this._scrollToElement(targetElement);

}

else

window.scrollTo(0, 0);

return false;

}

What this does is three things;

1. It finds the link that caused the event, and splits out the portion of the URL after the “#” – which of course is the ID of the anchor we want to navigate to.

2. It adds a client-side history point, including the name of the target anchor we want to display as an expando property called “jumpTo” on an anonymous object. This means we can recreate the behaviour if the user bookmarks the page.

3. It finds the target element and scrolls it into view. If the target is blank, it assumes we’re aiming for the top of the page.

Easy huh?!

handleNavigate

This function is fired when a page loads, if it contains client-side history information.

var target = args.get_state().jumpTo;

if (target) {

var targetElement = $get(target);

if (targetElement)

this._scrollToElement(targetElement);

}

All this does is to extract the data from the history state that we encoded in the handleClick function – we’re after the value of the “jumpTo” expando property. Once it has that, it tries to find the element on the page, and if it is found, scrolls it into view.

Summary

The end result is a URL that can look something like this;

http://myserver/Default.aspx#jumpTo=bottom&&PersonIdHistoryKey=1

... it should be obvious that we have both a client-side (in red) and server-side (in green) portion encoded here.

This component is so easy to use – we can just drop it onto a page, extending the ScriptManager control, and immediately enabling the handling of local anchor references without customising the HTML. Of course, if JavaScript is disabled, it will still work fine.

Let me know what you think – there are plenty of ways to enhance or alter this behaviour if it doesn’t work quite how you want it to (for example, you might not like it returning to the same place after every postback, or you might need to use client-side history for both this and something else at the same time). I’d also love to hear if you use it and have some feedback.

I’ve attached the source (usual disclaimers apply – this is not production strength code) so download it and have play.

AJAX Script Patterns: Service Agent

simonince — Fri, 05 Dec 2008 00:45:00 GMT

I’ve been thinking for a while about how people tend to build AJAX applications, as there seems to be something a lot of people have forgotten. This post examines how applying a pattern you probably know very well to AJAX could help – and leaves it to you to decide whether this is useful. Let me know what you think.

Setting the Scene

In your average application architecture, you’ll generally find a “Resource Access” layer that contains Service Agents (also known as Service Gateways) for accessing remote web services. What are these for? Well, I think the MSDN documentation on the pattern sums it up nicely in the Problem statement;

“How do you decouple the details of fulfilling the contract responsibilities defined by the [remote web] service from the rest of your application?”

The answer is of course that you create a class to manage the interaction with your service and hide the inner workings and contract implementations from the rest of your code. This class and any supporting entities make up your Service Agent.

AJAX: Why so Different?

With the growing popularity of AJAX, and the great features available in Microsoft AJAX, more and more web sites use script to call services hosted back on the ASP.NET server to load data, and dynamically update the page with DOM operations.

So how come so many sites have forgotten what we learnt years ago? This script calls a web service – and this web service forms a part of a larger system. It may change – the contracts, the implementation, the name, the location... Consider that these web services may also be shared between AJAX, Silverlight, ASP.NET, WPF, and/or other technologies as clients. So each of these could require tweaks to your shared web service (even if they’re using a different endpoint that uses a different binding, chances are the contracts and implementation are shared).

Microsoft AJAX helps us by auto-generating the web service proxy and related entities for calling a script-enabled web service. But if you change the web service, this changes the generated proxy, and you could find many pages in your web site suddenly need JavaScript changes to work correctly again. We don’t get the rich compile-time support in JavaScript that we get with .NET languages, so you might not find these problems until testing, or worse, live.

Therefore I see two options for handling this;

1. You could create a reusable ASP.NET AJAX server control that wraps up the web service calls and UI manipulation. This means you’ve just got one place to make changes, so is a great solution.

2. If the service is used differently in each place, perhaps it just doesn’t suit being a control. In which case, I propose creating a script-based Service Agent.

A Simple Example

To demonstrate this, I’ve created the bare minimum of a simple WCF service to be called from AJAX;

[ServiceContract(

Namespace =

"http://samples.microsoft.com/jslayering")]

[AspNetCompatibilityRequirements(

RequirementsMode =

AspNetCompatibilityRequirementsMode.Allowed)]

public class PersonService

{

[OperationContract]

public GetPersonResponse GetPerson(

GetPersonRequest request)

{

Implementation

}

[MessageContract]

public class GetPersonRequest

{

[MessageBodyMember]

public int Identifier { get; set; }

}

[MessageContract]

public class GetPersonResponse

{

[MessageBodyMember]

public bool Found { get; set; }

[MessageBodyMember]

public Person Person { get; set; }

}

[DataContract]

public class Person

{

[DataMember]

public int Identifier { get; set; }

[DataMember]

public string Name { get; set; }

[DataMember]

public int Age { get; set; }

}

You can see I’ve also chosen to use Message Contracts... we’ll see why in a moment J

All that happens in this service is the client requests a Person’s details, and they either get Found=true and a Person entity back, or Found=false. In my implementation this is hard-coded and randomised, so excuse the grim code.

Creating a Service Agent

The first thing we need is a JavaScript entity to hold person details in. This is because the Person class above is part of the contract of the web service – so if we change it, the JavaScript entity generated by Microsoft AJAX will change too... so we need to protect the rest of our JavaScript code from this. Let’s see my simple entity;

/// <reference name="MicrosoftAjax.js"/>

/// <reference path="~/PersonService.svc" />

Type.registerNamespace("ServiceAgents");

ServiceAgents.Person = function(id, name, age) {

this._id = id;

this._name = name;

this._age = age;

}

ServiceAgents.Person.prototype = {

get_id: function() {

return this._id;

get_name: function() {

return this._name;

get_age: function() {

return this._age;

}

ServiceAgents.Person.registerClass(

'ServiceAgents.Person');

if (typeof (Sys) !== 'undefined')

Sys.Application.notifyScriptLoaded();

* Note the use of the <reference> tag so I get intellisense in Visual Studio 2008!

This is the simplest of objects, and just stored the three fields found on a Person entity. Next, we need a Service Agent. I’ve chosen to create this as a component (inherited from Sys.Component) mainly because I might want to add event handlers and more to it another time, so having it as a managed disposable object is potentially useful.

/// <reference name="MicrosoftAjax.js"/>

/// <reference path="~/PersonService.svc" />

/// <reference path="Person.js" />

Type.registerNamespace("ServiceAgents");

ServiceAgents.PersonServiceAgent = function() {

ServiceAgents.PersonServiceAgent.

initializeBase(this);

}

ServiceAgents.PersonServiceAgent.prototype = {

initialize: function() {

ServiceAgents.PersonServiceAgent.

callBaseMethod(this, 'initialize');

dispose: function() {

ServiceAgents.PersonServiceAgent.

callBaseMethod(this, 'dispose');

GetPerson: function(identifier, callback) {

var success = Function.createDelegate(

this, this._onSuccess);

var failure = Function.createDelegate(

this, this._onFailure);

// call the web service

samples.microsoft.com.jslayering.PersonService.

GetPerson(identifier, success, failure, callback);

_onSuccess: function(result, context) {

// check we got a result back

if (!result.Found)

this._onFailure({ get_message: function()

{ return 'Person not found'; } },

context);

else {

// translate to our Person entity

var returnentity = new ServiceAgents.Person(

result.Person.Identifier,

result.Person.Name,

result.Person.Age);

// call the callback that was passed in

context(returnentity);

}

_onFailure: function(result, context) {

alert('A call to the Person Service failed: '

+ result.get_message());

}

ServiceAgents.PersonServiceAgent.registerClass(

'ServiceAgents.PersonServiceAgent', Sys.Component);

// ensure an instance of this component is created

// when the page is initialising

if (typeof (Sys) !== 'undefined') {

Sys.Application.add_init(

function() {

$create(

ServiceAgents.PersonServiceAgent,

{ id: 'PersonSA' },

null, null, null);

});

Sys.Application.notifyScriptLoaded();

}

There are four things to note in this component;

1. The only public method we’ve added is GetPerson. This literally sets up some call-backs and passes the call on to the auto-generated script proxy.

2. When the call succeeds, we check a result was found (using the Found property on the Message Contract) and if it was, we create a new instance of our own Person entity to pass back, by calling the supplied call-back method.

3. If there’s a failure we handle it; I could have let the caller do this, but this component is for illustrative purposes only... it is by no means perfect and I wanted to keep it quite brief!

4. We ensure an instance of our component is created when the page initialises, so that page script can easily consume it.

Using the Service Agent

Making use of this component is easy – we need to import the relevant services and scripts, and then get a reference to it using the $find method, and call it! First I register the scripts with a ScriptManager. We still need to point out on every page that we want to import the service, and now have to specify our Service Agent scripts too;

<asp:ScriptManager

ID="PageScriptManager"

runat="server">

<asp:ServiceReference

Path="~/PersonService.svc" />

</Services>

<asp:ScriptReference

Path="~/Scripts/Person.js" />

<asp:ScriptReference

Path="~/Scripts/PersonServiceAgent.js" />

</Scripts>

</asp:ScriptManager>

Then I’ve got the following script on my page;

function getPerson() {

var id = $get('RequestIdentifierTextBox').value;

var serviceAgent = $find('PersonSA');

serviceAgent.GetPerson(id, displayPerson);

// prevent post-back as we've handled it client side

return false;

}

function displayPerson(result) {

$get('IdentifierLabel').innerHTML = result.get_id();

$get('NameTextBox').value = result.get_name();

$get('AgeTextBox').value = result.get_age();

}

... which drives a page that looks like this;

Breaking the Application

Well this is not worthwhile unless we can demonstrate a tangible benefit. Imagine that code similar to that above is scattered throughout our web site, and we have many pages to maintain. Now imagine that our web service needs to change. Maybe the XML namespace is updated... or maybe we decide to rip out all of our Message Contracts (a bit contrived, but it demonstrates what we’re talking about!). My service becomes;

[ServiceContract(

Namespace =

"http://samples.microsoft.com/jslayering")]

[AspNetCompatibilityRequirements(

RequirementsMode =

AspNetCompatibilityRequirementsMode.Allowed)]

public class PersonService

{

[OperationContract]

public Person GetPerson(int identifier)

{

Implementation

}

Immediately our auto-generated proxy changes and the JavaScript code breaks. There’s no Found property anymore, we just get a null Person back if there is no match. And we can’t access a Person property on the Message Contract because it isn’t there... we’ve got a Person instead.

Obviously applying these changes site-wide would be a real headache. But for us, it’s easy. We just change a few lines! We’ll just tweak our _onSuccess call-back in the Service Agent;

_onSuccess: function(result, context) {

// note we only check for a result, not result.Found

if (!result)

this._onFailure({ get_message: function()

{ return 'Person not found'; } },

context);

else {

// note the changes when building our return entity –

// no ".Person." message contract syntax

var returnentity =

new ServiceAgents.Person(

result.Identifier,

result.Name,

result.Age);

context(returnentity);

}

Hey presto! Our site works again, and you can leave the office at a sensible time!

Conclusion

Obviously this is extra coding effort to put together a Service Agent, but do you see the benefits? Is it worthwhile? What about other patterns? How about View-Presenter, for example? Do they apply to JavaScript? Do you use this kind of approach already?

I’d love to know what you think, and what you do right now... feel free to comment or blog back at me.

The attached code should demonstrate all this – there are “-before” and “-after” web sites, both containing implementations of this page with a Service Agent and using direct calls against the auto-generated proxy.

In the “after” site I’ve removed the Message Contracts and tweaked the Service Agent... but I haven’t fixed the direct proxy calls so you can see how it breaks.

Enjoy...