Turbulences Tutorial - Chapter 1: Creating an Hello world module

Be sure to have installed a copy of Turbulences first.

Modules

All your application-specific code shall stay in myapp/modules; a module being a separate logic data/role entity. A module is typically made of three blocks:

• a controller which will define actions and behaviour of your module
• a model which represents (stores and validation) your data
• a view which will define specific views of your module

This is the classic MVC design pattern. This pattern allows separation of concerns and is widely used in both web and desktop modern frameworks. Please see the Wikipedia page or this excellent ADC introduction if you would like more information about this pattern.

Using modules allow wrinting stand-alone and hopefully reusable software components. Several modules are provided with Turbulences. Please see the Builtin Modules? page to learn more about them and how to use them.

How to create a module

Manually

A module generator tool exists and we recomend you to use it, as it completely automatises this task. Its use is described in the next section. These instructions are given to dispell any mistery about the inner structure and you need not follow them for each of your modules. However, if you would like to fully understand what the module generator does, read this section.

• create a hello module in myapp/modules

  $ cd myapp/modules
  $ mkdir hello
  

• create this hierarchy in your hello module:

  myapp/modules/hello
    + HelloController.php  // hosts class HelloController extends TURB_Controller {}
    + HelloView.php       // hosts class HelloView extends TURB_View_Smarty {}
    + Hello.php        // hosts class Hello extends TURB_Object {}
    + views
        + html      // hosts Smarty HTML templates
        + script    // hosts view specific javascript code
        + style     // hosts view specific css code
  

Using the generate tool

Just run

script/generate_module hello

This will create the above hierarchy and all the files that are required, boilerplating (filling with standard class definition code and the like) everything.

Create the model

We will now create each of the components of the MVC pattern, starting with the model.

• define an empty model (for now; modules/hello/Hello.php) as:

  class Hello extends TURB_Object
  {
  }
  

Create the controller

• define the controler (modules/hello/HelloController.php) as:

  // HelloController.php
  class HelloController extends TURB_Controller
  {
      // must be declared; called after the constructor 
      public function setup() {}
  
      public function action_default()
      {
          $name = 'world';
          $view = new HelloView();
          $view->assign('firstname', 'Walt');
          return $view->html_hello($name);
      }
  }
  

Create the view

• define the view (modules/hello/HelloView.php) as:

  // HelloView.php
  class HelloView extends TURB_View_Smarty
  {
      public function _hello($arg)
      {
          $this->assign('name', $arg);
      }
  }
  

Create the template

The template is the document that will be rendered to HTML or some other output. It is closely linked to the view.

• define the template (modules/hello/views/html/hello.tpl) as:

  <p>Hello {$firstname} {$name}</p>
  

Calling $view->html_hello($name); will check and call a method _hello in HelloView, in a HTML return context (we'll come to that in details later) ; this method will fetch automatically the modules/hello/views/html/hello.tpl template to render it.

Test your Hello module

Now, go to http://your_virtual_host/hello/ - that would render this new page. The execution path is the following:

index.php	runs the dispatcher, instanciate the controller of the hello module
HelloController.php	runs action_default()that instanciates a HellowView, assign some vars to it and calls html_hello()
HellowView.php	runs html_hello() that fetches the html/hello.tpl template and returns it
	finally the dispatcher renders the view it collects and returns it to the client browser

---

Some notes

• we are using the Smarty templating engine; relevant documentation is available at http://smarty.php.net/manual/
• if you would like to render in another format (say, XML), you would call $view->xml_hello($name); that would in turn render views/xml/hello.tpl. You may as well alter the rendered file name with $view->assign_template('other.tpl');.
• you may notice we did two assignments to the view object: one in action_default() and an other one in _hello(); you can do both, but we recommand you do these in the action_*() method; here's why: you may avoid defining the _hello() method, actually, the view rendering engine will know how to bypass it and automatically fetch the right template (views/html/hello.tpl here) and correctly assign the parameters; all that is needed for now is the HelloView class to be declared.

---