Controlador
From Tlalokes
Contents |
Ejemplo
Este es un ejemplo de un controlador
require 'TlalokesCoreController.php';
/**
* @ControllerDefinition( default='readone' )
*/
class TestCtl extends TlalokesCoreController {
/**
* @ActionDefinition( file='readone.tpl' )
*/
public function readone ()
{
$this->response->title = "Read one";
}
/**
* @ActionDefinition( file='readtwo.tpl', smarty, propel )
*/
public function readtwo ()
{
$this->response->title = "Read two";
}
}
Descripción general
A continuación una descripción general para escribir un controlador.
Primero incluimos la clase TlalokesCoreController, qué es el controlador base del framework
require 'TlalokesCoreController.php';
Se define la acción por defecto utilizando la anotación @ControllerDefinition
/** * @ControllerDefinition( default='readone' ) */
Se escribe el nombre del controlador finalizando el nombre con las letras Ctl (abreviatura de controllador) y se extiende la clase TlalokesCoreController que incluímos previamente
class TestCtl extends TlalokesCoreController {
Cada método del controlador es considerado una acción, para escribir una acción se define la plantilla a utilizar utilizando la propiedad file de la anotación @ActionDefinition, la plantilla deberá encontrarse ubicada en el directorio view de la aplicación, utilizando la extensión .tpl (abreviatura de template')
/** * @ActionDefinition( file='readone.tpl' ) */
Se escribe el método
public function readone ()
{
$this->response->title = "Read one";
}
Anotaciones
Las anotaciones sirven escencialmente para añadir metadatos al código fuente. En Tlalokes son utilizadas para definir especificaciones a una clase, método o propiedad.
@ControllerDefinition
En los controladores se require del uso de anotaciones por ejemplo, la anotación @ControllerDefinition permite definir cual será la acción o método a llamar una vez construido el objeto
/**
* @ControllerDefinition( default='index' )
*/
class MyFirstCtl extends TlalokesCoreController {
en el ejemplo anterior cuando el controlador MyFirstClass sea construido, ejecutará un llamado al método index(), si es que no ha sido solicitada otra acción ó método.
Además de establecer la acción ó método default, @ControllerDefinition también nos permite definir si deseamos que ese controlador esté disponible como un servicio web, ya sea en SOAP o en JSON-RPC
/**
* @ControllerDefinition( default='index', soap, json )
*/
class MyFirstCtl extends TlalokesCoreController {
con lo anterior las acciones del controlador estarán disponibles en (X)HTML, SOAP y JSON-RPC, esto permite reutilizar el controlador y nos evitará la escritura de nuevas clases que brinden acceso a los mismos métodos del controlador.
@ActionDefinition
Los métodos ó acciones también requiren anotaciones, especialmente para definir su relación con las vistas ó plantillas HTML.
/**
* @ActionDefinition( file='index.tpl' )
*/
public function index() {
en el ejemplo anterior definimos que archivo deberá relacionarse con el presente método o acción, así pues el método o acción index() entregará contenido a la vista o plantilla HTML index.tpl.
Además de permitirnos relacionar de manera sencilla una acción con una vista @ActionDefinition, proporciona una forma simple de especificar si deseamos utilizar el toolkit de mapeo objeto-relacional (ORM) Propel y/ó el motor de plantillas Smarty
/**
* @ActionDefinition( file='index.tpl', smarty, propel )
*/
public function index() {
como lo muestra el ejemplo podemos definir si esa acción utilizará las ya mencionadas herramientas, esto nos permite poder hacer uso de ellas de manera simple y acceder a todas sus funcionalidades, ó bien, evitarlas si lo que buscamos es mayor control manual y/o mayor velocidad.
En ocaciones reutilizamos la misma plantilla HTML y lo que deseamos es un Layout, para ello debemos definir un layout y las zonas donde deseamos aplicar bloques de contenidos.
/**
* @ActionDefinition( layout='auth_layout.tpl', zone='content:block_one&block_two;' )
*/
public function index() {
en el ejemplo anterior definimos que el archivo auth_layout.tpl será el Layout con el que se relacione el presente método o acción, así pues el método o acción index() entregará contenido a la vista o plantilla HTML auth_layout.tpl y las zonas y bloques que este contenga.
Propiedades disponibles
El controlador base de Tlalokes (TlalokesCoreController) hará disponibles algunos objetos para simplificar las entradas y salidas de datos, mismos que serán accesibles desde los métodos del controlador.
TlalokesRequest
Tlalokes procura simplificar el acceso a las entradas, y lo hace a través de este objeto que proporciona acceso a cualquier variable de entrada vía los dos verbos HTTP actualmente más implementados, es decir, GET y POST. Además al accesar las entradas mediante este objeto se obtiene una mejor certeza acerca del contenido, ya que el objeto realiza una identificación de tipos y una sanitización de las cadenas para evitar posibles ataques.
Forma de acceso. Basta con llamar la propiedad request para accesar al contenido de este objeto. Ejemplo:
$local_id = $this->request->id;
Propiedades predefinidas de TlalokesRequest. Basado en el análisis del URI y su manejo de REST, TlalokesRequest proporciona las siguientes propiedades predefinidas:
- Controlador. Proporciona el nombre del controlador en curso.
$this->request->_controller
- Identificador. Proporciona el valor del identificador del recurso.
$this->request->_id
- Acción. Proporciona el nombre de la acción interpretada y/o en curso.
$this->request->_action
REST
Además de simplificar el acceso a las entradas, identificar tipos de datos y sanitizar cadenas, TlalokesRequest analiza el URI y apartir de él, extrae el nombre del controlador, el id del recurso a tratar, la acción a ejecutar, y variable(s) adicional(es). Es así como proporciona de una manera sencilla y económica, un tipo de Transferencia de Estado Representacional ó REST (Representational State Transfer) y permite simular los métodos HTTP: POST, GET, PUT y DELETE y representarlos a manera de funciones básicas en bases de datos, es decir, representarlos en lo que conocemos como CRUD (Create, Read, Update y Delete).
La sintaxis en Tlalokes para manejar esta representabilidad esa la siguiente:
example.org/controller/id/action/additional_var_name/additional_var_value
Ahora bien, si accesaramos la URI example.org/controller/id mediante GET TlalokesRequest interpretará que la acción es read. si accesaramos la misma URI mediante POST interpretará que la accion es update, sin embargo si enviamos por POST la URI example.org/controller interpretará que se trata de un create y solo en el caso de delete debemos especificar la acción en un URI como example.org/controller/id/delete y enviarlo por GET. Simplificando sería:
POST -> example.org/controller = CREATE - Añade un nuevo elemento GET -> example.org/controller = READ - Obtiene todos los elementos GET -> example.org/controller/Id = READ - Obtiene el elemento coincidente al Id POST -> example.org/controller/Id = UPDATE - Actualiza el elemento coincidente al Id GET -> example.org/controller/Id/delete = DELETE - Elimina el elemento coincidente al Id
Si el identificador coincidiera con el nombre de un método existente en el controlador, se tomará como una llamada a ese método
example.org/controller/action - Ejecuta el método action() del controlador ControllerCtl
por lo que es importante que el nombre de un método del controlador nunca coincida con el identificador del recurso.
TlalokesResponse
Tlalokes simplifica la salida de la información mediante proporcionar este objeto de respuesta. Todo lo que se asigne a este objeto será accesible desde una plantilla simple de PHP y HTML ó bien mediante el uso del motor de plantillas Smarty, además el mismo contenido del objeto es representable vía SOAP y/o JSON-RPC lo que permite reutilizar el mismo controlador para diferentes tipos de salidas.
Forma de uso. Basta con asignar una nueva propiedad a la propiedad response para poner el contenido disponible. Ejemplo:
$this->response->foo = 'bar';
Propiedades predefinidas de TlalokesResponse. TlalokesResponse proporciona las siguientes propiedades predefinidas.
- Controller. Contiene el nombre el controlador en curso.
$this->response->controller
- Action. Contiene el nombre de la acción ó método en curso.
$this->response->action
- URI. Contiene el URI de la aplicación web.
$this->response->uri
- Imágenes. Contiene la ubicación del directorio de imágenes.
$this->response->img
- CSS. Contiene la ubicación del directorio de cascadas de estilo.
$this->response->css
- Javascript. Contiene la ubicación del directorio de Javascripts.
$this->response->js
