My time in Singapore so far has been a really good learning experience. I have been the lead for doQer, a startup launched by Remarkable Innovation. It is really exciting as it makes it easy for people to manage and view user manuals. No more downloading huge PDF files and not find the information you were looking for, or being stuck in a flash window inside your browser.

I have been priviledged to have a lot of say in giving direction to the project alongside Mark Reilly. Don’t mind my beloved and super comfortable Aeron Chair (my back thanks you), or really nice dual monitor setup. Finally I was able to mold my development practices to the Joel Test.

For those who don’t know the Joel Test, it is a list of good practices a Software company should have:

1. Do you use source control?
2. Can you make a build in one step?
3. Do you make daily builds?
4. Do you have a bug database?
5. Do you fix bugs before writing new code?
6. Do you have an up-to-date schedule?
7. Do you have a spec?
8. Do programmers have quiet working conditions?
9. Do you use the best tools money can buy?
10. Do you have testers?
11. Do new candidates write code during their interview?
12. Do you do hallway usability testing?

I must confess that not all items were ticked off, specially since lots don’t apply to web development. However it is very (very much) satisfying to see development moving to have more solid practices put in place!

Now with my moving back to Melbourne I have to start job hunting. A browse for jobs in Seek was not very exciting. The jobs section at Stack Overflow seems like a better place to start. Too bad most jobs are in the United States.

I am determined to take the inverse approach, find an awesome work place and drop them a note instead.

I would love to know what companies have good development practices in Melbourne. Would appreciate if anyone could drop me a note in the comments, or in this thread I started in Whirlpool!

It must be a sign. I am scared!

Right. No problems coming up with that, but what should I look for and where should I start?

After doing my reading I decided on two main selling points for me to join a project: Fun and Something-I-Would-Use

The first part was easy. Of course it should be fun! It is something I am going to be spending my free time on.

The big contributor to the fun part is doing something that is interesting to me. Although coding itself is already enjoyable, working on something compelling will get me going. How many times have I not gotten too excited explaining how I solved a problem or fixed a bug, when a person expected a simple answer by asking how my day was.

Ted Leung was talking about people who joins open source projects in the Herding Code podcast:

In general the whole thing with open source is you let people work in what they are interested in. They will probably gravitate towards what they are interested in and what they are good at. That means their quality of work will be a lot higher.

I agree. If working with something that interests me will generate quality output, and I get some fun out of it; I am happy with that!

Now the Something-I-Would-Use part. I came to that conclusion reading a post on Steve Yegge’s blog which was not on joining open source projects, but I believe is still applicable to this situation:

So when translated into project selection, Buffett’s and Lynch’s advice becomes: only build what you know. The longer, more accurate of the version of the investing rule — only invest in what you know and are excited about using yourself right now — has a simpler formulation for products and businesses.

Steve was talking about how software requirements are unimportant (not exactly the word he used). Specially if you are working on something that you use, because you know what the requirements are.

Again, I totally agree. People should join a project of a product they use in their own time. It will benefit from the current knowledge and experience of how the product should behave.

So now I am off to Google Code, Sourceforge, and Freshmeat to find a project that is fun and it is something-I-would-use.

I have really been enjoying writing JavaScript with JQuery; it has saved me time writing concise code which also helps me debug and maintain it. So I thought it would be a good idea to rewrite my Ajax example with JQuery to compare its usefulness.

In my previous code I had to first create the XMLHttpRequest object:

var xmlHttpReq;   

// Determining which browser we are dealing with 
if (window.XMLHttpRequest)
{
   xmlHttpReq = new XMLHttpRequest();
   xmlHttpReq.overrideMimeType('text/plain');
}
else if (window.ActiveXObject)
{
   // this is required if the browser is IE
   xmlHttpReq = new ActiveXObject("Microsoft.XMLHTTP");
}

Then I had to prepare the query string and post to the script that would get the me the details:

// generate the query string to post to the script
var queryStr = 'PostCode=' + escape(postcode);

var strURL = 'postcode_lookup.php';

xmlHttpReq.open('GET', strURL, true);
xmlHttpReq.setRequestHeader('Content-Type', 'application/x-www-form-urlencoded');
xmlHttpReq.onreadystatechange = displayPostcode;

// post to script
xmlHttpReq.send(queryStr);

That is too much work! With JQuery things are much easier:

$.get("postcode_lookup.php",
      { PostCode: jQuery('input[@name=PostCode]')[0].value },
      function(data)
      {
         /* Logic to parse data and determine output goes here */

         // Writing output into div
         $("#outputDiv").html(output);
      }
);

That’s it! All it takes is one function to make the Ajax call and then parse the data from the script.

The jQuery.get( url, [data], [callback], [type] ) function takes four parameters. But we are only using three as the last one is optional:
1. The script: postcode_lookup.php.
2. The parameters for the script contained in an array. In this case the value of the text field:
{ PostCode: jQuery(‘input[@name=PostCode]‘)[0].value }
3. The callback function to handle the data returned from the script.

I am quite happy for the amount of work that it has saved me. However I cannot emphasize enough how important it is to understand how the XMLHttpRequest works.

You can find the working example here.

This application came from my dependence on public transport and possible need to move houses; I wanted to know how close I would be in relation to train stations. There are quite a number of stations in Melbourne, and I don’t have the time to map all of their coordinates, so at the time being it only has train stations from the City Loop.

The application uses GDirections. It lets us load way points and retrieve the route details; such as distance, driving directions, and even an HTML summary of the travel.

I used GDirections in two instances of the application:
1. To determine the distance between my pivot position and the train stations.
2. To plot the route of my pivot point to the closest train station

In both instances I used GDirections in the same way:

var directions = new GDirections();

// Put pivot location and the selected train station into an array   
var lArray = new Array();
lArray.push( start );
lArray.push( end );

// Load route from pivot location to train station
directions.loadFromWaypoints(lArray);

After I loaded the way points it is possible to retrieve information such as the distance in meters:

directions.getDistance().meters

However I ran into a problem: I was loading the way points but it was returning me NULL. That is because the loading is done asynchronously, so to retrieve the details we have to wait until it loads completely. To do that we create an event listener:

GEvent.addListener(directions,"load", function()
{
   // Here directions should not be NULL
   var distance = directions.getDistance().meters;
});  

After we calculate the shortest distance, we are ready to render the route on the map. To do that I passed the map as an argument when initialising GDirections.

// Clear map and panel
map.clearOverlays();

var directions = new GDirections(map);

// Array with the shortest route
var lArray = new Array();
lArray.push( start );
lArray.push( end );

directions.loadFromWaypoints(lArray , {preserveViewport: true});

Note that I used the preserveViewport option. That is so the map won’t change zoom or position when rendering the route.

Please drop me a message if anyone knows where I can find free coordinates of the train stations, and I will add them to the application.

• To pop up an info window with marker description.
• To handle clicks and create new markers.
• To use markers with custom images.

To pop up an info window with marker description
Google maps handles clicks through event listeners. Thus, to open the info window we use the GEvent object:

GEvent.addListener(marker, 'click',
      function()
      {
         var htmlString = "<font color=\"#6387A5\" size=\"1\"
                                 face=\"Verdana, Arial, Helvetica, sans-serif\">"+
                          description+"<br/>" +
                          "(" + latitude + "," + longitude + ")</font>";
         marker.openInfoWindowHtml(htmlString);
      }
   );

The addListener method takes your marker, event type, and a callback function. The callback function is executed when the event is fired, and it calls marker.openInfoWindowHtml which opens an info window.

We also pass a string with the openInfoWindowHtml method, which will be displayed in the info window.

To handle clicks and create new markers
We also handle clicks on the map with GEvent, but this time we add a listener by passing the map instead of the marker:

GEvent.addListener(map, "click", function(overlay, location) {

         if( overlay )
         {
            // clicked on something other than the map

         }
         else
         {
            var description = prompt("Please enter marker description", "");

            // create a new marker
            if( description != null )
               addMarker(location,description);
         }

      });

I had an issue that triggered the map event when clicking on an info window. Ideally we should be able to tell where the click came from, and handle the event appropriately. This is possible with the callback function taking two arguments: an overlay, and the coordinates of the click.

The first argument is the overlay that was clicked by the user; for example markers and info windows. Therefore, when the first argument is not an overlay we can safely say that the user clicked on the map.

To use markers with custom images

We use the GIcon object to create markers with custom images. Once we create an instance of GIcon we pass it into the GMarker constructor; displaying the custom image instead of the default marker.

In the example we randomly use one of the three custom markers:

// create new gicon to use with the marker
var customIcon = new GIcon();

// put in random image
var pos = Math.floor(Math.random()*3);
var images = new Array("images/marker_green.png",
"images/marker_blue.png",
"images/marker_yellow.png");
customIcon.image = images[pos];

customIcon.iconSize = new GSize(20, 34);
customIcon.iconAnchor = new GPoint(10, 34);
customIcon.infoWindowAnchor = new GPoint(10, 0);

// create new marker
var marker = new GMarker(location,customIcon);

Creating markers is fairly simple:

1. Create a new instance of GLatLng object. The GLatLng holds the coordinates of your marker.

// create new location object
var location = new GLatLng(latitude, longitude);

2. Create a new instance of GMarker with the GLatLng object.

// place new marker
var marker = new GMarker(location);

3. Use the addOverlay method to create a new overlay in the map.

map.addOverlay(marker);

Just like we add an overlay to create a marker, we clear a marker by removing an overlay.

map.removeOverlay(markersArray[idx]);

The markersArray[idx] is the GMarker we would like to remove. If you are not using an array to keep your markers, you can pass in an instance of GMarker directly.

The xmlHttpReq object is responsible for the responsiveness of an AJAX application. It allows the JavaScript to make asynchronous HTTP request (POST or GET) to a script. The same xmlHttpReq object handles the output of the script through a callback function.

The example that I wrote is an Australian postcode lookup. Basically, the user enters a postcode which is then posted by the xmlHttpReq object to a PHP script. The script returns comma delimited details of the postcode, which is processed by the callback function, and displayed nicely to the user.

Click here to see working example.

The Query String

We post the data to the script using a query string; the string will later be passed into the xmlHttpReq object.

In our case the data we post to the script is the postcode; for example ‘PostCode=3000′.

var postcode = document.forms[0].PostCode.value;

// generate the query string to post to the script
var queryStr = ‘PostCode=’ + escape(postcode);

It is possible to pass more variables with the query string; for example ‘PostCode=3000&Location=Melbourne’.

Note that we encode the postcode when building the query string using the escape function.

The xmlHttpReq Object

Now it is time to create the xmlHttpReq object. We initialise it differently for Internet Explorer and Mozilla, thus we need to detect the user’s browser.

var xmlHttpReq;

// Determining which browser we are dealing with
if (window.XMLHttpRequest)
{
   // this is required if the browser is Mozilla
   xmlHttpReq = new XMLHttpRequest();
   xmlHttpReq.overrideMimeType(’text/plain’);
}
else if (window.ActiveXObject)
{
   // this is required if the browser is IE
   xmlHttpReq = new ActiveXObject(”Microsoft.XMLHTTP”);
}

We can now set the parameters for the xmlHttpReq object. The open function takes three parameters: HTTP request method, script to send the request to, and a flag that determines whether the request is asynchronous.

var strURL = ‘postcode_lookup.php’;

xmlHttpReq.open(’POST’, strURL, true);

Finally we set the callback function displayPostcodethat will handle the script’s output.

xmlHttpReq.setRequestHeader(’Content-Type’, ‘application/x-www-form-urlencoded’);

xmlHttpReq.onreadystatechange = displayPostcode;

The Callback Function

The callback function that we set in the previous section will be called whenever the state of the request has changed. When the request is completed, the xmlHttpReq.readyState will be set to 4.

function displayPostcode()
{
   document.getElementById('outputDiv').innerHTML = "";

   var postcodeData = "";
   var output = "";
   if (xmlHttpReq.readyState == 4)
   {
      postcodeData = xmlHttpReq.responseText.split(",");

      output = "";
      // processing information produced by the script
      if( postcodeData.length > 1 )
      {
         output = "Postcode: " + postcodeData[0] + "<br/>";
         output += "Locality: " + postcodeData[1] + "</br>";
         output += "State: " + postcodeData[2] + "<br/>";
         output += "Category: " + postcodeData[9] + "<br/>";
      }
      else
         output = "Postcode not found!";

      // writing output into div
      document.getElementById('outputDiv').innerHTML = "” + output + ““;
   }
   else
   {
      document.getElementById('outputDiv').innerHTML = "loader.gif";
   }
}

The callback function simply updates a div by looking at the information returned by the xmlHttpReq.responseText. While the request is not finished, we display a loading animated gif.

The Request

We have a xmlHttpReq object setup, and a callback function to handle the data returned by the script. Now we are ready to send the HTTP request to the script.

// post to script
xmlHttpReq.send(queryStr);

That’s it! We have a simple AJAX Postcode search. For this example the script is set to sleep for a couple of seconds, just so we can show off the loading gif :)

The zip file with the source code can be downloaded here.

The loading gif was originally downloaded from here, and the data with the postcode information was downloaded from the Australian Post website.