The online documentation is produced by a web publishing technology created by us to read the documents origins in OpenOffice Writer (ODT) and Microsoft Word (docx) formats and produces native web and PDF versions. In this way we maintain Louder project documentation update and in sync on each of its formats.
El componente View se encarga de administrar la forma estándar en la que se genera la presentación al usuario final en su explorador.
La presentación estándar en una aplicación en Kumbia Enterprise se basa en varios patrones de diseño que permiten reducir la codificación y hacer más mantenible esta parte del desarrollo.
El primer patrón utilizado es Template View el cuál habla de utilizar tags personalizados ó marcas embebidas en el contenido dinámico proporcionando flexibilidad y poder para crear interfaces web.
El segundo patrón es el Two State View el cual permite definir múltiples interfaces de acuerdo al dispositivo ó cliente desde el cuál se este se accediendo a la aplicación. Este tipo de implementación favorece principalmente aplicaciones que accedan desde un browser ó un dispositivo móvil como un telefono celular, en donde es necesario personalizar detalles para cada tipo de interfaz.
La arquitectura MVC presenta el concepto de vista la cuál actúa como puente entre el usuario final y la lógica de dominio en los controladores.
Jerarquía de vistas en la presentación
Una jerarquía de archivos con vistas imbebibles soportadas por el componente View permite reducir la codificación creando puntos de presentación comunes para la aplicación, controladores ó mediante la implementación de plantillas.
Cada parte de la presentación se crea en un archivo ubicado en una estructura convenida de directorios en el directorio de la aplicación llamado views/.
El componente View permite definir la presentación en varios niveles, cada uno contiene al siguiente:
Tabla: Niveles de presentación en el componente View
Archivo ó Ubicación
Descripción
index.phtml
Contiene la vista principal y encabezado XHTML de todas las vistas.
directorio-con-nombre-del-controlador
Permite establecer archivos con vistas para cada acción del controlador.
Por defecto se utiliza un encabezado XHTML 1.0 Strict el cuál propende por aplicaciones basadas en estándares y que funcionan mejor en los navegadores más avanzados del mercado.
Los helpers Core::stylesheetLinkTags() y Core::javascriptBase() incluyen archivos JavaScript como frameworks y utilidades además de los CSS incrustados en otras vistas activas.
Notese el llamado a View::getContent(), este imprime todo el contenido generado en el layout ó vistas activas en la aplicación en el lugar que se indique.
Requerimientos de la Vista Principal
Es recomendable no eliminar los llamados a los helpers estándar en la vista principal ya que esto puede impactar el comportamiento del framework. En general los requerimientos del contenido de la vista principal son los siguientes:
Su nombre debe ser index.phtml y mantenerse en la raíz de views/
Incluir los archivos JavaScript que se utilicen en cada petición a la aplicación
Incluir los archivos CSS que se utilicen en cada petición a la aplicación
Incluir codigo XHTML que sea común a cada controlador y acción de la aplicación
Requerimientos Vistas a nivel de Controlador
Generalmente cada acción solicitada presenta ó solicita información diferente al usuario de tal forma que el flujo de la aplicación sea consistente tanto para el desarrollador como para los usuarios. Los requerimientos de las vistas a nivel de controlador son:
Es necesario que exista un directorio con el nombre del controlador donde se encuentre la acción
El nombre del directorio debe ir en minúsculas y sin el sufijo "Controller".
El archivo de la vista debe tener la extensión .phtml y el nombre debe ser el nombre de la acción sin el sufijo "Action".
Requerimientos de Layouts de Controladores
Los layouts de controladores son vistas que contienen fragmentos comunes de presentación que son validos para cualquier acción del controlador. Los requerimientos de los layouts de controladores son:
Un archivo con el nombre del controlador en el directorio views/layouts debe existir.
El nombre del archivo debe ir en minúsculas y sin el sufijo "Controller".
El archivo debe tener extensión .phtml.
Requerimientos de Vistas Parciales en Controladores
En ocasiones fragmentos de presentación como menús, encabezados, pie de paginas, etc son comunes a varias acciones de un controlador pero no a todas, en estos casos se puede implementar vistas parciales. Los requerimientos de las vistas parciales en controladores son:
Es necesario que exista un directorio con el nombre del controlador donde se encuentre la vista parcial.
El nombre del directorio debe ir en minúsculas y sin el sufijo "Controller".
El archivo de la vista parcial debe tener la extensión .phtml y el prefijo "_" (underscore).
Requerimientos de Vistas Parciales Generales
Al igual que las vistas parciales de controladores las generales realizan la misma tarea con la diferencia que estan disponibles para cualquier layout, template ó vista de la aplicación.
Los requerimientos de las vistas parciales generales son:
La vista parcial debe estar ubicada en el directorio views/partials.
El archivo de la vista parcial debe tener la extensión .phtml y el prefijo "_" (underscore).
Requerimientos de Plantillas ó Templates
Las plantillas permiten establecer múltiples fragmentos de presentación y aplicarsen antes ó después del layout del controlador. Los requerimientos de las plantallas son:
Deben entas ubicados en el directorio views/layouts/.
La extensión del archivo debe ser ".phtml"
Inserción automática y manual de vistas
El componente View utiliza convenciones para insertar automáticamente la presentación correspondiente a un controlador ó una acción, otros componentes de presentación requiere que se establezca programacionalmente su relación con la presentación diseñada.
Si se realiza una petición a la aplicación mediante la URL:
En donde company es el nombre de la instancia del framework, press es el nombre de la aplicación y categories es el nombre del controlador. El nombre de la acción no se ha establecido por lo que se asume que es index.
Los archivos de presentación son los siguientes:
press/views/categories/index.phtml
press/views/layouts/categories.phtml
default/views/index.phtml
Implementar los tipos de vistas
En el siguiente ejemplo se ilustra los tipos de vistas y su integración en la presentación de una aplicación. El controlador customers se inicializa con 3 templates:
Ejemplo: Aplicar multiples templates a un mismo controlador
<?php
class CustomersController extends ApplicationController {
public function initialize(){
$this->setTemplateBefore("template1");
$this->setTemplateAfter(array("template2", "template3"));
}
public function createAction(){
}
public function updateAction(){
}
}
Los métodos del controlador setTemplate y setTemplateAfter permiten insertar plantillas antes y después del layout del controlador. Los templates como se mencionó deben estar ubicados en views/layouts.
El archivo de plantilla views/layouts/template1.phtml tiene:
El método View::renderPartial inserta una vista parcial que esta ubicada en el mismo directorio de controlador views/customers/. Notése que el prefijo "_" de las vistas parciales es omitido a propósito al establecer el nombre de esta.
La vista parcial views/customers/_header.phtml tiene:
<h4>Este es el encabezado</h4>
La vista parcial views/customers/_footer.phtml tiene:
<h4>Este es el pie de página</h4>
La vista de la acción create en el archivo views/customers/_create.phtml tiene:
El resultado obtenido en el explorador al invocar la acción create es:
El resultado obtenido al invocar la acción update en customers es:
Como se mostró todos los tipos de fragmentos de presentación proporcionan una poderosa forma de compartir el código y construir interfaces flexibles siguiendo un principio básico de mantenibilidad de una aplicación.
Transferir valores del controlador a la vista
Existen 2 formas de transferir datos del controlador a la presentación:
Transferir mediante atributos públicos
Si al procesar una acción en un controlador se requiere presentar información al cliente final esta debe ser transferida a las vistas asociadas para su posterior tratamiento. Por defecto los atributos públicos de los controladores son transferidos automáticamente a la presentación en forma de variables locales.
El siguiente controlador tiene 2 atributos públicos que se visualizan al invocar la acción info:
Ejemplo: Utilizar atributos públicos para transferir valores a la presentación
<?php
class PressController extends ApplicationController {
public $code;
public $name;
public function indexAction(){
}
public function infoAction(){
$this->code = 100;
$this->name = "Este es un nombre";
}
}
Todas las vistas asociadas a la petición tienen acceso a las variables locales $code y $name que pueden ser usadas a conveniencia:
El archivo views/layouts/press.phtml tiene:
<h1>El código es <?php echo $code ?></h1>
El archivo views/press/info.phtml tiene:
<p>El contenido de "name" es <?php echo $name ?></p>
Lo que en conjunto produce en el explorador:
Transferir mediante setParamToView
La segunda forma de transferir valores desde las acciones del controlador es mediante el uso del método setParamToView. Este método es especialmente útil cuando se requiera transferir grandes cantidades de datos a las vistas ó datos poco relevantes que no ameriten la definición de un atributo público en el controlador.
También si se usan controladores con el estado persistente activo es posible que también se quiera restringir la definición de atributos públicos a los estrictamente necesarios.
Ejemplo: Transferir datos a la presentación mediante setParamToView
<?php
class PressController extends ApplicationController {
public function indexAction(){
}
public function showAllAction(){
$this->setParamToView("editions", $this->Editions->find("status='A'"));
}
}
En la vista se crea una variable local llamada $editions con el valor asignado en la acción.
Controlar Niveles de Renderización
En determinadas situaciones es posible que se requiera controlar el nivel de profundidad de la visualización. El componente View permite establecer el nivel de renderización mediante el método setRenderLevel(int $level).
Esté método puede ser invocado desde el controlador ó desde una capa de visualización superior para evitar que otras sean presentadas.
Tabla: Niveles de renderización en View
Valor
Constante
Descripción
0
LEVEL_NO_RENDER
Indica que se debe evitar generar cualquier tipo de presentación.
1
LEVEL_ACTION_VIEW
Genera la presentación hasta la vista asociada a la acción.
2
LEVEL_BEFORE_TEMPLATE
Genera la presentación hasta las plantillas antes de el layout del controlador.
3
LEVEL_LAYOUT
Genera la presentación hasta el layout del controlador.
4
LEVEL_AFTER_TEMPLATE
Genera la presentación hasta las plantillas después de el layout del controlador.
5
LEVEL_MAIN_VIEW
Genera la presentación hasta la vista principal. Archivo views/index.phtml
Utilizar modelos en la presentación
Los modelos de la aplicación siempre están disponibles en la presentación. Si la opción de autoinicialización de modelos está activa se creará una referencia de todos los modelos de la aplicación como variables globales con el nombre del modelo, si no está activa solo los modelos utilizados en la petición actual serán llevados a la presentación.
Dependiendo del caso se puede usar en forma natural dentro de cualquier tipo de vista los modelos de esta forma:
Ejemplo: Utilizar modelos en la presentación cuando son auto-inicializados
//Listar las ordenes de compra
foreach($Orders->find() as $order){
echo $order->getRecordedDate();
}
Si los modelos no son auto-inicializados se puede obtener una instancia de ellos usando el método de EntityManager llamado getEntityInstance:
Ejemplo: Usar modelos en la presentación cuando no son auto-inicializados
$orders = EntityManager::getEntityInstance('Orders');
foreach($Orders->find() as $order){
echo $order->getRecordedDate();
}
Plugins de View
Los Plugins de presentación permiten extender la funcionalidad del componente View. La arquitectura de plugins de View permite observar, extender y manipular el comportamiento de las vistas de la aplicación según las condiciones lo exijan.
Los plugins permiten interceptar eventos en las vistas de tal forma que estos sean observables y además ejecutárse uno tras otro de manera centralizada sin requerir refactorización ó reintegración en la aplicación.
Crear un Plugin de View
Los plugins de View son clases que implementan eventos que son invocados a medida que avanza la ejecución del proceso de presentación en cualquier petición. Estas clases deben cumplir con los siguientes requerimientos:
Deben estar ubicados en el directorio de plugins usualmente apps/app-name/plugins
El nombre del archivo que implementa la clase debe ser el nombre del plugin
El nombre de la clase debe tener la extensión Plugin
Los plugins de controlador deben heredar de la clase ViewPlugin ó ser subclase de ella
Las clases pueden implementar métodos públicos que referencian los eventos ocurridos en los controladores, la lista de ellos es la siguiente:
Tabla: Eventos que se pueden implementar en plugins de View
Nombre Evento
Descripción
beforeRender
Ocurre antes de empezar el proceso de visualización de las vistas asociadas a la petición. El evento recibe la instancia de ControllerResponse actual
afterRender
Ocurre después de terminar el proceso de visualización de las vistas asociadas a la presentación.
API del Componente View
Jerarquia de renderización
static function string getContent(boolean $returnContent=false) El llamado a este método le indica al componente View donde debe insertar el siguiente nivel de la jerarquía de renderización. Si se pasa true en $returnContent devuelve el contenido del buffer de salida hasta el momento.
static function void setRenderLevel(int $level) Establece hasta que nivel de renderización se debe generar la presentación. Consulte la tabla de niveles de presentación para obtener más información sobre el uso de este método.
Administrar presentación
static function void handleViewRender(Controller $controller) Este método actua como el administrador de presentación predeterminado recibiendo como parámetro el último controlador enrutado. No debería ser invocado directamente por el desarrollador ya que es llamado por el contenedor de aplicaciones.
static function void handleViewExceptions(Exception $e, Controller $controller) Este método actua como el administrador de presentación predeterminado cuando no se captura una excepción recibiendo como parámetro el último controlador enrutado. No debería ser invocado directamente por el desarrollador ya que es llamado por el contenedor de aplicaciones cuando esta situación ocurre.
Visualizar vistas programacionalmente
static function void renderPartial(string $_partialView, string $_partialValue='') Permite visualizar una vista parcial dentro de otra vista. El segundo parámetro permite transferir un valor desde la vista donde se invoca este método al interior de la vista parcial. La vista parcial es ubicada en el directorio de vistas del controlador actual.
static function void renderView(string $_view) Permite visualizar una vista de acción dentro de otra vista. La vista de acción es ubicada en el directorio de vistas del controlador actual.
El método se utiliza de la siguiente forma:
<?php View::renderView("nombreVista") ?>
Si se requiere visualizar una vista parcial en otro controlador diferente al actual debe usarse:
static function array getValidationMessages() Obtiene desde una vista los mensajes de validación producidos por el componente Validation ó otro componente de usuario.
static function void setContent(string $content) Establece programacionalmente el contenido del buffer de salida actual de la presentación.
static function void setViewParam(string $index, string $value) Establece una variable de la vista que será creada en un ambito local como $index con el valor $value.
static function array getViewParams() Obtiene un array con las variables pasadas a la vista usando View::setViewParam.
static function void setProxyProvider(string $proxy, array $options) Establece un proxy-provider que administre las peticiones de presentación usando componentes de terceros.
static function void proxyHandler() Método predeterminado para la administración de presentación cuando se usan componentes de terceros
static function boolean existsActionView(string $name, string $controllerName='') Permite consultar si una vista de acción existe en el controlador actual ó en el definido en $controllerName.
Crear un componente de Presentación personalizado
El desarrollador puede crear componentes de aplicación que reemplacen al componente de presentación View por defecto en Kumbia Enterprise. Como los demás componentes de usuario estos deben estar ubicados en el directorio library de la aplicación ó donde la variable de configuración libraryDir indique.
Los controladores deben establecer el administrador de presentación requerido sobrescribiendo el método getViewHandler de esta forma:
Ejemplo: Cambiar el componente que administra la generación de la presentación
<?php
class CustomersController extends ApplicationController {
public function getViewHandler(){
return array("MyView", "handleViewRender");
}
}
De esta forma cuando se requiera mostrar la presentación para el controlador se pasará el control a el componente MyView invocando el método estático handleViewRender. Este método recibe el objeto del controlador instanciado (ó el último que se utilizó después de realizar enrutamientos) en la petición:
Ejemplo: Definir un componente de usuario que administer la presentación
<?php
class MyView {
static public function handleViewRender($controller){
//Realizar la presentación
}
}
Se debe tener en cuenta toda la funcionalidad mencionada en el componente View no estará disponible si se reescribe el componente de presentación. Los servicios de los componentes Core (CoreConfig, CoreLocale, etc), Router y Dispatcher pueden resultar útiles en este punto.
Crear un componente de presentación de Excepciones no capturadas
Al igual que la presentación normal, la de excepciones también puede ser reescrita siguiendo un procedimiento parecido al del anterior. En este caso el método getViewExceptionHandler debe ser reescrito en el controlador.
EJemplo: Definir un componente de usuario que adminisre la presentación de excepciones no capturadas
<?php
class CustomersController extends ApplicationController {
public function getViewExceptionHandler(){
return array("MyView", "handleViewExceptionRender");
}
}
El método recibe la excepción y el último controlador activo antes de que se generará. El componente MyView sería:
Ejemplo: Definir un componente de usuario que administre la presentación de excepciones no capturadas
<?php
class MyView {
static public function handleViewRender($controller){
//Realizar la presentación normal
}
static public function handleViewExceptions($e, $controller){
//Excepciones
}
}
Consulte la referencia de CoreException y Exception para obtener más información sobre las excepciones generadas que no han sido capturadas.
Integrar otros Engines de presentación
Si el desarrollador requiere, es posible integrar componentes de generación de presentación de terceros (otros frameworks ó proyectos). Con esto se aprovecha la funcionalidad de estos componentes sin perder el comportamiento y potencia del componente de Kumbia Enterprise View.
Comportamiento de la integración
La integración con los componentes de terceros tiene el siguiente comportamiento:
Las variables públicas del controlador, datos pasados mediante setViewParam y modelos utilizados en la petición (ó todos si la autoinicialización de entidades está activa) son creados en el formato adecuado del componente utilizado. Por ejemplo en Zend_View se debe usar $this para acceder a estos valores.
Los nombres de la extensiones de archivos de vistas pueden configurarse como se requiera y no se debe usar ".phtml" como es normal.
La jerarquia de inclusión "vista principal/templates/layouts/vista/partials" se mantiene sin cambio alguno con la única diferencia que el resultado de cada vista es producido por el componente seleccionado.
Todo el framework aplicable puede utilizarse en las vistas creadas con otros engines sin restricciones.
Los plugins de View funcionan normalmente
Componentes Soportados
Actualmente hay soporte para los componentes de presentación Zend_View de Zend Framework y Smarty.
Proxy a Zend_View
El componente de Zend Framework llamado Zend_View ofrece la posibilidad de integrar helpers, filtros y scripts a las vistas generadas con este. Para indicar que se usará este componente se debe cambiar el administrador de presentación en el controlador así:
Ejemplo: Establecer un proxy al componente de presentación Zend_View
El método View::setProxyProvider establece que se usará el Proxy a componentes terceros 'Zend'. El segundo parámetro permite indicar otras opciones opcionales de la integración.
Tabla: Parámetros del ProxyProvider a Zend_View
Opción
Descripción
zendPath
La ruta a donde está ubicado el Zend Framework. Si hace parte del include_path de PHP entonces no es necesario establecerla.
class
La clase utilizada para administrar las vistas. Por defecto es Zend_View pero puede establecerse cualquier otra que implemente la interfaz Zend_View_Interface.
extension
La extensión que tendrán las vistas. Por defecto es .phtml.
