Include a JavaScript Source File into Google’s CodeRunner or OpenSocialDevApp

OpenSocialDevApp or Google’s CodeRunner is a great tool for testing code snippets using OpenSocial API. It allows you to easily test code by cutting and pasting your JavaScript code into a textbox. You don’t need to load a gadget XML file into the server to test out something which can be a tedious process.

This works out really well when your code is small. However, once your code gets bigger, cutting and pasting starts to get painful. Wouldn’t it be nice if you can simply save your JavaScript code into a file, say mytestcode.js, and then just cut and paste a neat single line into the textbox like this?

<script type="text/javascript" 
    src="http://myserver.com/mytestcode.js"></script>

To test changes in mytestcode.js, all you need to do is re-execute CodeRunner every time you make an update to the file. No need for cutting-and-pasting.

However, this OpenSocial application only accepts raw JavaScript code, so the code above won’t work since it’s an HTML code.

To fix this problem, what we need is a way to convert the HTML code above into a JavaScript code. This is where the technique of dynamically including a JavaScript file comes to the rescue.

The code below is the script-src-tag converted into a JavaScript code. If you are not familiar with this technique, see this posting for details.

function includeJavascript(src) {
  if (document.createElement && document.getElementsByTagName) {
    var head_tag = document.getElementsByTagName('head')[0];
    var script_tag = document.createElement('script');
    script_tag.setAttribute('type', 'text/javascript');
    script_tag.setAttribute('src', src);
    head_tag.appendChild(script_tag);
  }
}
includeJavascript("http://myserver.com/mytestcode.js");

Instead of cutting-and-pasting the entire mytestcode.js into the CodeRunner’s textbox, just use the code above and make your changes directly to the mytestcode.js file on your server.

Furthermore, you don’t need to put all your code in a single file. You can break them up into multiple files and call out the include function for each.

includeJavascript("http://myserver.com/mytestcode1.js");
includeJavascript("http://myserver.com/mytestcode2.js");
includeJavascript("http://myserver.com/mytestcode3.js");
includeJavascript("http://myserver.com/mytestcode4.js");

With this technique, you can even run your entire OpenSocial application in CoderRunner!

Alvin Abad

When Firebug’s Console Object Cannot be Overridden

In my previous blog post, I’ve shown how to use Firebug’s console object to log debug messages. I’ve also shown how to perform graceful degradation if the console object is not available like when using a non-Firefox browser or if Firebug’s console is not enabled. This way, one can still retain the calls to console.log() without generating any error messages. However, there were still some issues I failed to address.

Production deployment

Normally, when you deploy code into production, you don’t want your debug calls to be included. You don’t want users to be getting those debug messages. There are two ways to fix this problem: 1) Add a step to your deployment process to search and remove all the debug calls in your code; or 2) Add some kind of a switch, say a global variable DEBUG, to decide whether to use Firebug’s console logger or redirect the call to a dummy console.log() that will not do anything. This functionality is similar to loggers like log4j in Java where you can set different settings (info, debug, etc.) to control logging without modifying the code.

Let’s say we wanted #2 above. The code below illustrates how this can be done.

    if (!window.DEBUG || typeof(console) == 'undefined') {
        console = {};
        console.log = function(msg) {
            return false;
        };
    }

If DEBUG is off (false), e.g., production, it will create the console object and implement a no-operation log() method. If the browser is Firefox, this will effectively override its console object, therefore, …

Wait, that is not correct. As of this writing (Firebug-v1.3.3), Firebug’s console object cannot be overridden! If you attempt to do so, you will get an error message of something like, “setting a property that has only a getter.”

Programming to an Interface and not an implementation

To fix this problem, what we should do instead is not use the Firebug console object directly to log messages. This is like the design pattern where one programs to an Interface and not an implementation.

Following this principle, we create our own implementation of the console object, let’s say mylogger. With this object, we can then control if we want to use Firebug’s console.log() or the dummy one depending on our DEBUG setting. Below is the modified version of the HTML page using mylogger.log().

<html>
  <head>
    <script type="text/javascript">
        DEBUG = true;

        // by default, set mylogger to do nothing
        mylogger = {};
        mylogger.log = function(msg) {
            return false;
        };

        // if DEBUG is true and Firebug console is available, use it for logging
        if (window.DEBUG && typeof(console) !== 'undefined') {
            mylogger = console;
	}
	    	    
        function demo() {
            // I did lots of things here          
            mylogger.log("I'm here!");
            // and a lot more          
        }
    </script>
  </head>
<body>
  <h1>Firebug's console.log() Demo</h1>
  <button onclick="demo();">Firebug console.log() demo</button>
</body>
</html>

The code above has a DEBUG switch that we set on the server side to true or false depending if we want to log messages or not. Instead of using the console.log() method directly in the demo() function, we use mylogger.log(). Since we cannot override Firebug’s console object, what we can do instead is make the decision whether to use it or not at runtime.

Debugging JavaScript Using Firebug’s Console Logger

Thanks to Firebug, debugging JavaScript has never been easier. Firebug is an add-on to the FireFox browser. It has many wonderful features. One of my favorite is the console logger. This is where you can call the function console.log() in your code to write log messages to the Firebug console. This is definitely much better than using the alert() function. It’s unobtrusive and transparent to the execution of your JavaScript program.

Below is a sample HTML page with JavaScript code demonstrating how to use this function.

<html>
  <head>
    <script type="text/javascript">
    function demo() {
        // do something          
        console.log("I'm here!");
        // do something          
    }
    </script>
  </head>
<body>
  <h1>Firebug's console.log() Demo</h1>
  <button onclick="demo();">Firebug console.log() demo</button>
</body>
</html>

The code above has a button element that will print out the message “I’m here!” to the Firebug console.

Graceful Degradation

Of course, console.log() only works with the Firefox browser, with Firebug installed, and the console is enabled. Otherwise, you’ll get an error saying the console object is not defined.

For browsers other than Firefox or if Firebug is not installed, you can still retain the console.log() calls in your code and avoid getting any error messages by redirecting this call to a no-operation. To do this, create a console object and an implementation of the log() method that does not do anything. Below is a sample implementation.

// if console is not defined, e.g., Firebug console is not enabled or Non-Firefox browser
if (typeof console == 'undefined') {
    var console = {};
    console.log = function(msg) {
        return;
    };
}

The code above shows that if the console object is not defined, like when using a browser other than FireFox, a console object will be created together with a method named log() that does not do anything. That console object will then be the one that will be used by your log() calls in non-Firefox browser or when Firebug console is not enabled, which will just fail silently.

The console.log() method also supports formatted messages similar to C or Perl’s printf function. For example:

console.log("This is loop %s", loop_counter);

Firebug’s console object is not limited to the log() method. It can do other cool things. You can learn more about them here – http://getfirebug.com/console.html

Many sites have discussed this topic with great examples and illustrations. Here’s a nice one – http://ajax.phpmagazine.net/2006/05/firebug_the_future_of_javascri.html.

Note: The solution presented here is not without problems. See my other post for details.
Alvin Abad

A Simple Cross-Domain Ajax

In spite of the power of the XMLHttpRequest API, its usage is limited by the “same-origin” policy. What this means is that the hostname of the url you are sending the XMLHttpRequest cannot be different from the hostname of the web server.

Understandably, the reason behind this is security. However, there are legitimate reasons why you would need to call out to other domains, for example, you have a site with multiple domains or sub-domains and you would need to call XMLHttpRequest to these different domains.

One way to get around this issue is to let the server-side, on behalf of the client browser, perform the HTTP request to the external site. This functionality is best explained here. But this doesn’t sound like the true Ajax we imagined because we wanted to use the same idea of XMLHttpRequest where you can call out a URL from the browser, with the only difference that it can be a different domain.

So how does one perform an Ajax request using a different domain?

Below is a simple example of a cross-domain Ajax:

<html>
<head>
<script type="text/javascript">
    function xss_ajax(url) {
        var script_id = null;
        var script = document.createElement('script');
        script.setAttribute('type', 'text/javascript');
        script.setAttribute('src', url);
        script.setAttribute('id', 'script_id');

        script_id = document.getElementById('script_id');
        if(script_id){
            document.getElementsByTagName('head')[0].removeChild(script_id);
        }

        // Insert <script> into DOM
        document.getElementsByTagName('head')[0].appendChild(script);
    }

    function callback(data) {
        var txt = '';
        for(var key in data) {
            txt += key + " = " + data[key];
            txt += "\n";
        }
        alert(txt);
    }

    var url = "http://alvin-samplejson.appspot.com/callback_json.php";

</script>
<title>Simple Cross Domain Ajax</title>
</head>
<body>
<h1>Simple Cross Domain Ajax</h1>
<button onclick="xss_ajax(url);">Get Data</button>
</body>
</html>

The JavaScript code above has two functions: xss_ajax() and callback(). The first function, xss_ajax(), performs the HTTP request given a URL. This function mimics the XMLHttpRequest’s open() and send() methods combined. The URL passed to it is not limited by the same-origin policy, thus, it can be any domain name. The second function, callback(), is a function that processes the data returned by the HTTP request performed by xss_ajax().

In the HTML body, I have included a button element to demonstrate a call to the xss_ajax() function.

To try out this example, simply save this code into a file, load it into your browser, e.g., file:///C:/simpleCrossDomainAjax.html, and hit the “Get Data” button.

As you will see, even if the origin is a local file, it can still perform an HTTP request to a different domain and be able to return a response. (http://alvin-samplejson.appspot.com/callback_json.php)

One thing that is different from the XMLHttpRequest API is that the response of our http request cannot be a true JSON object (or XML). Instead, it needs to be constructed with a string-like function call, where its parameter will be the true format of the object you wish to return.

Viewing the sample URL:
http://alvin-samplejson.appspot.com/callback_json.php

the response of the PHP page will look like this:

callback({"firstname":"John","lastname":"Smith","email":"john.smith@johnsmith.com"});

Below is the PHP code that is used for the HTTP request:

<?php
$obj = array();
$obj['firstname'] = "John";
$obj['lastname'] = "Smith";
$obj['email'] = "john.smith@johnsmith.com";

$response = "callback(" . json_encode($obj) . ");";
print $response;

/**
  Browser prints this out as:
  callback({"firstname":"John", "lastname":"Smith", "email":"john.smith@johnsmith.com"});
**/
?>

The “callback” function string as returned by the HTTP request triggers the call to the callback() function.

The magic behind all this is in the usage of the <script> DOM element. As we all know, a web browser can load a JavaScript source file from a different domain. For example:

<script type="text/javascript"
  src="http://external-domain.com/myjavascript.js"></script>

What this code is doing is performing an HTTP request to external-domain.com, fetching the file myjavascript.js, and loading its content.

If this can be done to a javascript file, then it can be done as well to a regular HTML file, or to any type of HTTP requests, e.g. cgi, php, jsp, etc. For example:

<script type="text/javascript" src="http://external-domain.com/mypage.html"></script>
<script type="text/javascript" src="http://external-domain.com/mypage.cgi"></script>
<script type="text/javascript" src="http://external-domain.com/mypage.php"></script>
<script type="text/javascript" src="http://external-domain.com/mypage.xml"></script>

Based on this principle, in order to mimic an XMLHttpRequest kind of call, all we need to do is programmatically create a script element at runtime every time the browser needs to perform an HTTP request. Line numbers 6 to 9 in the xss_ajax() function above performs this dynamic creation of the script element. Line number 17 is when the script element is inserted into the DOM that will trigger the actual execution of the script tag.

Since the script element tag expects a JavaScript code, the response of the URL specified must be executable like a JavaScript code. That is why our PHP code above returns a “callback()” string instead of the raw JSON object. When the script-tag gets created, the browser will see this function-call-like string and will execute it.

The example above only performs a simple HTTP request without any parameters. What if we need to send request parameters? Since the script-tag follows the same principle of making an HTTP GET request, passing request parameters would be the same thing as adding the query-strings to the URL, For example:

<script type="text/javascript"
  src="http://otherdomain.com/mypage.php?name=JOHN&password=secret"></script>

Therefore, to make our xss_ajax() support request parameters, all we need to do is simply add the request parameters to the URL.

Alvin Abad

Extending JavaScript’s String Object

If you are the kind of programmer who works on multiple projects using different languages at the same time, I bet you sometimes can’t help mix things together and subconsciously expect that a method/function you commonly use in one language is also available in the other. And when this happens, you suddenly pause and realize that the function you are about to type doesn’t exist in the language you are currently writing. What could be worse is when you cannot instantly remember the syntax of the method you want to use and you have to scramble and look up the API documentation. The interruption can be annoying. Wouldn’t it be nice if you can simply use the same method that you are always familiar with in the other language?

The good news is that when it comes to JavaScript, this language is so flexible and powerful it can easily fix this problem.

For example in Java, there is this method s.trim() that you call on a string object s to remove any leading and trailing whitespaces. Unfortunately in JavaScript, this method is not available. Of course you can always write a separate function to implement this method, for example, mytrim(s). But wouldn’t it be nice if you can use it the same way you use it in Java? This way, you wouldn’t have to consciously remember about your mystrim(s) function and just let your fingers do the thinking and type it like the way you always do: s.trim().

Fortunately, JavaScript is a very powerful object-oriented programming language. You can easily extend the String object to add a method. This is accomplished by creating a function implementing the functionality you desire and attaching it to String.prototype. Below is a sample implementation of the trim() method.

String.prototype.trim = function () {
    return this.replace(/^\s+|\s+$/g, "");
};

After loading the code above, you can now use s.trim(); where s is the string object.

Below is a sample html page where you can try out this feature. Create this html file and load it into your browser.

<html>
<head>
<title>Extending String object</title>
<script type="text/javascript">
    String.prototype.trim = function () {
        return this.replace(/^\s+|\s+$/g, "");
    };

    var mystring = "       hello, world        ";
    document.writeln("
<pre>");
    document.writeln("Has leading and trailing spaces: [" + mystring + "]");
    document.writeln("Spaces removed: [" + mystring.trim() + "]");
    document.writeln("</pre>
");
</script>
</head>
<body>
</body>
</html>

You should see the output like this:

Has leading and trailing spaces: [       hello, world        ]
Spaces removed: [hello, world]

If you are coming from Python and are used to the upper() method to convert characters to uppercase, you can implement the same method in JavaScript. JavaScript already has this method but it is called toUpperCase(). But if you prefer the Python way, so that you can just let your fingers do the thinking, the technique to accomplish this is the same:

String.prototype.upper = function () {
    return this.toUpperCase();
};

As you can see above, we didn’t have to write our own implementation. We simply use JavaScript’s built-in toUpperCase() function to duplicate it.

Extending JavaScript’s String object is not for everyone. This may not be a good idea to some people because this can cause confusion if one is not aware that an extension has been introduced. Some people would rather prefer implementing the functionality using a separate namespace, e.g., MyStringUtil.trim(s), instead of extending the string object. This makes it clear that an external API is being used.

Five Easy Steps to Learn JsUnit

If you already know JUnit or PyUnit, it shouldn’t take you more than ten minutes to learn how to use JsUnit. JsUnit is a Unit Testing Framework for Javascript. It is a JavaScript version of JUnit.

Below are five easy steps you can follow to quickly learn JsUnit.

Step 1. Download JsUnit zip file and extract it to a local directory.

http://jsunit.net/
http://downloads.sourceforge.net/jsunit/

Step 2. Create a sample function that you will use to test using JsUnit.

For example, let’s create a function that adds two numbers. Save this code into a file and name it “myAdd.js”.

// myAdd.js
function add(x, y) {
    return (x+y);
}

Step 3. Create an HTML file and name it “testMyAdd.html”.

In the HEAD section of this file, include the JsUnit source code and your myAdd.js file. In the BODY section, write your testcase functions as shown below. Similar to JUnit and PyUnit, the names of testcase functions must begin with “test”.

“testAdd.html”

<html>
<head>
    <title>Test Add Function</title>

    <script type="text/javascript" src="junit/jsUnitCore.js"></script>
    <script type="text/javascript" src="myAdd.js"></script>

</head>
<body>
<script type="text/javascript">
    function setUp() {
        // fixture setup before running a testcase
    }

    function tearDown() {
        // anything to cleanup after running a testcase
    }

    function testAdd() {
        assertEquals("", 3, add(2, 1));
    }

    function testAdd2() {
        assertNotEquals("", 0, add(2, 1));
    }
</script>
</body>
</html>

Step 4. Using a browser, locate the file “jsunit/testRunner.html” and load it.

Step 5. On the testRunner.html page, enter the testpage URL (testAdd.html) and click on the RUN button.

When JsUnit loads the testpage, it will automatically find all testcase functions and run them in sequence.

That’s it! You now have a working JsUnit testcase. Of course, JsUnit has more to offer than this simple example. But this should get you started as you explore more features of JsUnit. See online doc for more details: http://jsunit.net/documentation/index.html

Dynamically Including JavaScript and CSS Files

In C/C++, if you want to include code from another file, you use the #include directive. In PHP, you use the require or include command. In Java and Python, you use the import command to import a library. In Perl, you use the require or use command. However in JavaScript, for some reason, it doesn’t have this functionality. :(

What is expected in JavaScript is that you do the includes externally on the HTML page using the script-src tag. But there are many limitations with this option. Wouldn’t it be nice if you can simply perform includes just like you do it in other languages?

Fortunately, there is a workaround!

What you do is dynamically create the script tag element at runtime in the DOM. Below is a JavaScript function where you simply call whenever you need to include a JavaScript src file.

function includeJavascript(src) {
    if (document.createElement && document.getElementsByTagName) {
        var head_tag = document.getElementsByTagName('head')[0];
        var script_tag = document.createElement('script');
        script_tag.setAttribute('type', 'text/javascript');
        script_tag.setAttribute('src', src);
        head_tag.appendChild(script_tag);
    }
}
// Include javascript src file
includeJavascript("http://www.mydomain.com/script/mynewscript.js");

The idea behind this is that a new script-src tag is dynamically constructed in the DOM at runtime. It will be like adding this line to the <head> section of the web page but dynamically:

<script type="text/javascript"
   src="http://www.mydomain.com/script/mynewscript.js">
</script>

The same idea can be applied to CSS files. Below is a function where you can include CSS files programmatically.

function includeCSSfile(href) {
    var head_node = document.getElementsByTagName('head')[0];
    var link_tag = document.createElement('link');
    link_tag.setAttribute('rel', 'stylesheet');
    link_tag.setAttribute('type', 'text/css');
    link_tag.setAttribute('href', href);
    head_node.appendChild(link_tag);
}

Chaos in server-side or client-side of web development, which do you prefer?

On the server-side of web development, there are dozens of programming languages you can use. And for each language, there are dozens of frameworks to choose from. This has created language and framework wars. It’s a war zone out there.

On the client-side of web development, things might be less stressful you might say, because there is only one programming language. Yes, Javascript! Thank God, people agreed on using just one language.

Oh wait, we have different Javascript frameworks and toolkits. Developers on the client-side of web development now have toolkit wars. But that is not the biggest problem. In spite of having only one programming language, that doesn’t mean it works perfectly on all browsers. Developers have to battle browser incompatibilities in their Javascript code everyday. Browser wars is very much alive!