The Hello World

Goal

The goal of this tutorial is to learn how to define controllers in Lion. The application that we are going to develop just shows a 'Hello world' message.

Here is what we will accomplish in this tutorial:

• Create a controller to handle the user request (libs/controllers/HelloWorldController.class.php)
• Modify the app/config/controllers.xml file to declare the controller as active
• Create a template to show the string 'Hello world' (templates/helloWorld.tpl)

Defining the Controller

First, define which controller we're going to use in our application.

Naming convention: By default, when an __ActionController receives a request to execute an action, it tries to find a method with the name of the action followed by the suffix 'Action'. i.e., to execute the action 'fooBar', an __ActionController will try to execute the 'fooBarAction' method. If no action is specified, the controller will use the 'default' action, which then corresponds to the function "defaultAction'.

Since we just want a page to show the 'Hello world' message, we only need a single action to handle it.
So, let's start by defining a new action controller to execute that action:

<?php
 
/**
 * This is our action controller to handle the hello world action
 *
 */
class HelloWorldController extends __ActionController {
    
    /**
     * The default action. It just set the message 'Hello world'
     * in a __ModelAndView instance and returns it.
     * 
     */
    public function defaultAction()
    {
        //create a new __ModelAndView instance
        $model_and_view = new __ModelAndView();
        //Add the 'hello world' message to the __ModelAndView:
        $model_and_view->hello_world_message = 'Hello world';
        //returns the __ModelAndView
        return $model_and_view;
    }
       
}

In the class above we are defining our action controller by subclassing the __ActionController class (this is the most common and recommended practice in Lion).

This action controller will have at the same time one single method: defaultAction. This method is called by default when executing the HelloWorld controller.
This method just creates a __ModelAndView instance, assigns the 'Hello world' message and returns it. That's all.

Because class names are case insensitive in PHP, action codes will inherit this feature. i.e., the codes 'helloworld', 'HELLOWORLD' and 'HeLLoWorLd' are equivalents and correspond to the same controller: 'HelloWorldController'

Note that we are naming the controller class with the suffix 'Controller' due to the following mapping rule defined in the config/controllers.xml file:

<?xml version = "1.0" standalone="yes"?>
<configuration>
 
  <controller-definitions>
 
    <controller code="*" class="*Controller"/>
  
  </controller-definitions>
 
</configuration>

Now we have our action controller defined. Good job! :)

Placing the Controller

In Lion, the libs/controllers directory in your application is reserved to place the Controller files.

There is a mapping rule to let Lion know that any file in that directory with the suffix '.class.php' corresponds to a controller class with the same name without the suffix.
This mapping rule resides in the app/config/includepath.xml file:

<?xml version = "1.0" standalone="yes"?>
<classes>
 
  <!-- Components -->
  <cluster name="Components" path="/libs/components/...">
    <class name="*" file="*.class.php"/>
    <interface name="*" file="*.interface.php"/>
  </cluster>
 
  <!-- Event Handlers -->
  <cluster name="Event Handlers" path="/libs/eventhandlers/...">
    <class name="*" file="*.class.php"/>
    <interface name="*" file="*.interface.php"/>
  </cluster>
 
  <!-- Controllers -->
  <cluster name="Controllers" path="/libs/controllers/...">
    <class name="*" file="*.class.php"/>
    <interface name="*" file="*.interface.php"/>
  </cluster>
  
  <!-- Model classes -->
  <cluster name="Model" path="/libs/model/...">
    <class name="*" file="*.class.php"/>
    <interface name="*" file="*.interface.php"/>
  </cluster>
 
  <!-- Plugin classes -->
  <cluster name="Plugins" path="/libs/plugins/...">
    <class name="*" file="*.class.php"/>
    <interface name="*" file="*.interface.php"/>
  </cluster>
  
</classes>

Continuing with our example, since our controller class is HelloWorldController, let's name the file as HelloWorldController.class.php and place it into the libs/controllers directory.

Defining the View

Now it's time to define how the information will be shown to the user, it is, define the View (This is my favorite part :)

First, we need to understand how Lion resolves which View to use and how it sets up that View:
The __ModelAndView class is the one designed to provide all the necessary information to let Lion knows which View technology to use to render the user interface as well as which model data and which other information like the template to use in that process.
Lion just needs to retrieve a 'view code' from the __ModelAndView in order to create and setup a View. By default, if there is no information in the __ModelAndView regarding the view code, the one used for the 'action' will be the one used for the view: helloWorld.
Where is this behavior defined? In the app/config/views.xml file where you can edit the configuration section's view-definitions:

<?xml version = "1.0" standalone="yes"?>
 
<configuration>
 
  <view-definitions>
  
    <view code="*" class="__SmartyView">
      <property name="template" value="*.tpl"/>
      <property name="eventHandlerClass" value="*EventHandler"/> 
    </view>
  
  </view-definitions>
  
</configuration>

<html>
<head>
  <title>The hello world in Lion</title> 
</head>
<body>
  <h1>{$hello_world_message}</h1>
</body>
</html>

This template has a placeholder in Smarty format: {$hello_world_message}.
Because we have to assign a variable to the model with the same name as the placeholder, the View will try to fill this with the value already stored in the model. Which, in our example, is string 'Hello world'.

Sorry, there aren't any more steps to do, your application is ready to be launched :)

Executing the Hello World

Now it's time to execute our application, and for that purpose, we need to know how to build the appropriate URL to execute the action we want.

The default mapping rule for URLs in Lion is <controller>.<action>.html

i.e. if we want to execute the controller foo and a default action, the url should be foo.html.

By making use of Lion's route scheme, just use the following url: http://yourdomain/helloWorld.html

Lion will deduce that the action controller that you are requesting is the one with code 'helloWorld'.

Our application should be similar to the following one:

And yes: we know that it's not a Picasso, but for the goal of this tutorial is enough :)

The next tutorial shows how to declare model services and how to consume them from action controllers:
The Advanced Hello World