Smarty Manual. Monte Ohrt <monte at ohrt dot com> Andrei Zmievski Mario Ramírez

Transcripción

1 Smarty Manual Monte Ohrt <monte at ohrt dot com> Andrei Zmievski Mario Ramírez

2 Smarty - El motor compilador de Plantillas para PHP by Monte Ohrt <monte at ohrt dot com> and Andrei Zmievski <andrei@php.net> by Mario Ramírez <mario_ramirez@fjcorona.com.mx> Publication date Copyright New Digital Group, Inc.

3 Table of Contents Prólogo... xii I. Iniciando Que es Smarty? Instalación... 5 Requerimentos... 5 Instalación Básica... 5 Expandiendo la configuración... 9 II. Smarty For Template Designers Basic Syntax Comentarios Variables Funciones Atributos Colocando variables entre comillas dobles Matemáticas Escaping Smarty Parsing Variables Variables definidas desde PHP Arreglos asociativos Índices de Matrices Objects Variables cargadas desde archivos de configuración La variable reservada {$smarty} Solicitud de Variables {$smarty.now} {$smarty.const} {$smarty.capture} {$smarty.config} {$smarty.section}, {$smarty.foreach} {$smarty.template} {$smarty.version} {$smarty.ldelim}, {$smarty.rdelim} Modificadores de variables capitalize cat count_characters count_paragraphs count_sentences count_words date_format default escape indent lower nl2br regex_replace replace spacify string_format strip strip_tags iii

4 Smarty Manual truncate upper wordwrap Combinando Modificadores Funciones Integradas capture config_load {foreach},{foreachelse} iteration first last show total include {include_php} insert if,elseif,else {ldelim},{rdelim} literal {php} section,sectionelse index index_prev index_next iteration first last rownum loop show total {strip} Custom Functions {assign} {counter} cycle {debug} {eval} {fetch} {html_checkboxes} {html_image} {html_options} {html_radios} {html_select_date} {html_select_time} {html_table} math {mailto} {popup_init} popup {textformat} Config Files Debugging Console III. Smarty For Programmers iv

5 Smarty Manual 11. Constantes SMARTY_DIR SMARTY_CORE_DIR Clase Variables de Smarty $template_dir $compile_dir $config_dir $plugins_dir $debugging $debug_tpl $debugging_ctrl $autoload_filters $compile_check $force_compile $caching $cache_dir $cache_lifetime $cache_handler_func $cache_modified_check $config_overwrite $config_booleanize $config_read_hidden $config_fix_newlines $default_template_handler_func $php_handling $security $secure_dir $security_settings $trusted_dir $left_delimiter $right_delimiter $compiler_class $request_vars_order $request_use_auto_globals $error_reporting $compile_id $use_sub_dirs $default_modifiers $default_resource_type La clase Methods() de Smarty append() append_by_ref assign() assign_by_ref clear_all_assign() clear_all_cache clear_assign() clear_cache() clear_compiled_tpl() clear_config() config_load() display() fetch() get_config_vars() v

6 Smarty Manual get_registered_object() get_template_vars() is_cached() load_filter() register_block() register_compiler_function register_function() register_modifier() register_object() register_outputfilter() register_postfilter() register_prefilter() register_resource trigger_error template_exists() unregister_block unregister_compiler_function() unregister_function() unregister_modifier() unregister_object() unregister_outputfilter() unregister_postfilter() unregister_prefilter() unregister_resource() Cache Configurando el Cache Multiples caches por pagina Cache Groups Controlando salida de Cacheabilidad de plugins Caracteristicas Avanzadas Objetos Prefilters Postfilters Filtros de salida Función manipuladora de cache Recursos Templates desde $template_dir Templates partiendo de cualquier directorio Templates partiendo de otras fuentes Función manipuladora de Template por default Extendiendo Smarty con plugins Como funcionan los Plugins Nombres convencionales Escribiendo Plugins Funciones de Template Modificadores Block Functions Funciones Compiladoras Prefiltros/Postfiltros Filtros de Salida Fuentes Inserts IV. Appendixes Localización de Errores vi

7 Smarty Manual Errores Smarty/PHP Consejos y Trucos Manipulación de Variables Vacias Manipulación del valor default de una variable Pasando la variable titulo a la cabecera del template Fechas WAP/WML Templates con Componetes Ofuscando direcciones de Fuentes ERRORES vii

8 List of Examples 2.1. Archivos de la libreria Smarty Creando una instancia Smarty de Smarty Reemplazar por la ruta absulta de la libreria del archivo Adicionar el directorio de la libreria para incluirlo en el include_path de PHP Defina la constante SMARTY_DIR manualmente Ejemplo de estrutura de archivo Configurando permisos de archivos Editando /web/ Editando /web/ Editando /php/includes/guestbook/setup.php Editando /web/ Comentarios Variables Sintaxis de Funciones Sintaxis de atributos de Funciones Sintaxis entre comillas Ejemplos de matemáticas Ejemplo cambiando delimitadores variables definidas Accesando variables de matriz asociativa Accesando matrices por sus índices Accesando propiedades de los Objetos Variables de configuración Mostrando solicitud de variables Usando {$smarty.now} Usando {$smarty.const} Ejemplo de modificador capitalize cat count_characters count_paragraphs count_sentences count_words date_format default escape indent lower nl2br regex_replace replace spacify string_format strip strip_tags truncate upper wordwrap Combinando Modificadores capturando contenido de template Función {config_load} viii

9 Smarty Manual 7.3. Función config_load con section foreach foreach key Ejemplo de {foreach} - con base de datos (eg PEAR o ADODB) funcion {include} Función {include} pasando variables {include} y asignacion de variables Ejemplos de recursos para la función include funcion {include_php} función {insert} sentencia if {ldelim}, {rdelim} Etiqueta literal Etiqueta {php} section loop(ciclo) de la variable section Nombres de section sections anidadas sections y matrices asociativas {sectionelse} {section} propiedades del index {section} propiedades del index_next y index_prev {section} propiedades de iteration {section} propiedades first y last {section} propiedades de index section atributos de show {section} propiedades de total {strip} tags {assign} Accesando variables desde un script de PHP. {assign} counter cycle {eval} fetch {html_checkboxes} ejemplo de base de datos (eg PEAR o ADODB): html_image example {html_options} {html_options} - Ejemplo con base de datos (eg PEAR o ADODB): {html_radios} : Ejemplo {html_radios} : Ejemplo {html_radios}- Ejemplo con base de Datos (eg PEAR o ADODB): {html_select_date} {html_select_date} {html_select_time} html_table {math} {mailto} popup_init popup {textformat} Ejemplo de sintaxis de un archivo de configuración SMARTY_DIR SMARTY_CORE_DIR ix

10 Smarty Manual multiple $plugins_dir Arreglo de variables de configuración $compile_id append append_by_ref assign() assign_by_ref() clear_all_assign() clear_all_cache clear_assign() clear_cache() clear_compiled_tpl() clear_config() config_load() display() Ejemplos de recursos de la función display fetch() Usando fetch() y enviando a un get_config_vars() get_registered_object() get_template_vars is_cached() is_cached() con templates con multiple-cache loading filter plugins register_block() register_function() register_modifier() register_resource template_exists() unregister_function() unregister_modifier() unregister_resource() Habilitando Cache Configurando cache_lifetime por cache Habilitando $compile_check Usando is_cached() Limpiando el cache Pasando un cache_id para display() Pasando un cache_id para is_cached() Limpando todos los caches para un cache_id en particular Grupos de cache_id Previniendo que una saída de plugin de ser cacheada Previniendo una pasada entera del template para el cache usando un objeto registrado o atribuido usando un prefiltro prefilter de template Usando un postfilter de template Usando un filtro de salida de template ejemplo usando MySQL como una fuente de cache Usando templates desde $template_dir usando templates desde cualquier directorio usando templates con rutas de archivos de windows Usando recursos habituales usando la función manipuladora de template por default Función de plugin con salida x

11 Smarty Manual Función de plugin sin salida Plugin modificador simple Plugin modificador mas complejo Función de bloque Función compiladora simple prefilter plugin postfilter plugin plugin de filtro de salida Plugin resource (recurso) insert plugin Errores de Smarty Errores de analisis gramatical de PHP Otros errores comunes Imprimiendo cuando una variable esta vacia Atribuyendo el valor por default a una variable en el template Pasando la variable titulo al encabezado del template Usando date_format Convirtiendo elementos en forma de fecha de vuelta a un timestamp Usando insert para escribir un encabezado WML Content-Type Templates con Componetes Ejemplo de ofuscamiento de una direccion de xi

12 Prólogo Esta es indudablemente una de las preguntas que mas se hacen en las listas de correo de PHP: Como hacer mis scripts de PHP independientes del diseño?. Mientras PHP se encarga de como "incrustar scripts en lenguaje HTML", después de escribir los proyectos que mezclan PHP y HTML libremente, esto trae como consecuencia la idea de separar la forma y el contenido, muy buena idea[tm]. En adición, en muchas compañias la interpretación de esquema es diseñador y programador por separado. Por consiguiente, la busqueda trae como solución una plantilla(template). Por ejemplo en nuestra compañia, el desarrollo de una aplicación es como sigue: Después de tener la documentación necesaria, el diseñador de web diseña el prototipo de la interfaz y la entrega al programador. El programador implementa las reglas de negocio en PHP y usa el prototipo para crear el "esqueleto" de la plantilla. El proyeto esta en manos de la persona responsable del HTML designer/web page que produzca la plantilla para su gloria completa. El proyecto debe ir y regresar entre programación/html varias veces. De esa manera, es importante para tener un buen suporte de templates porque los programadores no quieren hacer nada con HTML ni quieren diseño HTML al rededor del codigo PHP. Los diseñadores precisan de soporte para archivos de configuración, bloques dinámicos y otras interfaces usadas, mas ellos no quieren ocuparse con las compejidades del lenguaje de programación PHP. Buscando, actualmente existen muchas soluciones de templates disponibles para PHP, la mayor parte de ellos les provee de una forma rudimentaria de sustitución de variables dentro del template y hace una forma limitada de la funcionalidad dinámica del bloque. Pero nuestras necesidades requieren mas que eso. Porque no queremos programadores que no quieran tener trato con HTML del todo, pero esto puede ser casi inevitable. Por ejemplo, si un diseñador quiere alternar colores de fondo sobre bloques dinámicos, esto tuvo que trabajarse con el programador anticipadamente. Nosotros necesitamos también que los diseñadores esten capacitados para usar archivos de configuración, y colocar variables de ellos dentro de los templates. La lista continua. Nosotros empezamos escribiendo por fuera una especulación para un motor de plantillas(templates) atrasado de Después de terminar la especulación, comenzamos a trabajar un motor de plantillas escrito en C que esperanzadoramente fue aceptado para ser incorporado con PHP. No solamente nos encontramos con algunas complicadas barreras tecnicas, si no también hubo acalorados debates sobre lo que exactamente debia de hacer o no un motor de plantillas. De esta experiencia, decidimos que un motor de platillas devería ser escrito en PHP como una clase, para que cualquiera lo use de la misma forma como ellos ven. Así nosotros escribimos un motor que es SmartTemplate nunca volvio a existir(nota: esa clase nunca fue enviada al público). Esta era una clase que ralizaba casi todo lo que nosotros necesitabamos: sustitución de variables regulares, soporte incluso de otras plantillas, integración con archivos de configuración, incrustación de código PHP, funcionalidades 'if' limitada y muchos mas bloques dinámicos robustos que podrían ser anidados muchas veces. Todo esto con expresiones regulares y el código producido seria mejor, como diriamos nosotros, impenetrable. Eso era también notoriamente lento en grandes aplicaciones por todas las interpretaciones y expresiones regulares trabajando en cada requisición. El mayor problema del punto de vista de un programador era todo el trabajo necesario en el procesamiento del scripts PHP y procesamiento de bloques dinámicos de la plantilla. Como hacemos eso facilmente? Entonces se origino la visión de que finalmente se convirtiera en Smarty. Nosotros sabemos que rápido es el código PHP sin las cabeceras y la interpretación de plantillas(templates). También sabemos que meticuloso y arrogante es el lenguaje PHP su poder debe ser aceptable para un diseñador, y este podría ser enmascarado con una simples sintaxis de plantillas(templates). Entonces que pasara si nosotros convinamos las dos fuerzas? De esta manera, nacio Smarty... xii

13 Part I. Iniciando

14 Table of Contents 1. Que es Smarty? Instalación... 5 Requerimentos... 5 Instalación Básica... 5 Expandiendo la configuración

15 Chapter 1. Que es Smarty? Smarty es un motor de plantillas para PHP. Mas especificamente, esta herramienta facilita la manera de separar la aplicación lógica y el contenido en la presentación. La mejor descripción esta en una situación donde la aplicación del programador y la plantilla del diseñador juegan diferentes roles, o en la mayoria de los casos no la misma persona. Por ejemplo: Digamos que usted crea una pagina web, es decir, despliega el articulo de un diario. El encabezado del articulo, el rotulo, el autor y el cuerpo son elementos del contenido, estos no contiene información de como quieren ser presentados. Estos son pasados por la aplicación Smarty, donde el diseñador edita la plantilla, y usa una combinación de etiquetas HTML y etiquetas de plantilla para formatear la presentación de estos elementos (HTML, tablas, color de fondo, tamaño de letras, hojas de estilo, etc...). Un día el programador necesita cambiar la manera de recuperar el contenido del articulo(un cambio en la aplicación lógica.). Este cambio no afectara al diseñador de la plantilla, el contenido llegara a la plantilla exactamente igual. De la misma manera, si el diseñador de la plantilla quiere rediseñarla en su totalidad, estos cambios no afectaran la aplicación lógica. Por lo tanto, el programador puede hacer cambios en la aplicación lógica sin que sea necesario restructurar la plantilla. Y el diseñador de la plantilla puede hacer cambios sin que haya rompimiento con la aplicación lógica. One design goal of Smarty is the separation of business logic and presentation logic. This means templates can certainly contain logic under the condition that it is for presentation only. Things such as including other templates, altering table row colors, upper-casing a variable, looping over an array of data and displaying it, etc. are all examples of presentation logic. This does not mean that Smarty forces a separation of business and presentation logic. Smarty has no knowledge of which is which, so placing business logic in the template is your own doing. Also, if you desire no logic in your templates you certainly can do so by boiling the content down to text and variables only. Ahora un pequeño resumen sobre que no hace Smarty. Smarty no intenta separar completamente la lógica de la plantilla. No hay problema entre la lógica y su plantilla bajo la condición que esta lógica sea estrictamente para presentación. Un consejo: mantener la aplicación lógica fuera de la plantilla, y la presentación fuera de la aplicación lógica. Esto tiene como finalidad tener un objeto mas manipulable y escalable para un futuro proximo. Un único aspecto acerca de Smarty es la compilación de la plantilla. De esta manera Smarty lee la plantilla y crea los scripts de PHP. Una vez creados, son executados sobre él. Por consiguiente no existe ningún costo por analizar gramaticalmente cada archivo de template por cada requisición, y cada template puede llevar toda la ventaja del compilador de cache de PHP tal como Zend Accelerator ( o PHP Accelerator ( Algunas de las características de Smarty: Es extremamente rápido. Es eficiente ya que puede interpretar el trabajo mas sucio. No analiza gramaticalmente desde arriba el template, solo compila una vez. El esta atento para solo recompilar los archivos de plantilla que fueron cambiados. Usted puede crear funciones habituales y modificadores de variables customizados, de modo que el lenguaje de la platilla es altamente extensible. Sintaxis de etiquetas delimitadoras para configuración de la plantilla, así lo puede usar {}, {{}}, <!-- {}-->, etc. 3

16 Que es Smarty? Los construtoress if/elseif/else/endif son pasados por el interpretador de PHP, así la sintaxis de la expresión {if...} puede ser compleja o simple de la forma que usted quiera. Permite un anidamiento ilimitado de sections, ifs, etc. Es posible incrustar directamente codigo PHP en los archivos de plantilla, aunque esto puede no ser necesario(no recomendado) dado que la herramienta se puede ajustar. Soporte de caching incrustado Fuentes de Plantilla absoluto Funciones habituales de manipulación de cache Arquitectura de Plugin 4

17 Chapter 2. Instalación Requerimentos Smarty Requiere un servidor web corriendo PHP o posterior. Instalación Básica Instale los archivos de la libreria de Smarty que estan en el directorio de distribución /libs/. Estos son los archivos PHP que usted NO EDITARA. Estos archivos son toda las aplicaciones comunes y ellos son actualizados cuando usted actualiza a una nueva versión de Smarty. Example 2.1. Archivos de la libreria Smarty Smarty.class.php Smarty_Compiler.class.php Config_File.class.php debug.tpl /internals/*.php (all of them) /plugins/*.php (all of them) Smarty utiliza una constante de PHP llamada SMARTY_DIR que es la ruta para el directorio de la biblioteca de Smarty 'libs/'. Basicamente, si su aplicación puede encontrar el archivo Smarty.class.php, usted no necesita definir SMARTY_DIR, Smarty lo encontrará. Por consiguiente si, Smarty.class.php no esta incluido en el path, y no es abastecido por una ruta absoluta para encontrar su aplicación, entonces usted debe definir SMARTY_DIR manualmente. SMARTY_DIR debe incluir una barra de seguimento. Aquí esta un ejemplo de como se crea una instancia de Smarty en sus scripts PHP: Example 2.2. Creando una instancia Smarty de Smarty require('smarty.class.php'); $smarty = new Smarty; Intente correr el script de arriba. Si usted obtiene un error diciendo que el archivo Smarty.class.php no fue encontrado, puedes usar una de las siguientes opciones: 5

18 Instalación Example 2.3. Reemplazar por la ruta absulta de la libreria del archivo require('/usr/local/lib/php/smarty/smarty.class.php'); $smarty = new Smarty; Example 2.4. Adicionar el directorio de la libreria para incluirlo en el include_path de PHP // Edite su archivo php.ini, y adicione el directorio de la libreria de Smarty // include_path y reinicie su servidor web. // Entonces lo siguiente debe funcionar: require('smarty.class.php'); $smarty = new Smarty; Example 2.5. Defina la constante SMARTY_DIR manualmente define('smarty_dir', '/usr/local/lib/php/smarty/'); require(smarty_dir. 'Smarty.class.php'); $smarty = new Smarty; Ahora que la libreria de archivos esta en su sitio, es tiempo de configurar los directorios de Smarty para su aplicación. Smarty require cuatro directorios (por defaul) llamados 'templates/', 'templates_c/', 'configs/' y 'cache/'. Cada uno de estos son para definir las propiedades de las clases de Smarty. $template_dir, $compile_dir, $config_dir, y $cache_dir respectivamente. Es altamente recomendado que usted configure un grupo separado de estos directorios para cada aplicación que utilice de Smarty. Asegurece que usted sabe la ubicación del document root de su servidor web. En nuestro ejemplo, el document root esta en /web/ Los directorios de Smarty solo son accesados por la libreria de Smarty y nunca son accesados directamente por el navegador. Por consiguiente para evitar cualquier preocupación con la seguridad, es recomendado colocar estos directorios fuera del document root. 6

19 Instalación Para nuestro ejemplo de instalación, configuraremos el ambiente de Smarty para una aplicación de libro de visitas. Escojemos una aplicación solo con el proposito de crear un directorio de nombre convencional. Usted puede usar el mismo ambiente para cualquier aplicación, solamente sustituya "guestbook" con el nombre de su aplicación. Nosotros colocaremos nuestros directorios de Smarty dentro de /web/ Usted necesita tener por lo menos un archivo dentro de su document root, y que sea accesado por el navegador. Nosotros llamamos el script de 'index.php', y lo colocamos en un subdirectorio dentro del document root llamado /guestbook/. Nota Técnica: Es conveniente configurar el servidor de forma que "index.php" pueda ser identificado como el índice del directório padre, de esta manera si usted accesa el script index.php será ejecutado sin "index.php" ni la URL. En Apache usted puede definir el sitio adicionando "index.php" en el final de su configuración del directorio DirectoryIndex (separando cada uno con espacios.) como en el ejemplo de httpd.conf. DirectoryIndex index.htm index.html index.php index.php3 default.html index.cgi Veamos nuestra estructura de archivos hasta hora: Example 2.6. Ejemplo de estrutura de archivo /usr/local/lib/php/smarty/smarty.class.php /usr/local/lib/php/smarty/smarty_compiler.class.php /usr/local/lib/php/smarty/config_file.class.php /usr/local/lib/php/smarty/debug.tpl /usr/local/lib/php/smarty/internals/*.php /usr/local/lib/php/smarty/plugins/*.php /web/ /web/ /web/ /web/ /web/ Smarty necesitara permisos de escritura (usuarios de windows ingnorar) para $compile_dir y $cache_dir, esto garantiza que el usuario del servidor pueda escribir en ellos. Este es generalmente el usuarios "nobody" y el grupo "nobody". Para usuarios con X sistema operativo, el default es "www" y el grupo "www". Si usted esta usando Apache, puede ver en su archivo httpd.conf (normalmente en "/usr/local/apache/conf/") cual es el usuario y grupo que estan siendo usados. 7

20 Instalación Example 2.7. Configurando permisos de archivos chown nobody:nobody /web/ chmod 770 /web/ chown nobody:nobody /web/ chmod 770 /web/ Nota Técnica: chmod 770 puede ser una seguridad bastante fuerte, solo le permite al usuario "nobody" y al grupo "nobody" acesso de lectura/escritura a los directorios. Si usted quiere abrir permiso de lectura a cualquiera (en la mayoria de las veces para su propia conveniencia de querer ver estos archivos), usted puede usar el 775 en lugar del 770. Nosotros necesitamos crear el archivo index.tpl, para que Smarty lo pueda cargar. Este estara localizado en su $template_dir. Example 2.8. Editando /web/ index.tpl {* Smarty *} Hello, {$name}! Nota Técnica: {* Smarty *} Esto es un comentario en el template. Este no es obligatorio, pero si una buena practica iniciar todos sus archivos de plantilla con estos comentarios. Esto hace facilmente reconocibles a los archivos a pesar la extención del archivo. Por ejemplo, editores de texto pueden reconocer el archivo y habilitar un realce de sintaxis especial. Ahora vamos a editar el index.php. crearemos una instancia de Smarty, daremos valor a las variables del template y mostraremos el archivo index.tpl. En el ambiente de nuestro ejemplo, "/usr/local/lib/php/ Smarty" esta dentro de include_path. Asegurese que exista el mismo, o utilice la ruta absoluta. 8

21 Instalación Example 2.9. Editando /web/ // load Smarty library require('smarty.class.php'); $smarty = new Smarty; $smarty->template_dir = '/web/ $smarty->compile_dir = '/web/ $smarty->config_dir = '/web/ $smarty->cache_dir = '/web/ $smarty->assign('name','ned'); $smarty->display('index.tpl'); Nota Técnica: En nuestro ejemplo, estamos configurando rutas absolutas para todos los directorios de Smarty. Si /web/ está dentro de su include_path de PHP, entonces estas declaraciones no son necesarias. Sin embargo, esto es mas eficiente y (por experiencia) tiene menos tendencia a errores en relación a determinar las rutas absolutas. Esto garantiza que Smarty esta recibiendo los archivos del directorio que usted desea. Ahora carge el archivo index.php desde su navegador web. Usted debera ver "Hello, Ned!" Usted a completado la configuracion basica para el Smarty! Expandiendo la configuración Esta es una continuación de la instalación básica, por favor lea esta primero! Una forma un poco mas flexible de configurar el Smarty, expandir las clases e iniciar su ambiente de Smarty. Es, en vez de configurar rutas de directorios repetidamente, asigne esas mismas a variables, etc., nosotros podemos facilitar eso. Vamos a crear un nuevo directorio en "/php/includes/guestbook/" y llamemos al nuevo archivo setup.php. En nuestro ejemplo, "/php/includes" está en nuestro include_path. Verifique que usted también lo definio, o utilice rutas absolutas de los archivos. 9

22 Instalación Example Editando /php/includes/guestbook/setup.php // load Smarty library require('smarty.class.php'); // The setup.php file is a good place to load // required application library files, and you // can do that right here. An example: // require('guestbook/guestbook.lib.php'); class Smarty_GuestBook extends Smarty { function Smarty_GuestBook() { // Class Constructor. // These automatically get set with each new instance. $this->smarty(); $this->compile_dir = '/web/ $this->template_dir = '/web/ $this->config_dir = '/web/ $this->cache_dir = '/web/ } $this->caching = true; $this->assign('app_name', 'Guest Book'); } Ahora vamos a modificar el archivo index.php para usar el setup.php: 10

23 Instalación Example Editando /web/ require('guestbook/setup.php'); $smarty = new Smarty_GuestBook; $smarty->assign('name','ned'); $smarty->display('index.tpl'); Ahora usted vera que es completamente simple crear una instancia de Smarty, solo use Smarty_GuestBook, que automáticamente inicializa todo para nuestra aplicación. 11

24 Part II. Smarty For Template Designers

25 Table of Contents 3. Basic Syntax Comentarios Variables Funciones Atributos Colocando variables entre comillas dobles Matemáticas Escaping Smarty Parsing Variables Variables definidas desde PHP Arreglos asociativos Índices de Matrices Objects Variables cargadas desde archivos de configuración La variable reservada {$smarty} Solicitud de Variables {$smarty.now} {$smarty.const} {$smarty.capture} {$smarty.config} {$smarty.section}, {$smarty.foreach} {$smarty.template} {$smarty.version} {$smarty.ldelim}, {$smarty.rdelim} Modificadores de variables capitalize cat count_characters count_paragraphs count_sentences count_words date_format default escape indent lower nl2br regex_replace replace spacify string_format strip strip_tags truncate upper wordwrap Combinando Modificadores Funciones Integradas capture config_load {foreach},{foreachelse}

26 Smarty For Template Designers iteration first last show total include {include_php} insert if,elseif,else {ldelim},{rdelim} literal {php} section,sectionelse index index_prev index_next iteration first last rownum loop show total {strip} Custom Functions {assign} {counter} cycle {debug} {eval} {fetch} {html_checkboxes} {html_image} {html_options} {html_radios} {html_select_date} {html_select_time} {html_table} math {mailto} {popup_init} popup {textformat} Config Files Debugging Console

27 Chapter 3. Basic Syntax Todas las etiquetas del template deben estar marcadas por delimitadores. Por default, estos delimitadores son { y }, sino estos pueden cambiar. Para estos ejemplos, nosotros asumiremos que usted está usando los delimitadores por default. En Smarty, todo el contenido fuera de los delimitadores es mostrado como contenido estatico, o igual(sin cambios). Cuando Smarty encuentra etiquetas en el template, trata de interpretarlos, e intenta mostrar la salida apropiada en su lugar. Comentarios Los comentarios en los templates son cercados por asteriscos, y por los delimitadores, así: {* este es un comentario *}. Los comentarios en Smarty no son mostrados en la salida final del template. semejantes a <!-- HTML comments --> Estos son usados para hacer notas internas dentro del template. Example 3.1. Comentarios <body> {* this multiline comment is not sent to browser *} {* include the header file here *} {include file="header.tpl"} {* Dev note: $includefile is assigned foo.php script *} <!-- this html comment is sent to browser --> {include file=$includefile} {include file=#includefile#} {* display dropdown lists *} <select name="company"> {html_options options=$vals selected=$selected_id} </select> </body> Variables Las variable de Template que comiencen con signo de pesos. Pueden contener números, letras y guiones bajos, muy parecido a las variables de PHP [ Usted también puede hacer referencia a arreglos que puden ser numericos o no-numericos. También puede hacer referencia a métodos y propiedades de objetos. Config file variables es una excepción de la sintaxis del signo de pesos. También puede ser referenciado entre #signos de numeros#, o con la variable especial $smarty.config. 15

28 Basic Syntax Example 3.2. Variables {$foo} <-- displaying a simple variable (non array/object) {$foo[4]} <-- display the 5th element of a zero-indexed array {$foo.bar} <-- display the "bar" key value of an array, similar to PHP $foo['bar {$foo.$bar} <-- display variable key value of an array, similar to PHP $foo[$bar] {$foo->bar} <-- display the object property "bar" {$foo->bar()} <-- display the return value of object method "bar" {#foo#} <-- display the config file variable "foo" {$smarty.config.foo} <-- synonym for {#foo#} {$foo[bar]} <-- syntax only valid in a section loop, see {section} {assign var=foo value="baa"}{$foo} <-- displays "baa", see {assign} Many other combinations are allowed {$foo.bar.baz} {$foo.$bar.$baz} {$foo[4].baz} {$foo[4].$baz} {$foo.bar.baz[4]} {$foo->bar($baz,2,$bar)} <-- passing parameters {"foo"} <-- static values are allowed Vea también $smarty reserved variables y Config Variables. Funciones Cada etiqueta Smarty muestra una variable o utiliza algún tipo de función. Las funciones son procesadas y mostradas colocando los atributos de la función entre delimitadores, así: {funcname attr1="val" attr2="val"}. Example 3.3. Sintaxis de Funciones {config_load file="colors.conf"} {include file="header.tpl"} {if $highlight_name} Welcome, <font color="{#fontcolor#}">{$name}!</font> {else} Welcome, {$name}! {/if} {include file="footer.tpl"} 16

29 Basic Syntax Las funciones internas y las funciones habituales, ambas deben tener la misma sintaxis dentro del template. Las funciones internas que funcionan en Smarty, son: {if}, {section} y {strip}. Estas no pueden ser modificadas. Las funciones habituales son funciones adicionales implementadas por plugins. Estas si pueden ser modificadas como usted quiera, o usted también puede adicionar nuevas. {html_options} y {popup} son ejemplos de funciones habituales. Atributos La mayoria de las funciones llevan atributos que especifican o cambian su funcionamiento. Los atributos para las funciones de Smarty son muy parecidos a los atributos de HTML. Los valores estaticos no necesitan estar entre comillas, pero si es recomendado para cadenas y literales. Las variables también pueden ser usadas y no precisamente estando entre comillas. Algunos atributos requieren valores boleanos(true o false). Estos pueden ser especificados como cualquier otro valor sin comillas true, on, y yes, o false, off, y no. Example 3.4. Sintaxis de atributos de Funciones {include file="header.tpl"} {include file="header.tpl" attrib_name="attrib value"} {include file=$includefile} {include file=#includefile# title="smarty is cool"} {html_select_date display_days=yes} <select name="company"> {html_options options=$choices selected=$selected} </select> Colocando variables entre comillas dobles Smarty puede reconocer variables asignadas entre comillas aunque estas solo tengan números, letras, guiones bajos y corchetes[]. Con cualquier otro carácter(puntos, referencia de objetos, etc.) las variables deben estar entre apostrofos. Usted no puede incrustar modificadores, Estos deben ser siempre aplicados fuera de las comillas. 17

30 Basic Syntax Example 3.5. Sintaxis entre comillas SYNTAX EXAMPLES: {func var="test $foo test"} <-- sees $foo {func var="test $foo_bar test"} <-- sees $foo_bar {func var="test $foo[0] test"} <-- sees $foo[0] {func var="test $foo[bar] test"} <-- sees $foo[bar] {func var="test $foo.bar test"} <-- sees $foo (not $foo.bar) {func var="test `$foo.bar` test"} <-- sees $foo.bar {func var="test `$foo.bar` test" escape} <-- modifiers outside quotes! PRACTICAL EXAMPLES: {include file="subdir/$tpl_name.tpl"} <-- will replace $tpl_name with value {cycle values="one,two,`$smarty.config.myval`"} <-- must have backticks Ver también escape. Matemáticas Las matemáticas pueden ser aplicadas directamente al los valores de las variables. Example 3.6. Ejemplos de matemáticas {$foo+1} {$foo*$bar} {* some more complicated examples *} {$foo->bar-$bar[1]*$baz->foo->bar()-3*7} {if ($foo+$bar.test%$baz* $b+10)} {$foo truncate:"`$footrunccount/$bartruncfactor-1`"} {assign var="foo" value="`$foo+$bar`"} Ver también la función{math}. Escaping Smarty Parsing En algunas ocaciones es deseable o hasta necesario que Smarty tenga que ingonar sections o algun otro tipo analisis de sintaxis. Un ejemplo clasico es con el codigo JavaScript o CSS incrustado en el template. El problema se origina cuando aquellos lenguajes que utilizan los caracteres { y } los cuales son también los delimitadores por default para Smarty. 18

31 Basic Syntax Esta puede ser una simple situación separando enteramente su codigo JavaScript y CSS dentro de un archivo personal y utilizar el metodo standar del HTML para el acceso. Es posible usar literal incluyendo el contenido del bloque {literal}.. {/literal}. Similar a usar entidades HTML, usted puede usar {ldelim},{rdelim} o {$smarty.ldelim} para mostrar los delimitadores actuales. Esto a menudo es conveniente para cambios simples a Smarty's $left_delimiter y $right_delimiter. Example 3.7. Ejemplo cambiando delimitadores $smarty = new Smarty; $smarty->left_delimiter = '<!--{'; $smarty->right_delimiter = '}-->'; $smarty->assign('foo', 'bar'); $smarty->display('example.tpl'); Donde example.tpl es: <script language="javascript"> var foo = <!--{$foo}-->; function dosomething() { alert("foo is " + foo); } dosomething(); </script> Ver También escape modifier 19

32 Chapter 4. Variables Smarty tiene varios tipos diferentes de variables. El tipo de variable depende de cual simbolo este prefijado(incluido dentro). Las variables de Smarty no pueden ser mostradas directamente o usadas como argumentos para atributos, funciones y modificadores, dentro de expresiones condicionales, etc. Para mostrar una variable, simplesmente coloque esta entre delimitadores siendo esta la única cosa entre ellos. Ejemplos: {$Name} {$Contacts[row].Phone} <body bgcolor="{#bgcolor#}"> Variables definidas desde PHP Las variables que son asignadas desde PHP son referenciadas precedidas estas con una señal de cifrado $. Las variables definidas dentro del template como una función assign también son mostradas de esta manera. 20

33 Variables Example 4.1. variables definidas php script $smarty = new Smarty; $smarty->assign('firstname', 'Doug'); $smarty->assign('lastname', 'Evans'); $smarty->assign('meetingplace', 'New York'); $smarty->display('index.tpl'); Donde el contenido de index.tpl es: Hello {$firstname} {$lastname}, glad to see you can make it. <br /> {* this will not work as $vars are case sensitive *} This weeks meeting is in {$meetingplace}. {* this will work *} This weeks meeting is in {$meetingplace}. esta es la salida: Hello Doug Evans, glad to see you can make it. <br /> This weeks meeting is in. This weeks meeting is in New York. Arreglos asociativos Usted también puede referenciar matrices asociativas en variables que son definidas desde PHP especificando la clave después del simbolo '.'(punto). 21

34 Variables Example 4.2. Accesando variables de matriz asociativa $smarty->assign('contacts', array('fax' => ' ', ' ' => 'phone' => array('home' => ' ', 'cell' => ' ') ) ); $smarty->display('index.tpl'); Donde el contenido de index.tpl es: {$Contacts.fax}<br /> {$Contacts. }<br /> {* you can print arrays of arrays as well *} {$Contacts.phone.home}<br /> {$Contacts.phone.cell}<br /> esta es la salida: <br /> zaphod@slartibartfast.com<br /> <br /> <br /> Índices de Matrices Usted podra referencia matrizes por su índice, muy semejantes a la sintaxis de PHP. 22

35 Variables Example 4.3. Accesando matrices por sus índices $smarty->assign('contacts', array( ' ', array(' ', ' ') )); $smarty->display('index.tpl'); Donde index.tpl es: {$Contacts[0]}<br /> {$Contacts[1]}<br /> {* you can print arrays of arrays as well *} {$Contacts[2][0]}<br /> {$Contacts[2][1]}<br /> esta es la salida: <br /> /> <br /> <br /> Objects Las propiedades de los objetos definidos desde PHP pueden ser referenciados especificando el nombre de la propiedad después del simbolo '->'. 23

36 Variables Example 4.4. Accesando propiedades de los Objetos name: {$person->name}<br /> {$person-> }<br /> esta es la salida: name: Zaphod Beeblebrox<br /> /> Variables cargadas desde archivos de configuración Las variables que son cargadas de archivos de configuración son referenciadas incluyendo entre ellas el signo(#), o como variables de Smarty $smarty.config. La segunda sintaxis es util para incrustar valores de un atributo dentro de comillas. 24

37 Variables Example foo.conf: 4.5. Variables de configuración pagetitle = "This is mine" bodybgcolor = "#eeeeee" tablebordersize = "3" tablebgcolor = "#bbbbbb" rowbgcolor = "#cccccc" index.tpl: {config_load file="foo.conf"} <html> <title>{#pagetitle#}</title> <body bgcolor="{#bodybgcolor#}"> <table border="{#tablebordersize#}" bgcolor="{#tablebgcolor#}"> <tr bgcolor="{#rowbgcolor#}"> <td>first</td> <td>last</td> <td>address</td> </tr> </table> </body> </html> index.tpl: (sintaxis alternativa) {config_load file="foo.conf"} <html> <title>{$smarty.config.pagetitle}</title> <body bgcolor="{$smarty.config.bodybgcolor}"> <table border="{$smarty.config.tablebordersize}" bgcolor="{$smarty.config.tablebgco <tr bgcolor="{$smarty.config.rowbgcolor}"> <td>first</td> <td>last</td> <td>address</td> </tr> </table> </body> </html> esta es la salida de ambos ejemplos: <html> <title>this is mine</title> <body bgcolor="#eeeeee"> <table border="3" bgcolor="#bbbbbb"> <tr bgcolor="#cccccc"> <td>first</td> <td>last</td> <td>address</td> </tr> </table> </body> </html> 25

38 Variables Las variables de un archivo de configuración no pueden ser usadas hasta después de que son cargadas por los archivos de configuración. Este procedimento es explicado posteriormente en este documento en {config_load}. Ver también Variables y $smarty reserved variables La variable reservada {$smarty} La variable reservada {$smarty} puede ser utilizada para accesar a variables especiales del template. A continuación una lista completa. Solicitud de Variables La solicitud de variables [ como $_GET, $_POST, $_COOKIE, $_SERVER, $_ENV y $_SESSION (Ver $request_vars_order y $request_use_auto_globals) pueden ser accesadas como se muestra en los ejemplos de abajo: Example 4.6. Mostrando solicitud de variables {* display value of page from URL (GET) *} {$smarty.get.page} {* display the variable "page" from a form (POST) *} {$smarty.post.page} {* display the value of the cookie "username" *} {$smarty.cookies.username} {* display the server variable "SERVER_NAME" *} {$smarty.server.server_name} {* display the system environment variable "PATH" *} {$smarty.env.path} {* display the php session variable "id" *} {$smarty.session.id} {* display the variable "username" from merged get/post/cookies/server/env *} {$smarty.request.username} Note {$smarty.now} Por historicas razones {$SCRIPT_NAME} puede ser accesado directamente sin embargo {$smarty.server.script_name} es el sugerido para accesar este valor. El timestamp [ actual puede ser accesado con {$smarty.now}. El número refleja el número de segundos pasados desde la llamada Epoca (1 de Enero de 1970) y puede ser pasado directamente para el modificador date_format para mostrar la fecha. 26

39 Variables Example 4.7. Usando {$smarty.now} {* utilice el modificador date_format para mostrar la fecha y hora actual *} {$smarty.now date_format:"%y-%m-%d %H:%M:%S"} {$smarty.const} Usted puede accesar al valor de constantes PHP directamente. Ver también smarty constants Example 4.8. Usando {$smarty.const} {$smarty.const._my_const_val} {$smarty.capture} La salida capturada via {capture}..{/capture} puede ser accesada usando la variable {$smarty}. vea la sección {capture} para un ejemplo. {$smarty.config} La variable {$smarty} puede ser usada para referir variables de configuración cargadas. {$smarty.config.foo} es un sinónimo para {#foo#}. vea la sección sobre {config_load} para un ejemplo. {$smarty.section}, {$smarty.foreach} La variable {$smarty} puede ser usada para hacer referencia a las propiedades 'section' y 'foreach' del loop. Ver la documentación sobre section y foreach. {$smarty.template} Esta variable contiene el nombre actual del template que esta siendo procesado. {$smarty.version} Esta variable contiene la versión Smarty con que es compilado el template. {$smarty.ldelim}, {$smarty.rdelim} Esta variable es usada para imprimir literalmente el valor left-delimiter y right-delimiter. Ver tambien {ldelim},{rdelim}. Ver también Variables y Config Variables 27

40 Chapter 5. Modificadores de variables Los modificadores de variables pueden ser aplicados a variables, funciones habituales o cadenas. Para aplicar un modificador, especifique el valor seguido por (pipe) y el nombre del modificador. Un modificador necesita parámetros adicionales que afetan en su funcionamento. Estos parámetros siguen al nombre del modificador y son separados por : (dos puntos). Example 5.1. Ejemplo de modificador {* apply modifier to a variable *} {$title upper} {* modifier with parameters *} {$title truncate:40:"..."} {* apply modifier to a function parameter *} {html_table loop=$myvar upper} {* with parameters *} {html_table loop=$myvar truncate:40:"..."} {* apply modifier to literal string *} {"foobar" upper} {* using date_format to format the current date *} {$smarty.now date_format:"%y/%m/%d"} {* apply modifier to a custom function *} {mailto upper address="me@domain.dom"} Si usted aplica un modificador a una matriz en lugar del valor de una variable, el modificador va a ser aplicado en cada uno de los valores de la matriz. Si usted realmente quisiera que el modificador funcionara en una matriz entera, debe colocar el antes del nombre del modificador, así como: (esto mostrara el número de elementos de la matriz $articletitle.) Los modificadores pueden ser cargados automáticamente a partir de su $plugins_dir (vea también: Naming Conventions) o pueden ser registrados explicitamente (vea: register_modifier). Adicionalmente, todas las funciones de php pueden ser utilizadas como modificadores implicitamente. (El de arriba usa actualmente la función count de php y no un modificador de Smarty). Usar funciones de php como modificadores tiene dos pequeños problemas: Primero, algunas veces al ordenar los parámetros de una función esto no es aconsejable ({"%2.f" sprintf:$float} actualmente funciona, pero existe algo mas intuitivo Por ejemplo: {$float string_format:"%2.f"} que es proporcionado con la distribución de Smarty). Segundo: con $security activado, todas las funciones de php que sean utilizadas como modificadores deben ser declaradas como variables de una matriz $security_settings['modifier_funcs']. Ver también register_modifier(), register_function(), Extending Smarty with plugins y modifiers, 28

41 Modificadores de variables capitalize Posicion del Parametro Tipo Requerido Default Descripción 1 boolean No false Este determina que palabra con digitos no debe ser convertida Este es usado para convertir a mayuscula la primera letra de todas la palabras de una variable. Example 5.2. capitalize $smarty->assign('articletitle', 'next x-men film, x3, delayed.'); Donde el template es: {$articletitle} {$articletitle capitalize} {$articletitle capitalize:true} Esta es la salida: next x-men film, x3, delayed. Next X-Men Film, x3, Delayed. Next X-Men Film, X3, Delayed. cat Ver también lower upper Posiscion del Parametro Tipo Requerido cat Descripción 1 string No empty Este es el valor para concatenar con la variable dada. 29