main documentation

Modules

Tutorial > first steps with the module

1 2 3

Open a terminal window.

cd to the alahup folder.

iMac-G4:~/Sites/alahup dom$ ./engine/tools/generate_module.php Available sites : a) alahup b) basic c) companieros d) lachose e) modulemadness f) transitcity e Module name : livecomments Default controller [default: main] :

A folder structure and a couple of files have been created in alahup/modules:

Let's go back to our mod.tpl file and change the "Mighty LiveComments list module !" string to:

elements/sets/default/mod.tpl :

{module id="livecomments"}

{module} is a alahup! Smarty function. It will insert our "livecomments" module.

Refresh the draft site.

As you can see, some templates have been pre-filled to guide us.

But first, let's examine the main file : livecomments_module.php.

livecomments_module.php :

<?
class LiveCommentsModule extends Module
{
// Uses /controller/action/ instead of /?<controller_key>=controller&<action_key>=action otherwise.
// Requires the block it's running inside of to be sticky ! Ignored otherwise
public $keep_url_clean = false;
//public $controller_key = 'c';
//public $action_key = 'a';
// If no controller is provided (from a link, from the url, or from a redirect), the default controller will be used.
public $default_controller = 'main';

// _init() is called when the module is loaded. It can be used for customization purposes.
function _init()
{
}
}
?>

This file defines the module's general behavior.

It namely says that 'main' is the default controller.

Let's open it: open controllers/main_controller.php.

controllers/main_controller.php. :

<?
class MainController_LiveCommentsModule extends Controller_Module
{
// If no action is provided, the default action of the controller is used.
public $default_action = 'index';

// This special method is called when the controller is loaded. This is useful to instantiate required objects.
function _init()
{
}

function index()
{
}
}
?>

The controller is an interface between the user's actions in the web browser and the logic of the application.

Each function (one should rather say method) of this class defines an action.

The default one is "index".

Most actions have an associated view with the same name.

Since we are in the 'index' action of the 'main' controller, the corresponding view is found in views/main/index.tpl .

One of the roles of the controller is to pass datas to the view.

Let's try this:

In controllers/main, change:

function index()
{
}

function index()
{
$this->test = "hello, world !";
}

In views/main/index.tpl, erase the text and just type:

This is the variable "test" : {$test}

As you can see, just set a variable to some value with $this->avariable from a controller to make it available to the view.

Let's try something else.

In controllers/main_controller.php:

controllers/main_controller.php :

function _init()
{
// initialize 'count' in as a session variable if it doesn't exist yet
if ( !array_key_exists('count', $_SESSION) ) $_SESSION['count'] = 0;
}

function index()
{
$this->test = $_SESSION['count'];
}

function increment()
{
$_SESSION['count']++;
$this->flash['message'] = "Incremented !";
$this->redirect_to('index');
}

function decrement()
{
$_SESSION['count']--;
$this->flash['message'] = "Decremented !";
$this->redirect_to('index');
}

In views/main/index.tpl:

views/main/index.tpl :

This is the variable "test" : {$test}<br/>
<br/>
{link_to text="minus" class="st0">"decrement"} {link_to text="plus" class="st0">"increment"}

Now go the draft site and click on the increment or decrement link?

What have we done here?

We have defined two actions, "increment" and "decrement" in the controller.

Each action changes the value of the 'count' session variable, then redirects back to the "index" action.

A message is also saved in the special $this->flash array.

This variable is a temporary variable to pass data between actions.

Now how come this is displayed in our view?

Open the views/_layout/main.tpl file.

This file is the main layout template. It should at least contain {$content_for_layout}, in order to display the current view.

It is the perfect place to display elements that are common to all views.

{if $flash.message}
<div style="color: red;">{$flash.message}</div>
{/if}
{$content_for_layout}

By default the 'main' layout is used, but you can change this behavior from the controller by changing $this->layout .

Enough with the tests. Let's code our LiveComments module!