On-Line Documentation : Louder Technology : PHP for Enterprise

Actions

Manual Index

Print View

PDF version

Projects

Kumbia Enterprise

Kumbia Enterprise Framework for IBM WebSphere

Louder Clustering

Louder Cache

Louder Application Forms

Need help?

Community Forums

Note

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.

Learn More

Select a Language:

Anterior - 25. Componente View

Siguiente - 27. Helpers JavaScript

Componente Tag

Tabla de Contenido:

26.1. Introducción
26.2. Establecer el valor de helpers creados con Tag
26.3. Comportamiento de helpers
26.4. API del Componente Tag
26.4.1. Crear enlaces
26.4.2. Componentes de interfaz de usuario
26.4.3. Componentes de listas/combos
26.4.4. Tratamiento de etiquetas META
26.4.5. Tratamiento e Inclusión de archivos CSS
26.4.6. Componentes para fechas
26.4.7. Incluir recursos Javascript
26.4.8. Interacción con la presentación

Introducción

Este componente actua como una biblioteca de etiquetas que permite generar tags XHTML en la presentación de una aplicación mediante métodos estáticos PHP predefinidos flexibles que integran tecnología del lado del cliente como CSS y Javascript.

La ventaja de utilizar estos helpers en lugar de XHTML puro, es que acelera el desarrollo y hace consistente el código XHTML y otros aspectos como las URLs y el convencionalismo del framework.

Cada método estático recibe sus opciones mediante parámetros por nombre que se pueden enviar en cualquier orden al mismo. En los tag que generan etiquetas es posible enviar parámetros XHTML ó CSS con su respectivo valor asignandose a la etiqueta generada.

Establecer el valor de helpers creados con Tag

Una de las ventajas más importantes de crear componentes de interfaz de usuario con Tag es lo sencillo que se puede asignar el valor de estos de forma uniforme y controlada.

Cada componente localiza el valor que debe presentar mediante las siguientes reglas. Si alguna regla se cumple las demás no son validadas:

Verifica si existe algún valor para él asignado con Tag::displayTo y lo toma como valor
Verifica si hay algún indice en $_POST que coincida con el atributo "id" de él y toma como valor
Verfica si existe un atributo público en el último controlador ejecutado que coincida con el atributo "id" de él y lo toma como valor.

Si a algún helper se le asigna directamente con el parámetro "value" ninguna de las reglas anteriores se tiene en cuenta.

El siguiente ejemplo ilustra la asignación de un valor a componente de interfaz de usuario creado mediante Tag:

Ejemplo: Mostrar un valor en un componente visual desde el controlador mediante Tag::displayTo

<?php

class PeopleController extends ApplicationController {

     public function indexAction(){
          Tag::displayTo('genero', 'F');
     }

}

En la vista el como estático se visualizará con el valor "F" seleccionado:

<?php

$generos = array(
     'M' => 'Masculino',
     'F' => 'Femenino'
);

echo Tag::selectStatic("genero", $generos); ?>

El desarrollador debe validar que no se asignen valores con displayTo cuando se deba visualizar los valores capturados por el usuario en la petición POST.

Comportamiento de helpers

Todos los helpers en el componente Tag devuelven código HTML generado por cada uno lo que permite utilizar este para utilizarlo como parámetro de otros helpers ó usarlo como se requiera.

<?php echo Tag::linkTo("controlador/accion", Tag::image("foto.jpg")) ?>

Los helpers pueden recibir parámetros por nombre ó un array asociativo cuyos indices seán los nombres de los parámetros.

<?php echo Tag::form("controlador/accion",  "method: post") ?>

<?php echo Tag::form(array("controlador/accion",  "method" => "post")) ?>

API del Componente Tag

A continuación se presenta el API del componente:

Crear enlaces

public static function linkTo(mixed $params)
Permite crear un enlace a una punto de la aplicación utilizando las convenciones de Kumbia Enterprise; este método genera un tag A de XHTML con la posibilidad de implementar tanto una confirmación antes de ejecutarse como de aplicar cualquier atributo que se desee a este tag. El label de la etiqueta puede ser un texto ó cualquier otro tag como por ejemplo una imagen.

Las opciones extendidas del componente son:

Tabla: Parámetros que recibe linkTo

Nombre	Descripción
confirm	Permite establecer que se presente un cuadro de dialogo de presentación al usuario que confirme la petición de la URL en el tag A.
text	Es el texto que aparecerá en el enlace.

Ejemplo: Uso de linkTo

<?php echo Tag::linkTo("controlador/saludo", "Saludar") ?>

<?php echo Tag::linkTo("controlador/saludo","SALUDAR", "class: css_saludo", "border: 0", "confirm: Desea ir a Saludo?") ?>

Genera el siguiente código XHTML:

<a onclick='if(!confirm("Desea ir a saludo?")) return false;' border="0" class="css_saludo" href="/instancia/controlador/saludo">SALUDAR</a>

public static function linkToAction(mixed $params)
Genera un enlace a una acción asociada al controlador actual. Al igual que linkTo es posible aplicar atributos HTML pasandolos como otros parámetros.

Ejemplo: Uso de linkToAction

<?php echo Tag::linkTo("cancelInvoice", "Cancelar") ?>

<?php echo Tag::linkTo("cancelInvoice", "Cancelar", "class: css_saludo", "border: 0", "confirm: Desea cancelar la factura?"); ?>

Opciones extendidas de linkToAction:

Tabla: Opciones extendidas de linkToAction

Nombre	Descripción
confirm	Permite establecer que se presente un cuadro de dialogo de presentación al usuario que confirme la petición de la URL en el tag A.
text	Es el texto que aparecerá en el enlace.

public static function linkToRemote(mixed $params)
Carga el contenido de una acción en un contenedor HTML dentro de la presentación actual. La vista se obtiene mediante AJAX por lo que la página no es recargada.

En el siguiente ejemplo se cargará el contenido de una acción en el div con id 'the_menu':

Ejemplo: Uso del helper linkToRemote

<div id='the_menu'></div>

<?php echo Tag::linkToRemote('main/getMenu', 'Texto del Enlace', 'the_menu') ?>

Como la presentación es parcial se debe modificar la salida del controlador para solo mostrar la vista asociada y saltar los templates ó layouts.

<?php

class MainController extends ApplicationController {

     public function indexAction(){

     }

     public function getMenuAction(){
          $this->setResponse('ajax');
     }

}

También es posible implementar eventos AJAX a medida que se procesa la petición mejorando la experiencia de usuario:

<div id='the_menu'></div>

<?php echo Tag::linkToRemote("main/getMenu", "Texto del Enlace", "the_menu", "onLoading: $('info').update('Cargando...')") ?>

Opciones de linkToRemote:

Tabla: Parámetros que recibe linkToRemote

Nombre	Descripción
confirm	Permite establecer que se presente un cuadro de dialogo que confirme la petición de la URL.
text	Es el texto que aparecerá en el enlace. Si no se establece el segundo parámetro del enlace es tomado.
update	Es el contenedor HTML donde se presentará el contenido de la vista.
onLoading	Código JavaScript a ejecutar antes de realizar la petición HTTP interna.
onSuccess	Código JavaScript a ejecutar cuando la petición se completa con éxito. El objeto con la el resultado petición puede obtenerse usando la variable 'transport'.
onComplete	Código JavaScript a ejecutar cuando la petición se completa. El objeto con la el resultado petición puede obtenerse usando la variable 'transport'.
onFailure	Código JavaScript a ejecutar cuando la petición falla ó se genera una excepción. El objeto con la el resultado petición puede obtenerse usando la variable 'transport'. En este mismo evento se carga el contenido de la presentación en el contenedor.
asynchronous	Permite establecer si la petición es asincronica ó sincrónica. Se debe establecer un valor booleano true ó false. Por defecto es false.

Adicional a lo anterior linkToRemote acepta como parámetro cualquier nombre de atributo aplicable a la etiqueta A.

Componentes de interfaz de usuario

public static function textField(mixed $params)
Crea una caja de texto con los parámetros establecidos.

<?php echo Tag::textField("nombre") ?>

El código HTML generado es:

<input type='text' id='nombre' value='' name='nombre'  />

El helper textField acepta como parámetro cualquier nombre de atributo aplicable a la etiqueta input type="text".

public static function textArea(mixed $params)
Permite crear una area de texto (textarea) con los parámetros establecidos.

Ejemplo: Uso del helper Tag::textArea

<?php echo Tag::textArea("nombre", "cols: 120", "rows: 5") ?>

Lo cúal genera el siguiente código HTML:

<textarea id="nombre" name="nombre" cols="120" rows="5"></textarea>

El helper textArea acepta como parámetro cualquier nombre de atributo aplicable a la etiqueta textarea.

public static function numericField(mixed $params)
Crea una caja de texto con los parámetros establecidos validando que su entrada sea solo valores numéricos.

Ejemplo: Uso del helper Tag::numericField

<?php echo Tag::numericField("accountNumber") ?>

El helper numericField acepta como parámetro cualquier nombre de atributo aplicable a la etiqueta input type="text".

public static function numericPasswordField(mixed $params)
Crea una caja de texto para contraseñas con los parámetros establecidos validando que su entrada sea solo valores numéricos. Este componente debe ser usado en casos especiales de confianza ya que su naturaleza ayudaría a un tercero malintencionado a conocer que el password solicitado es un algún valor numérico.

Ejemplo: Uso del helper numericPasswordField

<?php echo Tag::numericPasswordField("password") ?>

El helper numericPasswordField acepta como parámetro cualquier nombre de atributo aplicable a la etiqueta input type="password".

Componentes de listas/combos

public static function selectStatic(mixed $params)
Crea un combo con valores estáticos establecidos en un vector.

Ejemplo: Uso del helper Tag::selectStatic

<?php 

$estados = array(
     'A' => 'ACTIVO',
     'I' => 'INACTIVO'
);
echo Tag::selectStatic("estados", $estados, 'useDummy: yes');

Lo cuál genera el siguiente HTML:

<select id='estados' name='estados'>
     <option value='@'>Seleccione...</option>
     <option value='A'>ACTIVO</option>
     <option value='I'>INACTIVO</option>
</select>

Opciones de selectStatic:

Tabla: Parámetros recibidos por selectStatic

Nombre	Descripción
useDummy	Indica que se debe colocar una opción adicional 'Seleccione…' al prinicipio de la lista. El valor de este es una '@'.
dummyValue	Permite cambiar el valor de la opción Dummy de '@' al valor indicado.
dummyText	Permite cambiar el texto de la opción Dummy de 'Seleccione…' al texto indicado.

Adicional a lo anterior selectStatic acepta como parámetro cualquier nombre de atributo aplicable a la etiqueta SELECT.

public static function select(mixed $params)
Permite generar una lista desplegable mediante un array, un ActiveRecordResultset (resultado de ActiveRecord) ó un ActiveRecordRow (resultado de ActiveRecordJoin):

Ejemplo: Uso del helper Tag::select

<?php echo Tag::select('userId', $Users->find('order: name'), 'using: id,name', 'useDummy: yes') ?>

El primer parámetro de este helper es el id/name que tomará la lista. El segundo son los datos de la lista. Cuando se usa un ActiveRecordResultset ó ActiveRecordRow se debe establecer el parámetro using, el cuál es una pareja de atributos que será utilizada como valor/texto de cada opción de la etiqueta SELECT generada.

Opciones de select:

Tabla: Parámetros recibidos por Tag::select

Nombre	Descripción
useDummy	Indica que se debe colocar una opción adicional 'Seleccione…' al prinicipio de la lista. El valor de este es una '@'.
dummyValue	Permite cambiar el valor de la opción Dummy de '@' al valor indicado.
dummyText	Permite cambiar el texto de la opción Dummy de 'Seleccione…' al texto indicado.

Adicional a lo anterior select acepta como parámetro cualquier nombre de atributo aplicable a la etiqueta SELECT.

public static function localeSelect()
Es identico al helper select pero en este se aplica una función de localización a cada texto de las opción mediante un objeto de traducción.

El siguiente ejemplo muestra los idiomas disponibles basado en un objeto de traducción:

Ejemplo: Uso del helper Tag::localeSelect

<?php echo Tag::localeSelect('languageId', $Languages->find('order: name'), $traslate, 'using: id,name', 'useDummy: yes') ?>

public static function selectMixed()
Este método permite crear listas combinando arrays de valores estáticos y resultados dinámicos.

Ejemplo: Uso del helper Tag::selectMixed

<?php 

$dynamicData = $Categories->find();
$staticData = array(
     'N' => 'NINGUNO DE LOS ANTERIORES'
);

echo Tag::selectMixed('categoriesId', $dynamicData, $staticData, 'using: id,name', 'useDummy: yes') ?>

Las opciones adicionales de selectStatic y select también aplican a selectMixed.

public static function submitImage($caption, $src)
Permite crear un botón de envío de formulario con una imagen en vez de un texto. Recibe como parámetros "caption" que contendrá el texto que aparece en caso de que la imágen no pueda ser cargada. "src" especifica la ruta de la imagen.

Ejemplo: Uso del helper Tag::submitImage

<?php echo Tag::submitImage('Enviar', Core::getInstancePath.'img/submit.png') ?>

Adicionalmente este helper acepta como parámetro cualquier atributo o propiedad que pueda ser aplicable a la etiqueta input type='image'.

public static function button()
Permite crear un botón típico de HTML sin ninguna acción por defecto.

Ejemplo: Uso del helper Tag::button

<?php echo Tag::button('Actualizar','id: update','onclick: actualiza()') ?>

Recibe además los cualquier evento que pueda definirse para el botón con su correspondiente acción en javascript.

public static function image($img)
Incluye una imagen en una vista teniendo en cuenta el direccionamiento de los directorios del framework. El parámetro "img" define el nombre de la imagen que debe estar incluida dentro de la carpeta 'img'.

Ejemplo: Uso del helper Tag::image

<?php echo Tag::image('imagen.png', 'alt: Imagen') ?>

Opciones de image:

Tabla: Parámetros recibidos por Tag::image

Nombre	Descripción
alt	Especifica un texto alternativo para la imagen.

public static function formRemote($params)
Permite generar un formulario remoto, que será enviado con una petición de Ajax. El parámetro "params" permite ingresar una serie de opciones para el helper.El primer parámetro ingresado es el que define el valor de la propiedad action para la etiqueta 'form'.

Ejemplo: Uso del helper Tag::formRemote

<?php echo Tag::formRemote('usuarios/buscar','update: findResults','required: name') ?>

Opciones de formRemote:

Tabla: Parámetros que recibe formRemote

Nombre	Descripción
action	Valor que tendrá la propiedad 'action' del formulario.
complete	Callback que contendrá el codigo javascript que se ejecutará una vez se active el evento complete del formulario.
befote	Callback que contendrá el codigo javascript que se ejecutará antes de que el formulario sea enviado.
success	Callback que contendrá el codigo javascript que se ejecutará una vez se active el evento success del formulario.
required	Colección de campos que son requeridos para el formulario, ocurre una validación de dichos campos antes de hacer el envío.
update	Id de la etiqueta que será actualizada una vez se complete el envío.

public static function submitRemote($caption)
Crea un botón de envío para el formulario remoto actual. El parámetro "caption" define el texto que se muestra en el botón.

Ejemplo: Uso del helper Tag::submitRemote

<?php echo Tag::submitRemote('Buscar', 'update: findResults') ?>

Opciones de submitRemote:

Tabla: Parámetros que recibe Tag::submitRemote

Nombre	Descripción
caption	Valor que tendrá la propiedad 'value' del botón.
complete	Callback que contendrá el codigo javascript que se ejecutará una vez se active el evento complete del formulario.
before	Callback que contendrá el codigo javascript que se ejecutará antes de que el formulario sea enviado.
success	Callback que contendrá el codigo javascript que se ejecutará una vez se active el evento success del formulario.
update	Id de la etiqueta que será actualizada una vez se complete el envío.

public static function form($action)
Crea una etiqueta de apertura de un formulario. El parámetro "action" es el valor de la propiedad 'action' del formulario.

Ejemplo: Uso del helper Tag::form

<?php echo Tag::form('usuarios/buscar','id: formSearch') ?>

Opciones de submitRemote:

Tabla: Parámetros que recibe el helper Tag::form

Nombre	Descripción
action	Valor que tendrá la propiedad 'action' del formulario.
method	Método que será usado para el envío del formulario.
confirm	Si es declarado define el mensaje de confirmación para el envío del formulario.
onsubmit	Callback que contendrá el codigo javascript que se ejecutará una vez se active el evento submit del formulario.

public static function endForm()
Etiqueta que finaliza el formulario, corresponde al codigo de cierre de dicha etiqueta.

Ejemplo: Uso del helper Tag::endForm()

<?php echo Tag::endForm() ?>

Genera el siguiente codigo XHTML:

</form>

public static function submitButton($caption)
Permite crear un botón de envío para el formulario actual. Ingresa como parámetro el valor del texto que será mostrado en el botón. Además recibe cualquier atributo que pueda ser aplicable a una etiqueta input type='submit'.

Ejemplo: Uso del helper Tag::submitButton

<?php echo Tag::submitButton('Buscar', 'id: submitSearch') ?>

Tratamiento de etiquetas META

public static function setMeta(string $name, string $content)
Carga en memoria una etiqueta Meta para las cabeceras del documento HTML. Recibe el nombre de la etiqueta y un contenido para la misma.

Ejemplo: Uso del helper Tag::setMeta

<?php echo Tag::setMeta('description','Busqueda de usuarios.') ?>

public static function getMetas()
Imprime las etiquetas Meta que han sido cargadas previamente. No recibe parámetros e imprime automáticamente el resultado en el documento HTML.

Ejemplo: Uso del helper Tag::getMetas()

<?php Tag::getMetas() ?>

Tratamiento e Inclusión de archivos CSS

public static function stylesheetLink(string $src='', $useVariables=false)
Adiciona una etiqueta de link que incluye un archivo CSS teniendo en cuenta las rutas que se definen en Kumbia Enterprise. El primer parámetro constituye la ruta de ubicación del archivo CSS, el segundo determina si se usará un traductor de las variables globales que se pueden especificar en los archivos CSS.

Ejemplo: Uso del helper Tag::styleSheetLink

<?php echo Tag::stylesheetLink('calendar', true) ?>

Las variables CSS pueden usarse para reemplazar rutas absolutas que ayuden asegurar que imagenes u otros recursos seran establecidos correctamente.

Las posibles variables que se pueden utilizar son:

Tabla: Variables CSS que soporta el Tag::styleSheetLink

Variable	Descripción
@path	Ruta absoluta del servidor web hacia la instancia del framework.
@img_path	Ruta absoluta del servidor web hacia el directorio img de la instancia del framework.
@css_path	Ruta absoluta del servidor web hacia el directorio css de la instancia del framework.

En una clase CSS las variables se utilizan así:

Ejemplo: Uso de variables CSS con Tag::stylesheetLink

.header {
     background-image: url("@path/img/site/bg-header.gif");
}

Para aumentar el rendimiento del reemplazo de variables en archivos CSS estos se cachean en el directorio temp/ y se refrescan cuando se detecta cambios en ellos.

public static function removeStylesheets()
Remueve los tags de css agregados.

Componentes para fechas

public static function dateField(mixed $params)
Permite validar que los dato capturado sea una fecha. Este helper crea 3 listas una para los meses, días y otra para los años. Los nombres de los meses se muestran en el idioma de la localización activa. El valor capturado se almacena en un input oculto con el nombre del dateField.

Ejemplo: Uso de helper Tag::dateField

<?php echo Tag::dateField("fechaInicial") ?>

Por defecto dateField muestra la fecha 1 de enero del año en curso, sin embargo esta fecha no es válida.

Opciones de dateField:

Tabla: Parámetros que acepta Tag::dateField

Nombre	Descripción
startYear	Indica el año menor que tendrá la lista año.
finalYear	Indica el año mayor que tendrá la lista año.
useDummy	Indica si se debe forzar al usuario a seleccionar un valor valido.

Adicional a lo anterior dateField acepta como parámetro cualquier nombre de atributo aplicable a la etiqueta table.

public static function localeDateField(mixed $params, Traslate $traslate)
Es identico a dateField pero los nombres de los meses son tomados de la lista de localización actual permitiendo mostrarlos varios idiomas.

Ejemplo: Uso del helper Tag::localeDateField

<?php echo Tag::localeDateField("fechaInicial", $traslate) ?>

El helper localeDateField acepta como parámetro cualquier nombre de atributo aplicable a la etiqueta table.

Incluir recursos Javascript

public static function javascriptInclude(string $src='', boolean $cache=true)
Permite insertar una etiqueta <script> con la referencia a un archivo javascript de la instancia actual. La extensión .js debe ser omitida ya que el helper la agrega automáticamente.

Ejemplo: Uso del helper Tag::javascriptInclude

<?php echo Tag::javascriptInclude("lightbox") ?>

Genera el código HTML:

Cuando se pasa false en el segundo parámetro se agrega a la URL del HTML generado el parámetro GET nocache=valor donde valor es un entero aleatorio entre 0 y 999999. De esta forma se obliga al navegador a recargar el recurso javascript en cada petición.

Ejemplo: Uso del helper Tag::javascriptInclude con cache

<?php echo Tag::javascriptInclude("lightbox", false) ?>

Genera el código HTML:

Si se omite el nombre del JavaScript se trata de insertar un archivo con el mismo nombre del controlador actual.

public static function javascriptMinifiedInclude(string $src='')
Permite insertar un javascript minimizado con JsMin. El parámetro $src es la ubicación del archivo en el servidor una versión pública es generada la cuál es regenerada cada vez que se modifica el archivo original. Los archivos javascript minimizados consumen menor ancho de banda y pueden aumentar la velocidad de carga de la aplicación en clientes con velocidades de conexión reducidas.

Ejemplo: Uso del helper Tag::javascriptMinifiedInclude

<?php echo Tag::javascriptMinifiedInclude("lightbox") ?>

Genera el código HTML:

El directorio public/javascript debe tener permisos de escritura para usar este helper.

Interacción con la presentación

static function void displayTo(string $id, string $value)
Establece el valor para un componente visual del formulario que se va a presentar en la petición actual. El valor definido mediante este helper tiene mayor prioridad cuando se trata de obtener el valor de los componentes visuales.

Ejemplo: Uso del helper Tag::displayTo

<?php Tag::displayTo("nombre", "Juanita Mendoza");

En la vista la caja "nombre" se muestra con el valor establecido:

<?php echo Tag::textField("nombre") ?>

lo que produce:

<input type="text" id="nombre" name="nombre" value="Juanita Mendoza" />

static function mixed getValueFromAction(string $name)
Permite obtener el valor que será presentado en un componente visual como lo es una caja de texto ó una lista (combo). Todos los helpers realizan un llamado interno usando este método para obtener el valor a presentar dependiendo la naturaleza de cada uno.

Los valores son obtenidos en este orden:

Se verifica si existe algún valor para él asignado con Tag::displayTo y lo toma como valor
Se verifica si hay algún indice en $_POST que coincida con el atributo "id" de él y toma como valor
Verfica si existe un atributo público en el último controlador ejecutado que coincida con

Ejemplo: Uso del helper Tag::getValueFromAction

<?php

$nameValue = Tag::getValueFromAction('nameValue');

LouderTechnology ® 2012 - All rights reserved	About Louder Privacy Contact Us Legal Terms
The LouderTechnology ® and Kumbia Enterprise trademarks and logos are trademarks of LouderTechnology ®.	Select your language: