phplus framework Motor de Templates Guía de Referencia

(1)

phplus framework

Motor de Templates

Guía de Referencia

(2)

Parte 1: HTML

En la primera parte se explicarán la sintaxis y funciones aplicables

únicamente desde los archivos HTML, es decir desde los templates.

Sección de código

Formato:  [Codigo HTML]  Donde: • Seccion: Nombre clave único para la sección. • Código HTML: Representa el código HTML que se va a mostrar y ‐opcionalmente‐ se va a repetir en un bucle para desplegar todos los resultados necesarios. Dentro del código HTML, pueden, y generalmente, aparecen variables para cada nivel del bucle1.

Condicionales

Formato:

[Codigo HTML1]  [Codigo HTML2]  Donde: • Condicion: nombre clave de la condición a evaluar. En caso de evaluar a verdadero, se ejecutará el Código HTML1. Opcionalmente se puede agregar el segundo tag (else), usando la misma clave de la condición, seguida del código a ejecutar en caso de que la condicional evalúe a falso. 1_{Variables para cada nivel del bucle: son variables del tipo Variable normal, cuyo valor cambia para cada} repetición del bucle en la sección.

(3)

En el caso de no establecer el tag else y la condicional evalúe falso, no se mostrará ningún código HTML.

Switch (Condicional múltiple)

Formato:   [Codigo HTML1]   [Codigo HTML2]   [Codigo HTML3]   Donde:

•

Clave: nombre clave de la condición a evaluar.

•

Case ‘valor’: En caso de que la variable retornada por Clave sea igual a ‘valor’, se ejecutará el HTML1, en caso que sea igual a ‘valor2’, se ejecutará HTML2. Cualquier otro valor diferente a los dos anteriores ejecutará el case default, y por consecuencia HTML3. En caso de no incluir un case default, no se ejecutará ningún código.

Variable normal

Formato: {Variable} Donde:

(4)

• Variable: Nombre clave de la variable que se va a reemplazar por el valor establecido. En el caso que la variable se encuentre dentro de una sección, pude que el valor de ésta variable cambie para cada bucle2. En caso de que el valor establecido desde PHP para dicha variable sea un arreglo, el método para acceder a dicha variable es: {variable.indice} Donde variable es en nombre clave de la variable e índice es el índice ‘indice’ del arreglo variable. En otras palabras, es lo mismo que referenciar directamente desde PHP a: $variable[‘indice’] En el caso de que el valor establecido desde PHP para la variable sea un objeto, el método para acceder a las variables de dicho objeto es igual que para acceder a los índices del arreglo ({objeto.variable}). En caso de querer obtener el valor regresado por una función de la clase, el formato es: {objeto.metodo()}

Inclusiones Dinámicas

Formato: {@CARPETA.MODULO} Donde: • CARPETA: Nombre de la carpeta (Ojo: siempre en mayúsculas, sin importar que el nombre de la carpeta esté en minúsculas), donde se encuentra el archivo que queremos incluir. • MODULO: Nombre del archivo a incluir sin el prefijo correspondiente mod_ 3 y sin extensión.

Inclusiones Dinámicas (Dentro del gestor Artman)

2_{Bucle: Es una repetición definida de una parte de código. En éste caso, lo que se repite es el HTML} correspondiente a la sección en curso. 3_{mod_: Prefijo obligatorio para los archivos de tipo módulo para inclusión dinámica desde HTML. El formato} de éstos archivos es mod_nombredelmodulo.[tpl|html].

(5)

Formato: {@GESTOR_list.page} Donde: • GESTOR_: Prefijo necesario. • list: Nombre del article list (puede escribirse todo en mayúsculas en caso de que no use mayúsculas y minúsculas). • page: Nombre del archivo a incluir (sin extensión .php).

Snippets

Los snippets son pequeñas porciones de código HTML que se repiten constantemente en las secciones a través del sistema. Formato:

{snippet src=”modulo/archivo.html” var1=”val1” var2=”val2”}

Donde: • src: Atributo necesario que apunta al modulo y nombre del archivo que se va a incluir. • Var1: Nombre de la variable a sustituir dentro del template. • Val1: Valor con el cual se sustituirá la variable ‘var1’. Nota: En la parte del template que se va a incluir, se reemplazarán las variables dinámicas ( del formato {$variable}), con el valor que se le dé al atributo que coincida con el nombre del la variable. Se pueden agregar n numero de atributos en el tag.

Creación de URL para hipervínculos

Formato: {#action/section:variable=valor,otra_variable=otro_valor} Donde:

(6)

• Action: Valor correspondiente a la variable ‘módulo’ o ‘action’. • Section: Valor correspondiente a la variable ‘ejecutar’ o ‘section’. • Todo lo demás de los dos puntos: variables extras a enviar mediante GET, en formato variable=valor, otra=otro.

Variables de lenguaje

Formato: {%variable_texto} Donde: • Variable_texto: Nombre de la variable de texto. Éste tag se utiliza en sistemas que ocupan multilenguaje, de manera que la variable se sustituirá con el texto específico, en el idioma específico.

Variables dinámicas

Formato: {$nombre_variable} Donde: • Nombre_variable: Nombre de la variable dentro del scope actual o índice del arreglo asignado DENTRO de PHP.

Variables dinámicas (arreglos)

Formato: {$arreglo[indice]} Donde: • Arreglo: nombre del arreglo declarado dentro del PHP, al cual hacemos referencia.

(7)

• Índice: Indice del arreglo en cuestión (Sin comillas)

Validación de Formularios y Atributos Extras

Los campos en los formularios pueden tener los siguientes “atributos extras”: • validate: Atributo para validar los campos al momento de enviar el formulario. Éste puede tener los siguientes valores: o no‐empty: Valida que el campo no esté vacío. o email: Verifica que el campo tenga el formato necesario de correo electrónico. o number: Verifica que el campo sea un número. o custom / regex: Acepta expresiones regulares personalizadas. (Explicado a detalle en el atributo regex). • error: Éste atributo debe contener el mensaje de error que se le mostrará al usuario en caso de que valídate haya arrojado error en la validación. En caso de no establecer este atributo se mostrará un mensaje genérico. • regex: En caso de especificar validate=”custom” o validate=”regex”, debemos especificar el atributo regex, aquí es donde vamos a poner la expresión regular que el campo debe cumplir para poder enviarse. Ejemplo: para aceptar solamente mayúsculas: regex=”^[A-Z]+$”. Ojo: siempre debe de contener ^(inicio) y $(fin). • alt: Se puede usar para mostrar un mensaje “tip” en el campo. Éste mensaje se mostrará en un color más tenue cuando el campo esté vacío y se ocultará cuando el campo obtenga el foco o cuando el campo no esté vacío. Ejemplo: alt=”Nombre de usuario”.

Variables Globales

Variable Valor {USER} _{Nombre de usuario del usuario actual.} {USER_NAME} _{Nombre del usuario actual (en caso de que} esté loggeado) {USER_EMAIL} _{Email del usuario actual loggeado.} {PATH_IMG} _{Ruta a la carpeta de imágenes del template} actual. Incluye ‘/’ al final de la ruta.

(8)

{PATH_CSS} _{Ruta de la carpeta de css del template} actual. Incluye ‘/’ al final. {PATH_MEDIA} _{Ruta de la carpeta de media del template} actual (Flash, videos, etc). Incluye ‘/’ al final. {PATH_HTTP} _URL raíz {SHORT_DATE} _{Imprime la fecha actual en formato corto} dia‐mes‐año. {LONG_DATE} _{Imprime la fecha actual en formato largo. 1} de enero de 2009 {LOAD_TIME} _{Tiempo en segundos que tardo la página en} cargar.

Variables Globales Clave del Motor

Variable Valor {Title} _{Titulo de la página.} {Container} _{TODO el contenido de la página actual.}

Condicionales Globales

Condición Evalúa… IS_LOGGED _{Evalúa verdadero si el usuario se encuentra} actualmente loggeado al sistema. IS_ADMIN _{Evalúa verdadero si el usuario se encuentra} loggeado y el usuario tiene nivel de administrador. *NOTA: Para todas las condicionales, en caso de incluir un signo ‘!’ antes del nombre clave de la condición, la condición evaluará verdadero CASO CONTRARIO. Ejemplo: si quiero evaluar que el usuario NO esté conectado, sería:

Código en caso de que el usuario NO esté loggeado.

(9)

Modificadores

Los modificadores son métodos de todas las variables que facilitan la personalización del formato de salida de la variable. Los modificadores se aplican a variables normales y variables dinámicas. El formato general de modificadores es el siguiente: {variable.modificador()} Es posible que el modificador requiera de uno o más parámetros para completar algún modificador en específico, de ser necesario el formato es el siguiente: {variable.modificador(“parametro1”,”parametro2”, … ,”parametroN”)} Los modificadores pueden ir unidos en forma de cadena, de manera que una vez que se aplique el primer modificador, se seguirá con el segundo, y asi sucesivamente. Una variable con modificadores múltiples quedaría de la siguiente manera: {variable.modificador1().modificador2().modificadorN()} Los modificadores disponibles son los siguientes:

Nombre Descripción Parámetros

capitalize Capitaliza la primera letra de cada palabra. Ninguno default Funcion para establecer un valor en caso de que el valor de la variable sea vacio. 1. Valor a establecer en caso de que el valor de la variable sea vacio. encodeTags Convierte todos los tags HTML a las entidades HTML aplicables Ninguno decodeTags Covierte todas las entidades HTML a tags HTML Ninguno date Da formato específico de fecha al valor de la variable. 1. Formato de fecha: recibe los mismos formatos aplicables a la función date() de PHP format Da formato especifico a la cadena o numero. 1. Formato de cadena: recibe los mismos formatos

(10)

aplicables a la función sprintf() de PHP if Función para condicionar el valor del la variable en caso de tener un valor especifico. 1. Valor a comparar: El valor de la variable se comparará con este valor para realizar la evualizacion lógica. 2. Valor a establecer en caso de resultar verdadera la evaluación. 3. [opcional] Valor a establecer en caso de resultar falsa la evaluación. length Devuelve el numero de caracteres de la cadena Ninguno lower Convierte toda la cadena a minúsculas Ninguno nl2br Convierte los saltos de línea a . (Igual que la misma función de PHP) Ninguno numberFormat Da formato al numero de la forma: 1000.5 a 1,000.50 1. Decimales: Posiciones decimales a las cuales se va a redondear el numero. replace Reemplaza los caracteres especificados 1. Carácter(es) buscado(s). 2. Carácter(es) de reemplazo para los caracteres encontrados. truncate Corta la cadena en un determinado numero de caracteres 1. Numero de caracteres permitidos en la cadena. upper Convierte a mayúsculas todas las letras de la variable Ninguno Nota: recuerda que todos los modificadores van seguidos de un par de paréntesis ().

Variables Reservadas del Sistema

Estas variables se pueden acceder en cualquier momento. Nombre Contenido

(11)

system.now Fecha y hora actual en el formato: yyyy‐mm‐dd hh:mm:ss system.get Variable con el contenido de todo el GET del sistema. Acceder de la misma manera que una variable de tipo arreglo. system.request Variable con el contenido de todo el REQUEST del sistema. Acceder de la misma manera que una variable de tipo arreglo. system.post Variable con el contenido de todo el POST del sistema. Acceder de la misma manera que una variable de tipo arreglo. system.session Variable de tipo arreglo con el contenido de todo el SESSION del sistema. Acceder de la misma manera que variable de tipo arreglo. system.const Variable de tipo arreglo con el contenido de todas las constantes del sistema. Nota. Para acceder a cualquier variable arriba (P.ej. get), el formato adecuado de llamada es: Bienvenido {system.session.nombre} Si quisiéramos agregar un modificador para capitalizar la primera letra del nombre, y recortar a un máximo de 10 letras, seria de la siguiente forma: Bienvenido {system.session.nombre.capitalize().truncate(10)}

(12)

Parte 2: PHP

En esta parte, se hará referencia a todo lo que tiene que ver con el control de

templates desde PHP.

Instancia de la Clase

La clase del motor de templates es Template.php

Como primer parámetro de la función constructura, se acepta el path

(relativo u absoluto) donde se encuentra ubicado el template que vamos a

utilizar.

Como segundo paso es indicar cual es el template que se va a utilizar, para

ellos usamos la función:

Template::add_file(“archivo.html”)

Donde archive.html es un archivo ubicado en la ruta especificada.

Manipulación de Variables

Para establecer el valor de una variable normal, se pueden utilizar dos

métodos. Cuando la variable se encuentra fuera de toda sección, se utiliza:

Template::set(‘Variable’,’Valor’,true) ó Template::base_Variable=’Valor’

El Segundo metodo es por una “magic function”, y se aplica un ‘base_’ antes

del nombre de la variable para especificar que la variable se sustituirá en

todo el template.

Para reemplazar variables que se encuentran dentro de una sección, se

utilizan los mismo dos métodos con simples variantes:

(13)

Template::set(‘Variable’,’Valor’) ó Template::Variable=”Valor”

El valor establecido o asignado a la variable puede ser de tipo cadena,

numero, arreglo u objeto.

Secciones

Para manipular bucles de repetición, se utilizan las secciones.

Para “entrar” a una sección se utiliza la función:

Template::set_section(‘Seccion’)

La sección debe estar establecida desde el template HTML, de lo contrario se

elevará un error de ejecución de tipo Warning. Una vez dentro de la sección,

el alcance de manipulación se limite únicamente a la sección seleccionada.

Para iterar al siguiente bucle de la sección, se utiliza la función:

Template::next_section_iteration() ó el alias Template::loop()

Una vez terminados todos los bucles, debemos salir de la sección, sobre todo

si nos encontramos en secciones y bucles anidados. Si nos encontramos en

bucles anidados, debemos regresar a la sección padre de la siguiente

manera:

Template::set_section(‘SeccionPadre’)

De lo contrario, únicamente salimos de todas las secciones:

Template::finish_section()

Para salir solo un nivel del sección, se utiliza la función

Template::escape_section()

(14)

Condicionales de tipo IF

Los condicionales de tipo if funcionan únicamente para situaciones de caso

verdadero y opcionalmente un caso contrario.

El formato para establecer una condicional es:

Template::set_condition(‘ClaveCondicion’,Boolean) ó el alias Template::set_if

Donde ClaveCondicion es el nombre clave que se le dio a la condicional desde

el HTML. En la parte de boolean, generalmente se establece una evaluación

lógica para determinar si la condición es verdadera o falsa.

Esta función devuelve el valor ingresado como Boolean, de manera que se

pueda usar dentro de estructuras IF.

if( Template::set_condition(‘Clave’,(!empty($registros)) ){ // Codigo en caso de que haya registros

}

Condicionales de tipo Switch

Cuando hay varias opciones en el condicional, se utiliza Switch. La función

para establecer el switch es la siguiente:

Template::set_switch(‘ClaveSwitch’,$valor)

Donde: clave switch es la clave única de switch establecida en el HTML y

$valor es la variable que se va a comparar directamente al valor desde el

HTML.

(15)

Manipulacion de Variables Dinámicas

La manipulación de variables dinámicas es un método alternativo para poblar

y acceder desde el template a todas las variables declaradas en el alcance

actual del script.

La función para publicar variables es:

Template::render_vars(get_defined_vars(),’caller’,$indice,Boolean)