Free Marker

CERVANTESFormación

FreemarkerFreemarker.sxwVersión 1.0Revisión: 1

Emitido por: NHT-Norwick Fecha : 07/07/2003

CONTROL DE ACTUALIZACIONES

VERSIÓN 1.

FECHA

HOJA RESUMEN DE MODIFICACIONES

VERSIÓN: 1.0

APARTADO CAMBIOS SOBRE VERSIÓN ANTERIOR

1 / 15

VERSIÓN FECHA ELABORADO REVISADO APROBADO1 18/09/03 Joel Gonçalves Alberto Molpeceres Alberto Molpeceres

Copyright (c) 2003, New High Technologies of Norwick S.L. . Estedocumento puede ser distribuido solo bajo los términos y condiciones de lalicencia de Documentación de javaHispano v1.0 o posterior (la última versiónse encuentra en http://www.javahispano.org/licencias/).

CERVANTESFormaciónFreemarker

Freemarker.sxwVersión: 1.0


INDICE

Control de actualizaciones...........................................................................................................................1

CERVANTES.......................................................................................................................................................1

Hoja Resumen de modificaciones.................................................................................................................1INDICE...............................................................................................................................................................2

CERVANTES.......................................................................................................................................................2

1. INTRODUCCIÓN................................................................................................................................................32. MODELO DE DATOS..........................................................................................................................................43. PLANTILLAS....................................................................................................................................................64. INTERPOLACIONES............................................................................................................................................75. DIRECTIVAS (ETIQUETAS FTL)..........................................................................................................................8

Directivas predefinidas.........................................................................................................................9assign:................................................................................................................................................9if, elseif, else:....................................................................................................................................9list, break:........................................................................................................................................10

Built-in.........................................................................................................................................................11built-in para Cadenas de texto...........................................................................................................11built-in para números.........................................................................................................................12built-in para fechas y horas................................................................................................................13built-in para variables no definidas...................................................................................................13

REFERENCIAS............................................................................................................................................15

FreemarkerFecha: 16/09/2003

2 / 15 Freemarker.sxwVersión: 1.0




1. INTRODUCCIÓN

Todos estamos de acuerdo en que el perfil de un diseñador/maquetador (media) y unprogramador (procesos) son perfiles totalmente independientes. Sin embargo, con la metodologíaactual, en muchas ocasiones un maquetador tiene que trabajar sobre páginas llenas de código Java;y, a su vez, muchas veces un programador tiene que retocar código HTML, con el riesgo que estosupone en ambos casos.

Por lo tanto, tenemos la necesidad de separar al máximo grado posible el diseño y la maquetaciónde la programación, y esto se consigue utilizando un motor de plantillas. Un motor de plantillases una librería que permite separar los datos de la presentación, lo que en nuestro entorno webequivale a separar la programación Java del código HTML.

Freemarker es un motor de plantillas que se adapta muy bien a las necesidades que tenemos, yserá el que usaremos a partir de ahora en nuestros proyectos.

Como en todo motor de plantillas, en Freemarker nos encontramos con 2 elementos principales:las plantillas y el modelo de datos. La labor de Freemaker es juntar estos dos elementos paraenviar código HTML al navegador.

La principal ventaja de este sistema es que la plantilla llevará sólo la programación mínimanecesaria para hacerla dinámica, dejando todo el peso de la programación fuera de la plantilla.

Esta guía intenta explicar las nociones básicas necesarias para el uso de freemarker por parte delequipo de desarrollo.






2. MODELO DE DATOS

Podemos imaginarnos el modelo de datos como un diagrama de árbol, donde los elementos estánordenados jeráquicamente.

(root) | +- animales | | | +- ratón | | | | | +- tamaño = "pequeño" | | | | | +- precio = 50 | | | +- elefante | | | | | +- tamaño = "grande" | | | | | +- precio = 5000 | | | +- pitón | | | +- tamaño = "medio" | | | +- precio = 4999 | +- test = "Esto es un test" | +- queno | + causa = "no sé"

Existen 5 tipos de elementos en un modelo de datos, puediendo un elemento pertenecer a másde un tipo a la vez. Los tipos de elementos son los siguientes:

• Escalares (scalars): Son los elementos que guardan un valor simple. En el ejemplo, tamaño, precio,test y causa son elementos escalares. Los valores simples pueden ser de lossiguientes tipos:

• String: cadenas de texto que deben ir entre comillas, dobles osimples.

• Number: números positivos, negativos o decimales. El separadordecimal es el punto






• Date: fechas y horas.• Booleanos: representan los valores verdadero o falso, por lo que

solo pueden valer o true o false.

• Mapas de valores (hashes):Son contenedores de otros elementos, semejante a los directorios. Loselementos que contienen tienen que tener un nombre único dentro de su nivel dejerarquía para diferenciarlo de sus hermanos. En el ejemplo, animales, ratón,elefante, pitón y queno son elementos hashes. Para movernos por los hasheslos haremos con el punto. Así, si en el ejemplo queremos obtener el precio delratón accederíamos así: animales.ratón.precio.

• Listas (sequences):Son contenedores de otros elementos. Por lo general se usan para agruparelementos de una misma categoría, pudiendo acceder a ellos por la posición queocupan dentro de la secuencia, ocupando el primer elemento la posición 0. En elejemplo animales , ratón, elefnte, pitón y queno son elementos de tiposecuencia. Como ya hemos dicho, un elemento puede ser de varios tipos, y esoes lo que ocurre, por ejemplo, con animales, que es de tipo secuencia y de tipohashes a la vez. Para movernos por las secuencias los podemos hacer por suposicion. Por ejemplo, para acceder al ratón accederíamos así: animales[0].

• Métodos:Son los elementos que calculan algo en función de un parámetro que lepasamos, y devulven un elemento. No están representados en el ejemplo. Nose recomienda usarlos en la parte de la presentación, excepto los que manejanla presentacion (Por ejemplo String.trim()), ya que estaríamos realizando enparte algo que queremos evitar: mezclar la lógica con la presentación.Por lotanto no los explciaremos en esta guía.

• Etiquetas definidas por el usuario:Son elementos definidos por el usuario, como pueden ser las macros. No lostrataremos en esta guía, por estar enfocada a programadores, estándo lasmacros destinadas a facilitar el trabajo de los maquetadores. Podeis consultarmás sobre ellos en el manual oficial de freemarker, que podeis encontrar en supágina web.






3. PLANTILLAS

Las plantillas son las páginas con el código HTML, pero que contienen partes de código escritasen lenguaje FTL (FreeMarker Template Language); un lenguaje muy simple que nos permitirátener contenido dinámico.

El lenguaje FTL es case-sensitive, es decir, distingue mayúsculas de minúsculas, y por tanto noes lo mismo list que List. Ignora los espacios superfluos, es decir, que las instrucciones <#ifuser == “Juan”> y <#if user == “Juan” > son idénticas para FreeMarker.Además, las etiquetas deben estar correctamente anidadas.

En una plantilla podemos encontrar los siguientes elementos:• Texto: es el código HTML que será mostrado tal cual, sin hacer nada sobre él. • Interpolaciones: son las secciones del código que serán calculadas por

FreeMarker y reemplazadas por su valor correspondiente, es decir, que seránvisibles por la salida. Están delimitadas por ${ y } o por #{ y }.

• Etiquetas FLT: son etiquetas similares a las de HTML, pero, a diferencia de lasinterporlaciones, no son reemplazadas por ningún valor, sino simplemente soninstrucciones para FreeMarker. Un ejemplo de esto es la etiqueta <#if>, que ensí no es reemplazada por ningún valor, pero modifica el comportamiento deFreemarker.

• Comentarios: delimitados por las etiquetas <#-- y -->

Ejemplo:

<html><head> <title>Welcome!</title></head><body> <#-- Greet the user with his/her name --> <h1>Welcome ${user}!</h1> <p>We have these animals: <ul> <#list animals as being>[BR] <li>${being.name} for ${being.price} Euros </#list> </ul></body></html>



Texto:

Interpolaciones:

Etiquetas FTL:

Comentarios:




4. INTERPOLACIONES

Existen dos formas de escribir interpolaciones:• ${expresion}: para cadenas literales. La cadena se mostrará tal cual. • #{expresion} o #{expresion; formato}: para mostrar números.

Los números también podemos mostrarlos con ${}, pero la forma #{} es mucho más potente, yaque podemos formatear el número para que se muestre con los decimales que deseamos. Estose consigue pasando el parámetro formato, que pueden ser los siguientes:

• Especificar el número de decimales: esto se cosigue pasando la letra mseguido del número de decimales, por ejemplo m1 mostrará el número siemprecon un decimal.

• Especificar el número máximo de decimales, aunque se usará el mínimoposible: para ello pasamos como argumento la letra M y el número dedecimales, por ejemplo M3. Cuando indicamos que muestre un número dedecimales menor del que tiene el número, se mostrará el número redondeado.

• Especificar el número mínimo y máximo de decimales: para ello pasamoslos argumentos m y M, por ejemplo m1M3 indica un mínimo de un decimal y unmáximo de 3.

Ejemplo:

x=2.582 e y=4:

#{x; M2} <#-- 2.58 -->#{y; M2} <#-- 4 -->#{x; m1} <#-- 2.6 -->#{y; m1} <#-- 4.0 -->#{x; m1M2} <#-- 2.58 -->#{y; m1M2} <# 4.0 >






5. DIRECTIVAS (ETIQUETAS FTL)

En FreeMarker se escriben las directivas o instrucciones usando etiquetas FTL. Estas etiquetaspueden ser de 3 tipos:

• Apertura de etiqueta: su sintaxis es <#nombre_de_la_directiva parametros>.

• Cierre de etiqueta: su sintaxis es </#nombre_de_la_directiva>.• Directivas vacias: su sintaxis es <#nombre_de_la_directiva parametros/>.

Estas son las directivas que no tienen contenido entre las etiquetas de aperturay cierre; como ocurre, por ejemplo, con la etiqueta XHTML <img/>.

NOTA: También es posible usar las directivas sin el carácter #, es decir<nombre_de_la_directiva parametros> . Sin embargo, se recomienda usarlopara distinguir mejor las etiquetas FTL y hacer todos un código uniforme. El formatoque incluye el carácter # es el más moderno, y el recomendado por losdesarrolladores en las últimas versiones de la librería.

En cuanto a las directivas, existen 2 tipos principales:

• Directivas predefinidas: son un grupo de directivas que vienen integradas conFreeMarker, y que normalmente nos serán suficientes para programar laplantilla. Comienza con <# y a continuación el nombre de la directiva; porejemplo <#list> .

• Directivas definidas por el usuario: FreeMarker permite crear nuestras propiasdirectivas, y se usarán de la misma forma que las predefinidas, con la únicadiferencia de que en vez de usar el comienzo de etiqueta <# se usa <@ .

Para crear nuestras directivas lo haremos con las macros.Ejemplo:

Este es un ejemplo muy sencillo, pero podemos hacer macros muy potentes. Las macrospermiten recibir parámetros lo que nos permitirá complicar nuestras directivas hasta el grado quequeramos.



<#macro saludo> <span class=”letra01”>Hola!</span></#macro>

<@saludo/> Hola!




Directivas predefinidas

assign:

Esta directiva se utiliza para crear variables o modificar el valor de estas. Esta es su sintaxis: <#assign nombre_variable1=valor nombre_variable2=valor ... />

También podemos asignar a las variables valores de otras variables.

if, elseif, else:

La sentencia condicional que todos los programadores conocen tiene la forma:<#if condicion>

...

<#elseif condicion2>

...

<#else>

...

</#if>



JuanHola Juan!PepeHola Juan!?

<#assign user=”Juan” /> ${user}<#assign saludo=”Hola “+user+”!” /> ${saludo}<#assign user=”Pepe” /> ${user} ${saludo}




list, break:

Podemos realizar iteraciones sobre elementos de tipo secuencia de la forma:

<#list secuencia as elemento>

...

</#list>

Cuando usamos esta etiqueta automáticamente se crean 2 variables:• item_index: contiene el índice del elemento actual, comenzando por el cero.• Item_has_next: es un boolean que devuelve true si el elemento actual no es el último.

NOTA: Para el ejemplo hemos creado la variable seq y la hemos dado un valor.Esto es a modo de ejemplo, porque esta variable y el resto siempre serán creadasen el modelo de datos.



<#assign x=5> <#if x == 1> x es 1<#elseif x == 2> x es 2<#elseif x == 3> x no es ni 1 ni 2<#/if>

<#assign animal=”pato”><#if animal == “perro”> El animal es un perro<#else> No es un perro, es un ${animal}</#if>

<#assign seq = ["winter", "spring", "summer", "autumn"]/>

<#list seq as x> ${x_index + 1}. ${x}<#if x_has_next>,</#if></#list>

1. winter,2. spring,3. summer,4. autumn?

x no es ni 1 ni 2

No es un perro, es unpato




BUILT-IN

Los builtin son comandos que nos permiten formatear la salida de las interpolaciones. Las másimportantes y que más usaremos serán los builtin para:

• Cadenas de texto.• Números.• Fechas y horas.• Variables no definidas.

Para usarlos, se usa el carácter ? y a continuación el nombre del comando.

No explicaremos todos los builtin existentes, simplemetne nos limitaremos a los querecomendamos utilizar para optimizar la separación de lógica y presentación.

built-in para cadenas de texto

- cap_first: convierte el primer carácter (ignora los espacios) en mayúscula.

- uncap_first: convierte el primer carácter (ignora los espacios) en minúscula - capitalize: convierte la primera letra de cada palabra de la cadena en mayúsculas y el

resto en minúsculas.- lower_case: convierte toda la cadena a minúsculas.- upper_case: convierte toda la cadena a mayúsculas.- length: devuelve la longitud de la cadena- trim: elimina los espacios en blanco del principio y del final de la cadena.- index_of: busca la primera aparición de una cadena dentro de otra y devuelve la posición

de la primera ocurrencia. Si no hay ocurrencia devuelve un –1. Ejemplo: "abcabc"?index_of("bc",2) devuelve un 4 (las cadenas empiezan en laposición 0). El segundo parámetro es opcional, e indica a partir de que carácter de lacadena se empieza a buscar. Si no se indica se asume un 0.

- last_index_of: idéntico a index_of, pero en lugar de devolver la posición de la primeraocurrencia, devuelve la posición de la última ocurrencia.

- replace: reemplaza una sub-cadena por otra:



${" green mouse"?cap_first}${"GreEN mouse"?cap_first}${"- green mouse"?cap_first} >

Green mouseGreEN mousegreen mouse

${"coche rojo"?replace("rojo","verde")} coche verde




- html: reemplaza con los códigos HTML los caracteres correspondientes. 1. < son reemplazados por <2. > son reemplazados por >3. & son reemplazados por &4. “ son reemplazados por "

built-in para números

En el apartado interpolaciones vimos que es posible formatear el número de decimales quequeremos mostrar de un número. Los built-in para números nos dan un poco más de flexibilidad ala hora de dar formato a los números. Es importante notar que lo primero que hace el built-in esformatear el número en cadena de texto, por la tanto usaremos las etiquetas ${} para mostrarlosen lugar de #{}.

- currency: muestra el número en el formato de moneda, de acuerdo a la configuraciónlocal de FreeMarker.

Ejemplo, suponiendo que la configuración local está configurada para España:

También podemos cambiar la configuración local:

- definir un formato: podemos definir el formato exacto de salida del número usando lasintaxis de formato para números decimales en Java.



<#assign num=42/>${num}${num?string.currency}

4242,00

<#assign num=42/>${num}${num?string.currency}<#setting locale=”en_US”>${num?string.currency}

4242,00

42.00

${12345678?string(",##0.00")} 12,345,678.00




built-in para fechas y horas

Al igual que ocurre con los built-in para números, cuando los usemos para fechas tambiéndebemos convertirlos a cadenas de texto, string, para poder darles un formato.

Para dar formato a las fechas y horas podemos usar los formatos predefinidos que vienen conFreeMarker o indicar nosotros el formato que queramos.

Es importante saber que las fechas y horas de los formatos predefinidos se mostrarán de acuerdoa la configuración local. Por ejemplo, si la configuración local está para Estados Unidos, elsistema mostraría lo siguiente:

Para indicar nosotros el formato con el que queremos mostrar la información se haría de lasiguiente forma:

Cada letra especifica un campo, por ejemplo la H mayúscula representa las horas. Siescribiremos dos HH indicamos que queremos mostrar las horas con dos dígitos.

built-in para variables no definidas

Si intentamos acceder a una variable que no existe, se genera un error y la página no seprocesa. Con los built-in podremos gestionar este problema de forma muy cómoda:

- default: Define el valor de la variable si no existe.Ejemplo, suponiendo que originalmente la variable user no existe:



<#-- fecha 04/08/2003, hora 21:24:44 -->

${hora?string.short}${hora?string.medium}${hora?string.long}

${fecha?string.short}${fecha?string.medium}${fecha?string.long}

9:24 PM9:24:44 PM9:24:44 PM PDT

4/8/03Apr 8, 2003April 8, 2003

<#-- fecha 04/08/2003, hora 21:24:44 -->

${hora?string(“HH:mm:ss”)}

${fecha?string(“dd/mm/yyyy”)}

21:24:44

04/08/2003




NOTA: No es recomendable usar este built-in, porque va un poco en contrade la filosofía de los motores de plantillas. Lo lógico es que todas lasexcepciones se recojan en la parte de la programación. De este modo,nosotros usaríamos simplemente ${user} y en la parte de la programaciónya se habrán encargado de que la variable valga “Anónimo” o “Juan”.

- exists: Devuelve true si la variable existe o false si no existe.Ejemplo, suponiendo que originalmente la variable user no existe:



<#if user?exists> El usuarios es ${user}<#else> Usuario anónimo</#if>

Usuario anónimo

${user?default(“Anónimo”)}<#assign user=”Juan”>${user?default(“Anónimo”)}

Anónimo

Juan




REFERENCIAS

Freemarker.http://www.freemarker.org



Copyright (c) 2003, New High Technologies of Norwick S.L. . Estedocumento puede ser distribuido solo bajo los términos y condiciones de lalicencia de Documentación de javaHispano v1.0 o posterior (la última versiónse encuentra en http://www.javahispano.org/licencias/).

Free Marker

Documents

Transcript of Free Marker