Controller
From Tlalokes
Contents |
Example
This is an example of a controller in Tlalokes
require 'TlalokesCoreController.php';
/**
* @ControllerDefinition( default='read_one' )
*/
class TestCtl extends TlalokesCoreController {
/**
* @ActionDefinition( file='read_one.tpl' )
*/
public function read_one ()
{
$this->response->title = "Read one";
}
/**
* @ActionDefinition( file='read_two.tpl', smarty, propel )
*/
public function read_two ()
{
$this->response->title = "Read two";
}
}
Anatomy of a controller
Include the TlalokesCoreController class, this class provides everything your controller needs to work with Tlalokes
require 'TlalokesCoreController.php';
Set the default action by calling the @ControllerDefinition annotation
/** * @ControllerDefinition( default='read_one' ) */
Write the your controller name ending its name with Ctl and extend the TlalokesCoreController class previously included
class TestCtl extends TlalokesCoreController {
Each method (or function) of the controller is considered as an action, to write an action set the @ActionDefinition annotation and define the view (template) associated with it. The template file must be located at the view directory in your application's structure, i't suggested to use the .tpl extension name.
/** * @ActionDefinition( file='read_one.tpl' ) */
Now write your action
public function readone ()
{
$this->response->title = "Read one";
}
Annotations
Annotation in Tlalokes are essentially to add meta-data to source code, specifically to define specifications to a class, method or property.
ControllerDefinition. In the controller is required to use annotations like @ControllerDefinition which allows you to define the default action of method to call once constructed the object
/**
* @ControllerDefinition( default='index' )
*/
class MyFirstCtl extends TlalokesCoreController {
in the previous code example, once the MyFirstClass controller has been constructed, it will call the index() method, if there isn't been called another method.
The annotation @ControllerDefinition also allows you to define is this controller is going to be available as a web service, in SOAP or JSON-RPC format.
/**
* @ControllerDefinition( default='index', soap, json )
*/
class MyFirstCtl extends TlalokesCoreController {
in the previous example, the controller's actions will be available in (X)HTML, SOAP and JSON-RPC, this allows you to avoid the writing of new classes that brings access to the same actions in the controller and promotes the writing of reusable code.
ActionDefinition. The actions or methods require its own annotations in order to define its relationship with views or (X)HTML templates.
/**
* @ActionDefinition( file='index.tpl' )
*/
public function index() {
in the previous example, is defined wich template file is related to the action, in that way the action index() will deliver its responses content to the view or template index.tpl.
The @ActionDefinition annotation allows you a simple and easy way to specify if you want to use Propel as your ORM toolkit and the template engine Smarty.
/**
* @ActionDefinition( file='index.tpl', smarty, propel )
*/
public function index() {
as you can see in the previous example, you can define is your action will use these tools or to avoid them is what we need more "manual" control, more speed or high availability.
Properties
The core controller (TlalokesCoreController) provides you of some objects to simplify the input and output of your data from an action.
TlalokesRequest
Tlalokes simplifies the access to inputs, it does it throw the TlalokesRequest object, it provides you access to the GET and POST HTTP "verbs". This object provides you access to your inputs but also executes some before actions like data type conversion and string cleaning (to avoid come kind of code injection) providing you of some certainty about the data content.
How to use it. You just need to use the property request to access your inputs. Example:
$local_id = $this->request->id;
TlalokesRequest predefined properties. According to the analysis of the URI and it management of REST, TlalokesRequest provides the following properties:
- Current controller. Provides the name of the current controller.
$this->request->_controller
- Current element Id. Provides the Id of the current resource.
$this->request->_id
- Current action. Provides the name of the current action.
$this->request->_action
REST
Beside simplifying the access to inputs, identify the data types and making some cleaning of strings, TlalokesRequest analyses the URI and extracts from it the name of the controller, the id of the resource, the action to execute and the additional variables. This is how TlalokesRequest provides, in a simple and cheap way, a Representational State Transfer (REST) and simulates the HTTP "verbs": POST, GET, PUT y DELETE y represents them as basic actions of a database, also known as CRUD (Create, Read, Update and Delete).
The syntax to handle this representations is as follows:
example.org/controller/id/action/additional_var_name/additional_var_value
If you access the URI example.org/controller/id throw GET TlalokesRequest will understand that the action is read. If you access the same URI throw POST it will understand that the action is update, however is we send throw POST the URI example.org/controller it will understand that the action is create and just for delete you must specify the action in the URI as example.org/controller/id/delete and send it throw GET. Simplifying it is:
POST -> example.org/controller = CREATE - Add a new element or resource GET -> example.org/controller = READ - Gets all the elements GET -> example.org/controller/Id = READ - Gets the element coincident to the Id POST -> example.org/controller/Id = UPDATE - Updates the element coincident to the Id GET -> example.org/controller/Id/delete = DELETE - Deletes the element coincident to the Id
If the Id coincides with the name of an action or an existent method in the controller, it will call that method
example.org/controller/action - Calls the action() method from ControllerCtl
this is important, so you must be careful about it, in order to your methods never coincides with some element or resource Id.
TlalokesResponse
Tlalokes simplifies the output of information throw this response object. Every property assigned to this object will be accessible from a simple PHP/HTML template or from the template engine Smarty, besides the same content of the object will be accesible throw SOAP and/or JSON-RPC, this allows you to reuse your controller code in different output formats.
To use it, you just need to assign a new property to the property response. Example:
$this->response->foo = 'bar';
Predefined properties of TlalokesResponse.
- Controller. Contains the name of the current controller.
$this->response->controller
- Action. Contains the name of the currect action.
$this->response->action
- URI. Contains the URI of your application.
$this->response->uri
- Imágenes. Contains the URI of your images directory.
$this->response->img
- CSS. Contains the URI of your CSS directory.
$this->response->css
- Javascript. Contains the URI of your Javascripts directory.
$this->response->js
