The Local JavaScript API for Local People

I was giving a presentation at an ESRI gathering hosted in reading at Microsoft this week, talking about all things Silverlight and MapIt, and very little unsurprisingly about the Flex API. During a presentation imageabout the Web API’s I mentioned JavaScript and Silverlight as two offerings that whilst can do similar things, need to be considered carefully in relation to the audience in questioning and the tasks they wish to perform. Now I like the Silverlight API and as I mentioned in the talk it can really allow for the avoidance of browser support pain by abstracting away the layer between your application  and the browser hosting it.

Often though you don’t want a plug-in to preclude people accessing your site, this might be down to a number of reasons but unless your going to start hand cranking simple code for map access (people who have to disable JavaScript within your browser should stop reading now) then you have the JavaScript API. Usually this is delivered to you from somewhere in the cloud ( specifically), but often there are a number of scenarios that might occur that will mean you have to install it locally.

Why Local?

If you are an ArcGIS server subscriber you are able to request the JavaScript API from ESRI or your local imagedistributor as explained here on the support site. There are a number of reasons why you might wish to do this:

You are super secure and think that access to the internet is a potential security risk  and therefore getting access to the online API is not possible. Many organisations have yet to embrace the concept of Content Delivery Networks (CDN’s), such as that used for hosting the ESRI JavaScript API. Whilst in a consumer space this is a common architectural practice as it places the download on the users connection for the CDN and not on the hosts (saving bandwidth allowing that to be used for serving images and functionality). Often within the firewall of organisations it is not possible to access external files as the network is secure.  This is also the case where you have a slow external connection and you wish to limit the amount of information that is downloaded from the ‘cloud’.

imageYou want to create a custom build of the API to reduce the number of files downloaded, improving browser response. The classic number one rule from High Performance Web Sites of making fewer HTTP  requests asks for front end developers to minimise the number of files they download from a site, when building on top of the JavaScript API it is common to build your application into many separate files to separate functionality or Dijits and to allow the usual spaghetti of development that can happen with JavaScript to be controlled.

A concurrent dilemma

The problem with this is that each JavaScript library you add to the application the longer it will take to download due to the limited number of concurrent files a browser can download at once. This is the same if you include new CSS files and images as well. This is down to the way HTTP 1.1 was implemented and setting a limit of no more than two files concurrently per hostname. BrowserScope explains it nicely as:

When HTTP/1.1 was introduced with persistent connections enabled by default, the suggestion was that browsers open only two connections per hostname. Pages that had 10 or 20 resources served from a single hostname loaded slowly because the resources were downloaded two-at-a-time. Browsers have been increasing the number of connections opened per hostname, for example, IE went from 2 in IE7 to 6 in IE8.

image This often leads to developers hosting parts of their application on different hostnames one starting with a URL such as and another such as, to get around such limitations. With large JavaScript libraries the time it takes to download these on slower connections can leave an application imageunresponsive and give a very bad user experience.

You can see from their tests (see image left) that modern browsers have upped this limit to 8 connections, this can have a dramatic affect on perceived speed as more of the application can be downloaded at once and when partitioned correctly (using a lazy loading pattern preferably) then users can see something happening in the browser much earlier than they could with a plug-in such as Silverlight or Flash (beware the loading circle of doom).

Of course with external (public facing) applications you will always have some users using IE6 and the limitations of 2 connections per hostname. This is where the ability to package your JavaScript files up into as small package as possible and as few packages as possible becomes more important and the need for a copy of the local JavaScript API imperative for use in a custom Dojo build.image

One build for all?

Unfortunately each build is different for each project and therefore there is no magic bullet for this. Fortunately there are a number of key pieces of information and discussions about how to perform this task. There is a thread on the ESRI support forums going through the process an excellent Geocortex post upon why they did a custom build here and finally a link to the Dojo documentation outlining the process in full. Whilst it might be a complex procedure, for people who are interesting in getting their application to load in the fastest time within the browser, it should be a procedure worth looking at.

Where are you from? A journey into WCF with Dojo.

To celebrate the upgrading of the JavaScript API to 1.5 I decided to have a little play with adding a where are you from page to the site (you can get too it from the page link above). This is a little routine to take your IP address and geo-locate where you are. It’s a very simple application in the style of Al Pascual’s imageMap Stats Silverlight application that you can get here. In fact it’s almost the same, except it works with Dojo uses a different IP geolocator from IPInfoDB as the one used by Al didn’t know places like New Zealand existed.

It was an interesting application to write, not only did it let me get acquainted again with the JS API, but also accessing simple WCF services from Dojo (easier than you might think) and working with the .NET JSON data contract serializer’s. Once you have the basics of those then the world is your oyster in terms of getting functionality into the browser. The Dojo bits were easy, a few bits of JavaScript on the page a call to a service using xhrGet and were cooking on gas, all we need now is the working WCF service. Hmm now that should be easy yes?

WCF Learning Pains

I’ve always been amazed about how Microsoft took a nice simple thing such as Web Services and made it so much harder with WCF. I do understand that you can to so much more, but with the Visual Studio IDE imageyou just used the template to create the webservice (add new!) and there it was, easy as the proverbial pie. Now with WCF it’s all about message contracts and whether they right information has been dumped into your web.config file. Now I do understand the power of data contracts and how they can be extremely powerful, but the fact that after creating a new WCF service, I had to make sure everything was decorated correctly down to specifying the right binding on my endpoint (if you don’t know what I mean then don’t worry it’s not really worth knowing, if you do I think you should get out more). Why do I have to do this? I think I’ve become lazy when developing with Microsoft products, when the tools fail me I have to start relying on my brain again (ok I use Google’s brain, but haven’t we all outsourced our thinking to Google already?), I think I last used that was when I was developing Java applications (or come to think of it debugging JavaScript!). So my new checklist for getting WCF services ready to be used with Dojo is:

  • Is your endpoints binding set to webHttpBinding in your web.config, mine wasn’t it caused me grief.
  • Have you set your AspNetCompatibilityRequirements to allowed in your service attributes? I think this matters, stuff works once it’s been added in (lots more info about WCF and ASP.NET can be gained here, a must read).
  • Does your operating contract (contained in your interface file if you didn’t know) specify the right parameter names for the Dojo request (mine didn’t it took me a while to realise why nothing was actually being passed in, classic brain-fail!). image
    Now I can actually see that these things are going to help me in the long run, I just wished that stuff I could have knocked up in about 5 minutes in the old way takes me so much longer and a great deal more fiddling to do. It’s like having to do real coding again, not just concerning myself with actually getting the applications to do what the customer wants, yeah I remember those days, they weren’t good in my opinion!

serviceHostingEnvironment what’s this then?

Once I had the code working there was one final journey into the unknown depths of the servicemodel section of the web.config file. This had to do with deploying my application onto my host, which has a number of URL’s that are assigned to my domain. This confuses WCF and gives a strange error when it cannot seem to resolve the correct one. So it was back to the web.config file to set the baseAddressPrefixFilters element within the serviceHostingEnvironment tag. Fortunatley my Googlebrain was able to help me out again and I managed to find this post (ironically from my host!) although the simple solution is contained in the comments.

I am not Spock.

Yeah I know you think I’m making it all up, I wish I was. When designing this stuff they should have read Jol Spolsky’s duct tape programmer post to understand whilst many people can get software to work and be delivered on time, were not all Spock.  Nor do we wish to devote out life to being Spock, I have games to play and wine to drink (and if I have any time left over a family to be with, well maybe I can spend a little more time coding!).

Anyway after all this I managed to get my simple, yeah it’s not very complicated once this bits fall into place, location application working. I’ve got a few more plans for it (integration with Firefox location, addition of Tweets in your area, <insert additional social API integration here>, you get the idea.

Once complete I’ll post some of the code up and if your really interested, sometime I’ll go through how I wrote a WCF class to consume the ArcGIS Server REST API, yeah I know you can’t wait. In the meantime I’ll put the existing code up soon but head over to the page to find out where you are (if you don’t already know!) and remember as you develop all this ninja code the following adage…



Dojo – Well done you have found another piece of the hidden documentation!

imageI’ll start this post by saying I like Dojo. It makes developing JavaScript a lot easier than hacking the code yourself especially when trying to support multiple browsers. As with everything though it’s not perfect.  Whilst getting hold of the code is as simple as linking to the AOL hosted site, getting hold of the information about how to use the code makes you feel like your playing some sort of Japanese console adventure game, probably on the Wii, hunting the internet for snippets of code, working examples or even fully fledge sites, that might give you a small insight into how the library is best used.

Power imageUp!

Every time you find a bit of this information, no matter how small it can make all the difference about how productive you can be with the code, it’s like you have gained a power up. In fact often, maybe only in my head, I can hear one of those tinkling game sounds notifying me of some additional ability.

If we compare Dojo to the other libraries that can be used for working with ArcGIS we can see why the benefit of having a massive set of technical authors and production values can really streamline the help for a product. Whilst both Silverlight and Flex have had a number of versions, there have been no massive breaking changes like there has in Dojo. The relevant documentation is maintained on a single site, backed by a large company that provides an integrated experience including videos and professional tutorials and encourages staff to blog about the best practices of the use of the software.

imageDude where’s my manual?

Dojo on the other hand with its open source nature is always going to struggle to compete, unlike another JavaScript library such as the yahoo supported YUI. Which has a series of patterns to be used, a  comprehensive help system and someone (maybe more!), I assume, that is paid to maintain and promote this information.

Whilst products like Aptana can really help the developers productivity, that lack of a tightly integrated IDE like Flexbuilder and Visual Studio means that actually working out how something is used by looking at the objects and methods becomes a more complicated process. Couple that with a number of versions released in a relatively short time, including some major breaking changes between versions 0.4 and 0.9 and the search for help can be fraught with danger.

Just because a site says something might work in Dojo always be careful to read the label and check the version that it says it is based upon!

Doctor heal thy self!image

I know that the answer to this question is to contribute to the documentation myself, to make it better for   other people. Maybe I will if I ever get time, in the mean time I will resume my search for the mysterious documentation, if you don’t hear from me again I hope these notes will save to remind others of the perils that are fraught with the search for the Dojo doc. I will also leave clues about how you can find your way to the promised land of Dojo goodness.

Why are you still here? Go and read the doc and good luck with the power-ups!