ATK Howto: Using the atkFrontController

Complexity: Intermediate
Author: Peter C. Verhage <peter@achievo.org>

Preface

The atkFrontController can be used to implement the MVC pattern in your web application. It's part of ATK and can be used stand-alone for ATK applications but can also be easily integrated in WDE using the atkFrontController plug-in. If you use a recent version of ATK or WDE the atkFrontController is out-of-the-box available without any special installation or configuration needed. The atkFrontController has been heavily inspired by Ruby on Rails.

This how-to will give a short introduction on usage of the atkFrontController in stand-alone mode. It will soon be extended to add information about usage in WDE, usage of Ajax and some new features that will be coming soon.

Basic usage

First you need to checkout ATK or download the latest ATK nightly in a directory that's browseable by your webserver. Copy atk.inc and the example config.inc.php from the atk/skel directory to the root directory of your application. Create a directory atktmp and make it writeable to your webserver. Create a file named index.php with the following contents:

 <?php
 $config_atkroot = "./";
 require_once($config_atkroot."atk.inc");
 atkimport('atk.front.atkfrontcontroller');
 $request = $_REQUEST;  
 $output = atkinstance('atk.ui.atkoutput');  
 $content = atkFrontController::dispatchRequest($request);
 $output->output($content);
 $output->outputFlush();

Create a directory modules and inside this directory create a directory called example, this will be the ATK module we will be working from. Inside the module directory you need to create a directory called controllers. Inside this directory you can place your controller files. A controller file should be named class.<name>controller.inc where <name> can be replaced by your custom name. Inside the controller file you should create a class which follows the same naming scheme and extends the atkFrontController class. E.g.

 class HelloController extends atkFrontController
 {
 }

The example controller above should be placed in a file named class.hellocontroller.inc.

After you've created the controller class you can start adding actions. An action is a method that uses the following naming scheme <name>Action and is declared public. Inside an action you can assign template variables as if they were instance variables of your controller you can also choose to use your controller as if it were an array and assign template variables that way. E.g.

 class HelloController extends atkFrontController
 {
   public function helloAction()
   {
     // assign a template variable (method 1)
     $this->title = "Hello!";
     
     // assign another template variable (method 2)
     $this['name] = $this->request->name;
   }
 }

In the example above you can also see that request variables can be accessed by the /$this->request/ object. In the same manner you can store/retrieve information to/from the session using the /$this->session/ object.

Now that we've assigned some template variables let's look at how we can access them in our template. First we need to create a template for our action. Templates are stored in the templates directory of the controller's module. They are stored using the naming scheme <module>/<controller>/<action>.tpl. So this means that for our hello action we need to create a template called hello.tpl in the directory templates/example/hello of our module. Our template might look like the following:

 <h1>{$title}</h1>
 Hello {$name}!

As you can see you can simply use the template variables by name. You can also choose to store your template in a templates directory in the root of your ATK application or in the skel/templates directory inside your module directory. ATK will first try to find the template in the application root templates directory, then in your module's templates directory and finally in the module's skel/templates directory

Because we are using the atkFrontController in stand-alone mode we should also create a layout. The layout is given the result of the action and all of the action template variables. The result of the action is made available through the special template variable /$content_for_layout/. Our layout file might look like the following:

 <html>
 <head>
 <title>{if $title}{$title}{else}Hello{/if}</title>
 </head>
 <body>
   {$content_for_layout}
 </body>
 </html>

A layout is first searched for in the application root's layouts directory, then in the module's layouts directory and finally in the module's skel/layouts directory using a naming scheme of <module>/<controller>.tpl. If no layout is found the exact same directories are searched for a template using the naming scheme <module>/root.tpl. Finally if still no layout template has been found the exact same directories are searched for a template called root.tpl.

Now that we've created our controller with custom action let's browse to it to check if everything works as expected. You should browse to the earlier created index.php and add a parameter uri with the value <module>/<controller>/<action> and another parameter name with your name, so for example http://localhost/?uri=example/hello/hello/&name=Peter.

If everything works as expected you will end up with a page that says Hello Peter! (although it might say something different if your name isn't Peter...).

Spicing things up

To be continued...