Due to the fact that this is a working draft the tutorial may have got some errors. If you find one please inform us via the mailinglist.

My First Jamal Project

So you got this new web 2.0 application you developed? All your application code is ready and now it's time for some cool ajax features? But wait! Don't you remember the last time you tried to use ajax in your application? After a good start with a function here and there you ended up with some messy code that still today gives you nightmares. Don't wan't this to happen again? OK, read on and we show you how to get it done.

What's It All About?

The main problem with ajax applications today is that you start with a few functions and objects to get things done and end up with a code that you never wan't to maintain again. With this problem in mind we started jamal to do function and object organization for us so that we can focus on the real domain problems. Inspired by frameworks like rails, cake, symfony, etc we decided that a javascript mvc framework would be the best way to go. But have no fear. That's all for the theory for today. Now it's time to get our application running quick!

There Was This App Called Shoutr

Let's imagine we've got our cool new web 2.0 application shoutr. Everyone can shout some words out loud on your page and you want it to be refreshed via ajax. First we got to the jamal page and download the tutorial package from here. Then we copy the files in the scaffold directory to our javascript file folder in our web application. To see something happening we link the base javascript files to in our html files.

<script type="text/javascript" src="js/jquery.js"></script>
<script type="text/javascript" src="js/jamal_packed.js"></script>

If open your web page the next time Jamal is up and running. If you are a firefox user having firebug installed you should take a look to your console. Jamal will greet you with some messages telling that it's running.

But that's not much for the moment. I'm a fan of fast results that I can see ( red, green, refactor if you know what I mean). So let's create our first controller and let alerting something to the user. We make our way to the controllers folder in Jamal application and a file called shouts_controller.js which we fill with this content

$j.c({Shouts: {
        /**
         * Shouts index
         */
        index: function() {
                alert('Hello World');
        }
}
});

Jamal controllers are created by extending $j.c variable with a new class in json notation. You can name your controllers as you like but we recommend CamelCased? names for simplicity. Every controller needs methods that can be invoked to get your javascript logic running. It's always a good start to define an index method for your main operations. But we still have to link the files to our page. We'll add the following lines right after the last link tags.

<script type="text/javascript" src="js/app_controller.js"></script>
<script type="text/javascript" src="js/controllers/shouts_controller.js"></script>

Now that we've created our controller it's time for a first look at our application. Hit the refresh button and... wait! Notings happenings. These german jerks must've done something wrong! No stress! Jamal doesn't what controller and which action it has to start. We can tell it to Jamal via our class definition in the body tag. Yes, you did't something wrong. Jamal can use the class attribute of your body tag to be configured! To get back to the point just add this line to your class attribute in your body tag.

jamal {controller:'Shouts',action:'index'}

Hit the refresh button and a alert window will greet every user of the page. But that's just the beginning. We wan't see dynamic content on our page. To manipulate the dom we use views in Jamal. To create a view for our application we create a file called shouts.js in the views folder and open it. Similar to the controllers we extend a variable with our new view class. But this it's $j.v

$j.v({ Shouts: {
        replaceContent: function(title, body){
                $('div#container').fadeOut("slow", function () {
                        $('h2#title').html(title);
                        $('p#body').html(body);
                }).fadeIn("slow");
        }
}
});

Views are the heart of our DOM manipulation and can be filled with the methods you need to get your content render to the page. We wan't to replace a shout's title and body by fading them out replacing the content and fading them in again to have a cool web 2.0 feeling. We can use the jQuery methods fadeOut() and fadeIn() for processing the fading and the html() for replacing the content of title and body. After getting this done we have to tell our action to use our new created view to do the rendering. We replace the content of our index action by this.

$j.v.Shouts.replaceContent('Dennis', 'Yay, what a cool website!');

You can access your views via the $j.v variable followed by the name of your application and the method you wan't to call. Don't forget to link the view files in our page.

<script type="text/javascript" src="js/app_view.js"></script>
<script type="text/javascript" src="js/views/shouts.js"></script>

Hit refreshed! I promise it's gonna be great. Let's see now we've got the controller running and it's calling our view to render the content to our page via our view. What's next? Right, the model. We need to get some data from anywhere to provide our page with dynamic content. If you are a JSON fan Jamal has got a cool feature for you. Every model comes with a function to make AJAX request and retrieve JSON data. With that in mind we can use a very short way to get an ajax request done for getting our data and passing it to the view. Just take a look in at this first.

$j.current.m.json('/path/to/my/json/resource', function(response) {
        $j.v.Shouts.replaceContent(response[0].user.name, response[0].text);
});

As you might have noticed you just need to provide an uri to a JSON file to get your data for processing. We could provide a callback for the data procession but the function () {} expression will do for now. If you wan't to see a quick result we provided you with a JSON file with a lot of shouts. After providing the json() method with the right uri to your JSON file go back to your page and hit the refrsh button again. You can now see the first shout in our JSON file. To get a random shout you could change your controller code to something like this.

array_index = (Math.floor ( Math.random ( ) * 10 + 1 )) - 1;
json_path = 'public_timeline.json';

$j.current.m.json(json_path, function(data) {
        $j.v.Shouts.replaceContent(data[array_index].user.name, data[array_index].text);
});

Now you get a different every time you refresh your page (ok, not every time but most of the time). But that's a bit tedious. We can use the timers exentions for jQuery to reload the content for us. You can get it here. Link it to your page right under the jQuery link tag

<script type="text/javascript" src="js/jquery.timers.js"></script>

and then change your controller code to this.

$('div#container').everyTime(5000,function(i) {
        array_index = (Math.floor ( Math.random ( ) * 10 + 1 )) - 1;
        json_path = 'public_timeline.json';

        $j.current.m.json(json_path, function(data) {
                $j.v.Shouts.replaceContent(data[array_index].user.name, data[array_index].text);
        });
});

After another refresh you will notice that we've done our job. The page is refreshing every 5 seconds providing us with a newest shouts. You can now change the JSON file uri to your own resource. But i think don't help for that from now on.

Conclusion

You've seen that with the Jamal MVC creating AJAX applications is no longer a long queue of methods calling each other every time. Now you've a clean seperation of your DOM Manipulation and your AJAX request linked together at one central place.