Quick links: Content - sections - sub sections
EN FR
The page corresponding to the latest stable release can be seen in the Jelix 1.8 Manual

Controller objects run actions corresponding to client-input. An action corresponds to a unique URL of your application.

Actions are methods of the controller that prepare a response.

Each controller is dedicated to one client-request type.

Naming conventions

File-system

Controllers are sorted per-module on the file-system, in the controllers directory. Each should have a unique prefix and suffix :

controllerName.clientRequestType.php

For example, the foo controller usable on classic client-requests :

foo.classic.php

Class name

All controller class name should use suffix Ctrl.

For example, the foo controller class name should be :

fooCtrl

Creating a controller

Each module could define a default controller, which then should be named "default".

For example, the first controller that you might want to create, named "default": exampleModule/controllers/default.classic.php. The name of the class is then defaultCtrl. Here is the class:


class defaultCtrl extends jController {

}

Each controller class should inherit from jController. Then you add a method for each action you want to implement. Methods for actions should be public, without arguments, and should return an object which inherits from jResponse, so a "response" in Jelix. Example:


class defaultCtrl extends jController {

    public function index(){
        $resp = $this->getResponse('html');
        $resp->addContent('<p>Hello world</p>');
        return $resp;
    }
}

The method named "index" in a controller is always considered as the default action of the controller.

When Jelix cannot determine the action and/or the controller from the URL, it tries to execute the method index() of the "default" controller. So it is recommended to have a "default" controller in a module, and an index() method in each controller.

Redefining the class constructor

To redefine the class constructor, you should call the parent constructor (so the constructor of jController), by giving the received argument, which is a jRequest object. Example:


class defaultCtrl extends jController {
    function __construct($request) {
        //...
        parent::__construct($request);
        //...
    }
}

Services provided by jController

jController provides methods for your actions.

Fetch a jResponse object

Actions should always return jResponse objects which implements the "View" of the MVC pattern. Jelix supplies several response objects, which allow to generate easily some HTML pages, XUL pages, JSON, text, XML, Zip, redirections etc, and you can make your own inheriting from jResponse.

Each response type is declared with a keyword. So, to retrieve a specific response object, you call the method getResponse() by indicating the keyword corresponding to the response type:


   $resp = $this->getResponse('html');

$resp is now an instance of jResponseHtml capable of generating HTML.

Notice that you can create your own response object. You can then support a new output format, or you can overload an existing response object to do some things shared between many actions. For example, you can create your own response HTML which generates dynamically a menu. Then, in all actions where you use this responses, you will have this menu. See the page which explains how to do this.

Accessing client-request parameters

HTTP client-request parameters are accessible through an instance of jRequest, which is accessible from jCoordinator. For example :


 $id = $GLOBALS['gJCoord']->request->getParam('id');

Although jController provides the method param() :


  $id = $this->param('id');

Fetching an undefined parameter makes param() to return null or it's second argument for example :


   $title = $this->param('title','Hello World (default title)');

jController provides a few filtering methods like intParam(), floatParam() or boolParam() which use the same arguments :

  • intParam() to fetch an integer,
  • floatParam() to fetch a float value,
  • boolParam() returns false except if the parameter's string value is "true", "1", "on", or "yes"

Use jFilter for any other type of filtering.