Become A CoccyxJS MVC Ninja – Mini Tutorial #1: Controller

coccyxjs_ninjaWelcome to the first in a series of CoccyxJS mini tutorials and today we are going to learn how easy it is to add routing to our Web applications using the CoccyxJS Controller component. But before we get on with today’s mini tutorial please read the instructions in my article, “A Series jOf CoccyxJS Mini Tutorials”, which has instructions for setting up a project directory structure that we will use throughout the series as well as instructions for installing http-server, which we will use to run our mini applications.

Routing Request

Controllers manage your applications’ views, models and collections. They are also responsible for handle routing request, which is what we will focus on here today. Routing request can result whenever the URL in the browser’s address bar changes by clicking the browser’s forward and back navigation buttons or when a user clicks on an anchor tag or submits a form.

When a routing requests is made the CoccyxJS router will attempt to match the request to a route handler defined by a Controller in it routes hash. If found then the router will call the route’s handler function. If not found the router will ignore it.

Since CoccyxJS implements RESTFUL routing we always have to define our routes as “verb url”: handler, where verb can be one of “get”, “post”, “put” and “delete” and the url is the actual URL associated with the route. The verb plus the url together serve to uniquely identify the resource, which in the case of routing is the route handler function that will be called.

The most important thing to know at this point though is that CoccyxJS ignores all routing request until it is explicitly told to begin handling them. For that we need to call its History component’s start method which is used to register one or more Controllers and to begin processing routing requests.

I am sure that all this must sound a lot more complicated than it really is so instead of talking about it, lets implement it and we’ll see how CoccyxJS makes all this really easy.

tutorial01.js

In your project’s root folder, specifically its javascripts folder, create a file named tutrotial01.js if it doesn’t already exist. In tutorial01.js paste the following code and save the file. We’ll discuss the code in a moment but it is so much better to see it played out first:

/**
 * CoccyxJS mini tutorial 01.
 * Creating our first Controller and route handler.
 * The route we want thato handle is 'get /' and the
 * route handler that will be called will simply
 * alert 'Hello World!'.
 */

(function(v){

    'use strict';

    //Implement a route handler for 'get /'
    function showIndexPage(){
        //Alert "Hellow World!" just so we know
        //our routing request was actually handled.
        alert('Hello World!');
    }

    //A simple controller that declares one route.
    //The route it will handle is 'get /'.
    //The function it will call is showIndexPage.
    var controller = {
        name: '',
        routes: {
            'get /': showIndexPage
        }
    };

    //Register the controller &
    //begin handling routing requests.
    v.history.start(true, [controller]);

}(window.Coccyx));

Now, if you are on a Mac open up the terminal and make the project folder the current directory. Once you’ve done that we will start our server. Type http-server and hit enter. You should see the following:

Terminal

Now open your browser and navigate to http://localhost:8080 and you should see the following in response:

running_tutorial01

What Just Happened?

Ok so lets break this down:

  • First we created a function named showIndexPage which when called simply alerts “Hello World!”.
  • Next we created a Controller and its routes hash with one route definition defined to handle a request of “get /” by calling the showIndexPage function. We also gave the Controller a name by assigning it a property called… you guessed it… name and assigned it a value of “”. Since name is an empty string the router interpreted our route definition’s URL to just “domain/”. Had we given it a real name, say “invoices” for instances, then the router would have interpreted our route definition’s URL as domain/invoices. We will cover route definitions in more detail in a later mini tutorial but for now it is important just to realize that every Controller defines the routes it wants to handle and a name.
  • Lastly we called history.start(true, [controller]) to register our Controller and to begin processing route requests. By passing true as the first argument, we are instructing the router to not only begin processing routing requests, but to also route the browser’s current address. In response, after having registered our Controller, the router found a matching route definition (which it does because our Controller defined one) and called its handler, which is the showIndexPage function that we defined which displayed an alert of “Hello World!”.

Now wasn’t that ezpz? Give yourself a pat on the back because you are well on the way to becoming a CoccyxJS Ninja.

What’s Next

In the next mini tutorial we will learn about Views and we will expand upon tutorial01.js by adding a View to the route handler function. See you soon.

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s