Caja is a project started by google a few years ago to provide a way to safely embed third party DHTML code on your own web page, as well as rich communication interfaces between the embedding page and the embedded applications. Normally to embed third party code one would use iframes, but with the capability of javascript to communicate between frames this can be a serious security breach.

At this point google caja provides you with a neat solution. First of all you will not need any iframes to embed third party code on your web page safely, the java based cajoler will provide you with html and javascript that is sand-boxed and secure to embed once it is cajoled. Don’t get me wrong, Java will only be needed to compile possibly hazardous code once, into the cajoled secure code one can use on his website. After that it is all done by the javascript libraries provided by the caja project.

But let me show you how the magic works.

First of all you will need to install some software:

• JDK 6
• The subversion version manager
• The Apache Ant build system.
• The JUnit testing framework. Just drop junit.jar</tt> in the $ANT_HOME/lib directory you set up for Ant.

Then create some folders for your caja project, for this I assume you will use Linux or Mac OS:

mkdir caja
cd caja
mkdir svn-changes
cd svn-changes
mkdir pristine
cd pristine

After you have done this you will need to check out caja from the SVN – Repository:

svn checkout http://google-caja.googlecode.com/svn/trunk/ google-caj

Following the wiki of the caja project I assumed simply running “ant demos” on the console would provide me with some working demos. To make a long story of yelling and cursing short, no it didn`t. After long sessions of trail and error and a post on the discussion board where Jasvir Nagra pointed me in the right direction I found out why.

First of all several sources of the projects wiki as well as the sources compiled by ant will show you that you have to integrate the valija js the following way:

<script src="valija.co.js" type="text/javascript"></script>

;
What´s the problem with that ? There is simply no valija.co.js anywhere in the whole project !! But there is a “valija.out.js”. Simply use that file name and one of your setup problems will be gone. Yes right, one, there are several more traps I will show you.

Next thing you will notice, running firebug, is that cajoling source ,either via applet or via war (generated via ant playground), will not work but return a 500 Internal Server error.

Though I am a huge fan of software running out of the box I assumed that running either “ant playground” or “ant demos” ( / “ant testbed” for testbed only) would provide me with a running demo to play with. It didn´t. The reason why I found out after I had setup jetty Java server in debug mode, like Jasvir suggested. The log then showed me that some nu.validator.* library was missing in my jar file that was compiled by ant. Because I had been looking through all the project files and folders at my days of yelling and cursing I new where to find it. This Lib with all the needed classes is stored in “$cajaSourceFolder/third-party/java/htmlparser/src”. So there is a simply solution for that, simply copy the “nu” – folder to “$cajaSourceFolder/src” and run “ant testbed” or “ant playground” again.

Tada,… problem solved. Either you will get a working testbed by now or a working playground war.

To play at the playground I would suggest that you use jetty. The use of the server to my mind is quite easy. Simply download the src here, unpack it, switch to the folder and run:

$cajaSourceFolder: ant playground
$jettyHomeDir/webapps:ln -s $cajaHomeDir/ant-war caja-playground
cd ..
$jettyHomeDir: java -jar start.jar etc/jetty-logging.xml etc/jetty.xml

By now you will have jetty running on port 8080 at localhost and caja-playground can be found at:

http://localhost:8080/caja-playground

But we don´t only want to play do we ?

So after playing around a little bit with either the playground or the testbed application I assume you would like to use what you have produced with either of those in a simple host page. Ten years of doing this job by now I thought the wiki might provide me with a simple solution for a host page that would be working right away. Hhmmm sorry nope. Wrong again. It does not.

Don`t get me wrong there is an example. It simply does not work with the code that you can download at the projects page. Simple as that. But this could not keep me from setting up one simple example, by braking down the playgrounds web page to the minimum needed to get it running.

Same procedure as every year Ms Sofia ? Same procedure as every year James. If nothing helps reverse engineering does it each and every time.

The nice guy I am I will save you some time and give you a step by step of what is needed to get the cajoled code running in a simple as can be host page.

First thing you will need to get the cajoled code running will be this inside the body tag of your page:

<!-- Load all needed scripts -->
     <script src="cajita.js" type="text/javascript"></script>
     <script src="unicode.js" type="text/javascript"></script>
     <script src="css-defs.js" type="text/javascript"></script>
     <script src="html4-defs.js" type="text/javascript"></script>
     <script src="html-sanitizer.js" type="text/javascript"></script>
     <script src="html-emitter.js" type="text/javascript"></script>
     <script src="setup-valija.js" type="text/javascript"></script>
     <script src="bridal.js" type="text/javascript"></script>
     <script src="domita.js" type="text/javascript"></script>
     <script src="valija.out.js" type="text/javascript"></script>

The next step will be to provide a method that will assign the containers for your cajoled widget:

<script type="text/javascript">
  var imports = ___.copy(___.sharedImports);
  var gadgetRoot = "";
  imports.outers = imports;

  function setGadgetContainer(containerId){
    gadgetRoot = document.getElementById(containerId);
    imports.htmlEmitter___ = new HtmlEmitter(gadgetRoot);
    attachDocumentStub('-g___', {
      rewrite: function(){
        return null;
      }
    }, imports, gadgetRoot);
    imports.$v = valijaMaker.CALL___(imports.outers);
    ___.getNewModuleHandler().setImports(imports);
  }
</script>

This code simply initiates the base for caja and assigns a container for the widget. But lets go on with the html you will need for your page:

<div id="cajoled-output" class="g___">
           {Here goes the html output of the cajoler}</div>

<!-- Load widget 1 -->
<script type="text/javascript">setGadgetContainer("cajoled-output");</script>
<!-- The Cajoled javascript output put in an external file -->
<script src="widgets/widget1.vo.js" type="text/javascript"></script>

You might have recognized the ” class=’g___’ ” that is also mentioned in the js method. This is nescessary for the html code rendered dynamicly by the caja libary to assign the content to the container.

This is it. If you followed the instructions you should have a working google caja playground, demo, webservice and jetty server by now as well as a working basic stand alone page witch will run you cajoled code.

First of all you will need to download the following two files from the jQuery Api – Docs Website:

Qunit.js
Qunit.css

Afterwards you will need to create a new html file with the following code:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
      "http://www.w3.org/TR/html4/loose.dtd">
<html>
  <head>
    <link rel="stylesheet" href="core/qunit.css" type="text/css"/>
    <script src="http://code.jquery.com/jquery-latest.js"> </script>
    <script type="text/javascript" src="core/qunit.js"></script>
    <script type="text/javascript">
     // --- Unittest Code goes here ---
    </script>
  </head>
  <body>
    <h1 id="qunit-header">QUnit example</h1>
    <h2 id="qunit-banner"></h2>
    <h2 id="qunit-userAgent"></h2>
    <ol id="qunit-tests">
    </ol>
  </body>
</html>

This Html file will be the page we can view the testresults on.

In this tutorial I only like to give you a brief overview of what can be done how, because most of you will be familiar with writing unittests at other languages, and in the case of javascript and jQuery this will be almost the same.

So lets go write our first unittest:

  $(document).ready(function(){
    module("Basic Unit Test");
    test("Sample test", function()
    {
       expect(1);
       equals(divide(4,2),
        2,
        'Expected 2 as the result, result was: ' + divide(4,2));
    });
  });

If you now open the the html page in your prefered browser you will see something like this:

Your unittest failes, just like one might have expected because we never implemented the divide method into our code. But lets go step by step. You might have recognized several different parts of code in the js – snippet that need a little explanation.

First of all we have a line “module(“Basic Unit Test”);”. By adding this we are able to separate the modules we want to test visually on the test page. If you take a look on that page after running the tests you will read “1. Basic Unit Test module: Sample test (1, 0, 1)” at the moment. So the string we have set by adding “module(“Basic Unit Test”);” to our code is displayed there as well as some more information we have provided by the lines that followed this one.

Next line we have added so far was “test(“Sample test”, function(){});”. This is basically the declaration of a single test that you run. The first parameter is a String that simply gives the test a name(“1. Basic Unit Test module: Sample test (1, 0, 1)”), the second one is a callback function that is called the moment we run the test by loading the page. Lets go on analyzing the code we just tested.

Next thing you might have recognized is “expect(1);”, this is a simple declaration how many assertions we expect at this single test. At the moment we run only one so this is set to one. If we had set this one to two for instance, the result of our test would be that not one assertion has failed but two, because in that case we would also have forgotten to implement the second assertion.

Lets move on to the last line we just implemented “equals(divide(4,2),2,’Expected 2 as the result, result was: ‘ + divide(4,2));”. This is the actual assertion we wanted to make, just to make sure that the method “divide” works properly and returns the mathematical correct result. The Qunit method equals takes three parameters. The first one and the second one are the ones compared, the third is a String, a message you might want to print out. This message is handled by the Qunit.log() method I will show you later.

Besides the method equals there are two more methods provided to you for testing. They are called “ok” and “same”. While “ok” is a simple Boolean check and for this only takes two parameters, the Boolean value that has to be true in order to not make the test fail, and a message, the “same” method is kind of like equal. The only difference between those two is that equal only returns true if both, the first and the second parameter, are 100% equal ( like a === b), and same only compares the variables values vs. each other.

But let me give you some example code:

  var arrayContainer = {a: 'firstElement'};
  equals(arrayContainer, {a: 'firstElement'}, 'Will fail');
  same(arrayContainer, {a: 'firstElement'}, 'Will pass');

After describing the basics to you we can now start to make our test working. This is quite easy just add the following to your code:

  function divide(a,b)
  {
    return a / b;
  }

Your unit test passed, congratulations. But if you are a little bit like me you are missing the message we added to the equals assertion in our test, it is not displayed anywhere at our page, and even if you look at the console there will be nothing. This is because the public method Qunit.log() was indeed declared in the class file, but no code that would display the messages has been implemented. To my mind this was because the developers of Qunit wanted it to be up to your decision whether or not you like to display them.

It is done really easy and in this tutorial I will show you how to display them in the console of the browser (though it has one), just add the following on top of the ready callback :

  QUnit.log = function(result, message)
  {
    if (window.console && window.console.log)
    {
      window.console.log(result +' :: '+ message);
    }
  }

If you now reload the Unittest page, open up Firebug for instance (in prior), and switch to the console view of Firebug you will see this:

By now you should have the gear to develop some unittest for jQuery or any other javascript  you use might in your project. I hope this tutorial has given you a good overview and a nice point to start from.

The following link provides a zip file with the summary of this tutorial:
jQunit-tutorial.zip

   function accessIframeJS(IframeName, methodName, methodParams)
   {
    var  IFrameObj  = window.frames[IframeName];
    var  methodCall = "IFrameObj."+methodName+"("+ methodParams +")";

    try{
       eval(methodCall);
    }catch(error){
       // some code here for error handling
    }
   }

Traced on Firebug it turns out that FireFox loses the IFrameObj on Drag & Drop while rewriting the DOM. Took me quite a while, and a long talk with uncle google until I took a look at bugzilla of mozzilla and the huge amount of iframe Bugs mentioned there. But I found the solution after reading alot of those posts,.. and yes as all ways it is an easy one, if you knew the solution.

function accessIframeJS(iframeId, methodName, methodParams)
 {
  var IFrameObj = document.getElementById(iframeId).contentWindow;
  var methodCall = "IFrameObj."+methodName+"("+ methodParams +")";

  try{
     eval(methodCall);
  }catch(error){
     // some code here for error handling
  }
 }

Ta ta,… this works everywhere,… but it took me a long search, until I found the post in Bugzilla.

First of all you will need the basic wrapping:

(function($){
   // your js code goes here
})(jQuery);

This wrapping adds your code to the jQuery library if you add the js file to your page.
Next thing you will have to do is add the basic functionality to your plugin.

$.fn.yourPlugin = function(options){
}

By adding those lines to your js file within the first code snippet you now can access your plugin by:

$('#yourDomElement').yourPlugin();

Next you need to know the difference between private and public vars within the class you are developing. If you write something like:

   /**
     * default options for plugin
     * private
     * @var array defaultOptions
     */
    var defaultOptions = {
        action:       false,
        debug:        false
    }

This would be a private var witch is only accessible within the class it self. If you need to have a var of your class to be public you have to write something like this:

   /**
     * default options for plugin
     * public
     * @var array defaultOptions
     */
    $.fn.yourPlugin.defaultOptions = {
        action:       false,
        debug:        false
    }

One word has to be said by now, public variables can only be defined after the declaration of the constructor of your plugin, otherwise the compiler will throw a nice little javascript error because “yourPlugin” was not defined yet.
Now that we have learned this we can go on with the possibility of configuration for the plugin. Like in every other language we will need to have some basic properties for the class that can be overwritten by your needs. To do something like that is quite simple:

   /**
     * yourPlugin base constructor
     *
     * @param [] options
     * @return void
     */
    $.fn.yourPlugin = function(options){
        // extend default options with overrides
        var opts = $.extend({}, defaultOptions, options);
    }

So by now you can set the options you need by writing something like this:

   $('#yourDomElement').yourPlugin({
      action:       myAction
    });

In this case you would have set opts.action from “false” to “myAction”.
Next we will go to private and public class methods. It is allmost the same as defining public and private member variables of your class.
Something like this would be private:

   /**
     * private
     * method to do some vodoo
     */
    function yourPrivateClassMethod()
    {
        // the methods code
    }

And something like this is a public method:

   /**
     * public
     * method to do some vodoo
     */
    $.fn.yourPlugin.yourPublicClassMethod = function()
    {
        // the methods code
    }

Same rules like for the public member variables,… they have to be declared after your constructor, otherwise you will get an error. Another word of advise,.. as a developer I thought to access variables and methods within a class I can go by “this”,.. forget “this”,.. private methods and vars are accessed directly by their name, the public one you can access either by $(this).yourPlugin.yourPublicClassMethod() or $.fn.yourPlugin.yourPublicClassMethod().

So by now, if we put together the things we learned, we can do something like this:

(function($){
   /**
     * default options for plugin
     * private
     * @var array defaultOptions
     */
    var defaultOptions = {
        action:       false,
        debug:        false
    }

    /**
     * yourPlugin base constructor
     *
     * @param [] options
     * @return void
     */
    $.fn.yourPlugin = function(options){
        // extend default options with overrides
        var opts = $.extend({}, defaultOptions, options);

        switch(opts.action)
        {
        	case 'private':
        		yourPrivateClassMethod();
        		break;

        	case 'public':
        		$.fn.yourPlugin.yourPublicClassMethod();
        		break;
        }
    }

    /**
     * public
     * method to do some vodoo
     */
    $.fn.yourPlugin.yourPublicClassMethod = function()
    {
    	// should alert 'false', 'false',
    	//because the public vars where not set

        alert($.fn.yourPlugin.defaultOptions.action);
        alert($.fn.yourPlugin.defaultOptions.debug);
    }

    /**
     * default options for plugin
     * public
     * @var array defaultOptions
     */
    $.fn.yourPlugin.defaultOptions = {
        action:       false,
        debug:        false
    }

    /**
     * private
     * method to do some vodoo
     */
    function yourPrivateClassMethod()
    {
        alert('This method is private');
    }

})(jQuery);

I hope this little summary helped a little in understanding how javascript classes and jQuery work.
If you have any suggestion or did see some errors in this tutorial please let me know about it.