TemplatePower Manual

Manual de TemplatePower

Translated by:

Eduardo Cuervo Ricardo

Introducción
    ¿Qué es TemplatePower?
    ¿Qué puede hacer TemplatePower?
    ¿Porqué usar TemplatePower?
    Requisitos
    GNU General Public License
Formato de las plantillas
El objeto TemplatePower
Funciones
    assign
    assignGlobal
    assignInclude
    getOutputContent
    getVarValue
    gotoBlock
    newBlock
    prepare
    printToScreen
    serializedBase
    showUnAssigned
    version

¿Qué es TemplatePower?

TemplatePower permite separar el código PHP y la presentación (HTML)en ficheros distintos. Es parecido a la popular clase de plantillas FastTemplate pero mucho más rápida (hasta 6 veces más).

¿Que puede hacer TemplatePower?

TemplatePower 1.6.2 tiene las siguientes características:

- soporte de bloques dinámicos anidados.
- soporte de inclusión de archivos / bloques (nota: el código PHP NO se ejecuta, para eso usar v2.0).
- muestra / oculta las variables no asignadas.

TemplatePower 2.0 incluye además:
- etiqueta ignore.
- etiqueta de inclusión de código PHP, este código será ejecutado.
- asignación global de variables.
- asignación de múltiples variables en una sola sentencia de asignación, utilizando un array asociativo.
- salvar en disco y usar una plantilla previamente analizada.
- etiqueta reuse (en pruebas).

TemplatePower 3.0 incluye además
- plantillas almacenadas en base de datos.

¿Porqué usar TemplatePower?

En primer lugar es gratuito para uso personal (General Public License)!

La razón por la que el autor desarrolló TemplatePower fué porque el uso de FastTemplate no le resultaba suficientemente sencillo. Entonces consideró que podia ser hecho de una forma mas facil, por eso llamó a su proyecto EasyTemplate, pero ese nombre ya estaba siendo usado, por lo que cambió el nombre a TemplatePower.

El resultado es un motor de plantillas que el autor asegura que es mucho mas facil de usar que FastTemplate (N del T. yo no he usado FastTemplate, pero TemplatePower me parece muy facil de usar :-)) y además es mucho más rápido que FastTemplate. Esas son las razones por las que debes usar TemplatePower.

Si encuentras errores en el software rellena el informe que encontrarás aquí.

(N del T. Si encuentras errores en esta traducción puedes enviarmelos a edu arroba cuervo punto as, (antiSpam))

Requisitos

TemplatePower necesita PHP 4.0.1 o superior y funciona en sistemas windows y unix.

GNU General Public License

TemplatePower se distribuye bajo los términos de la Licencia pública GNU. Si deseas vender una aplicación o un sitio desarrollado usando TemplatePower, puedes comprar un 'Certificado de distribución'. Este certificado te permite vender un número de aplicaciones (al menos 5) que usen TemplatePower. Su precio es de númeroDe Aplicaciones x $3 USD.

Index

Formato de las plantillas

Principales etiquetas de plantillas

Variables

{variablename}

Como muchos otros sistemas de plantillas, TemplatePower usa {variablename} como marca para algunos valores. el nombre variablename debe ser un entero no negativo o una cadena. En caso de ser una cadena, no debe contener el símbolo de llave ( { ) ni un espacio en blanco. esto significa que nombres de variable como {-1}, {a{name} o {a name} no se permiten.

En tu programa (script PHP) de control se puede asignar un valor a una variable con la función assign(). Todos los marcadores de variables con el mismo nombre dentro de un bloque son vistos como una sola variable, por tanto solo tienen que ser asignados una vez.

Bloques dinámicos

<!-- START BLOCK : blockname -->

<!-- END BLOCK : blockname -->

Puedes usar bloques dinámicos, por ejemplo si quieres crear una tabla con productos que tenga en cada fila un número de producto, el nombre del producto y el precio. Simplemente hay que situar el código de cada fila entre marcas como las indicadas arriba. Estas marcas DEBEN estar en una linea independiente para funcionar correctamente. El nombre del bloque 'blockname' tiene que ser un entero no negativo o una cadena de texto, esta cadena no puede contener un punto (.).

En el programa de control puedes usar estos bloques con la función newBlock().

Los bloques también son útiles para mostrar y ocultar información. Si defines un bloque en la plantilla, pero no lo creas con la función newBlock(), el código contenido entre las marcas de bloque no se mostrará. Esto es útil, por ejemplo, para mostrar y ocultar mensajes de error.

Bloques de inclusión. (Include blocks)

<!-- INCLUDE BLOCK : iblockname -->

Gracias a los bloques de inclusión puedes incluir archivos como subplantillas (el código, no objetos), HTML, etc. De todas formas si incluyes un archivo PHP, debes recordar que el código PHP no será ejecutado. Si quieres que el código incluido sea ejecutado debes usar la etiqueta de marca includescript, disponible en TemplatePower a partir de la versión 2.0 en adelante.

Esta marca debe ir en una linea ella sola para funcionar correctamente. El nombre del bloque ' iblockname' debe ser un entero no negativo o bien una cadena que no puede contener punto (.).

En tu programa de control puedes asignar archivos al bloque iblockname usando la función assignInclude().

En TemplatePower v3.0+ también es posible crear un bloque de inclusión constante.

<!-- INCLUDE BLOCK : ./header.tpl -->

Etiquetas de plantillas de TemplatePower v2.0+

Includescript blocks

<!-- INCLUDESCRIPT BLOCK : iblockname -->

Con la etiqueta de bloque includescript block puedes insertar un archivo PHP y su código será ejecutado. Esta marca debe ir en una linea ella sola para funcionar correctamente. El nombre del bloque ' iblockname' debe ser un entero no negativo o bien una cadena que no puede contener punto (.).

En tu programa de control puedes asignar archivos al bloque iblockname usando la función assignInclude().

Al igual que en la etiqueta de bloque 'include block', también es posible crear un bloque constante de includescript. Esta característica es soportada por TemplatePower v3.0 o superior.

<!-- INCLUDESCRIPT BLOCK : ./header.php -->

Bloque a ignorar.(Ignore block)

<!-- START IGNORE -->
	  
<!-- END IGNORE -->

Situando cualquier código en medio de las etiquetas ignore, se consigue que sea ignorado en el análisis y tratado simplemente como código. No se procesarán variables o bloques en ese código, como siempre, deben ir solos en una linea para funcionar correctamente.

Bloque de reutilización. (ReUse block)

<!-- REUSE BLOCK : orig_bname AS copy_bname -->

Con el la etiqueta de bloque 'reuse block' puedes volver a usar cualquier bloque y darle un nombre diferente. Esta caracteristica no está totalmente probada. Solamente funciona bien si el bloque reutilizado no tiene bloques hijos.

Como en las etiquetas anteriores, los nombres tienen que ser enteros no negativos o cadenas que no contengan punto (.).

Plantillas almacenadas en bases de datos

Las plantillas almacenadas en bases de datos tienen que se guardadas en el mismo formato que las platillas normales, por tanto el retorno de carro (CR) y la marca de nueva linea (LF) deben ser guardadas también en la base de datos.

Index

El objeto TemplatePower

(unknown)

Crea un nuevo objeto TemplatePower .

Descripción

object TemplatePower ( string basefile/content, [const type] )

El valor predeterminado del parámetro type es la constante T_BYFILE, en el caso de que el primer parámetro sea el nombre de un archivo. Si el primer parámetro es una variable con el contenido de una plantilla, type debe tomar el valor T_BYVAR.

Véase también: assignInclude().

Ejemplos de objetos TemplatePower v3.0+

//create a new TemplatePower object using a file

$tpl = new TemplatePower( "./base.tpl" );
$tpl = new TemplatePower( "./base.tpl", T_BYFILE );


//create a new TemplatePower object using a variable

$tpl = new TemplatePower( $base_content, T_BYVAR );


//create a new TemplatePower object using a 
//serialized template

$tpl = new TemplatePower( $base_content );
$tpl->serializedBase();

En la version 1.6.2 de TemplatePower solamente habia un parámetro, que era basefile. En la versión 2.0 habia un segundo parámetro, para informar si basefile es una plantilla serializada o no. En la versión 3.0+ esto es diferente usando la función serializedBase().

Ejemplos de objetos TemplatePower v2.0.

//create a new TemplatePower object using a file

$tpl = new TemplatePower( "./base.tpl" );


//create a new TemplatePower object using a 
//serialized template

$tpl = new TemplatePower( "./base.stpl", true );

Index

assign

Asigna un valor a una variable.

Descripción

assign ( string [blockname.]variablename, mixed value )
assign ( Array( [blockname.]variablename => value ) )

El valor predeterminado para value es ''.

Véase también: assignGlobal(), getVarValue(), y showUnAssigned().

Ejemplo 1.

simple.tpl

<html>
<head>
<title>Simple Template Example</title>
</head>
<body>
<H2>Welcome {name}!</H2>
</body>
</html>

myscript.php

<?php
include_once( "./class.TemplatePower.inc.php" );

$tpl = new TemplatePower( "./simple.tpl" );
$tpl->prepare();

$tpl->assign( "name", "Ron" );

$tpl->printToScreen();
?>

Ejemplos de la función assign.

$tpl->assign( "name", "Ron" );
$tpl->assign( Array( product_id  => $pid,
                     productname => $pname ));

Variables y Bloques

Cada variables es hija de un bloque padre. Incluso en el Ejemplo 1, en el que no hay un bloque definido, la variable name tiene un bloque padre. El bloque padre de name es _ROOT, este es el bloque predeterminado si una variable no tiene un bloque padre definido expresamente por el usuario.

Se pueden utilizar las variables, nombrandolas junto con su bloque padre, usando el formato 'nombreDeBloquePadre.nombreDeVariable'.

$tpl->assign( "_ROOT.name", "Ron" );
$tpl->assign( "book.title", "Core PHP Programming" );

Index

assignGlobal

(TP 2.0+)

Asigna a todas la variables con el mismo nombre un valor.

Descripción

assignGlobal ( string variablename, mixed value )
assignGlobal ( array( variablename => value ) )

La función assignGlobal() da un valor a todas las variables con un determinado nombre, con independencia del bloque al que pertenecen. Este valor puede ser reemplazado después en cada bloque utilizando la función assign().

Ejemplo 1.

img.tpl

<html>
<head>
  <title>AssignGlobal Example</title>
</head>
<body>
  <img src="{imagedir}/logo.gif">

  
    <img src="{imagedir}/img_{id}.gif">
  
</body>
</html>

myscript.php

<?php
include_once( "./class.TemplatePower.inc.php" );

$tpl = new TemplatePower( "./img.tpl" );
$tpl->prepare();

$tpl->assignGlobal( "imagedir", "images");

for ( $i=1; $i<=10; $i++ )
{
    $tpl->newBlock( "image" );
    $tpl->assign( "id", $i );
}

$tpl->printToScreen();
?>

Ejemplos de la función assignGlobal

$tpl->assignGlobal( "basedir", "/usr/local/apache/www/");
$tpl->assignGlobal( Array( basedir  => "/usr/local/apache/www/",
                           imagedir => "images/" ));

Index

assignInclude

(TP 2.0+)

Asigna el archivo/contenido a incluir para un bloque.

Description

assignInclude ( string includename, string filename/content, [const type] )

El valor predeterminado del parámetro type es la constanteT_BYFILE si el segundo parámetro es un nombre de archivo. Si el segundo parámetro fuese una variable con el contenido de una plantilla, type debería ser T_BYVAR.

Ejemplo 1.

include.tpl

<html>
<head>
  <title>AssignInclude Example</title>
</head>
<body>
  

  
</body>
</html>

myscript.php

<?php
include_once( "./class.TemplatePower.inc.php" );

$tpl = new TemplatePower( "./include.tpl" );
$tpl->assignInclude( "header", "./header.tpl" );
$tpl->assignInclude( "content", "./about.php" );
$tpl->prepare();

$tpl->printToScreen();
?>

Ejemplos de la función assignInclude

$tpl->assignInclude( "header", "./header.tpl" );
$tpl->assignInclude( "content", $content, T_BYVAR );

Ejemplo 2. Plantillas en bases de datos


<?php
  include( "./class.TemplatePower.inc.php");

 //connect to database
   $link = mysql_connect("host", "user", "passwd")
              or die("Could not connect");
     
  mysql_select_db("my_database") 
      or die("Could not select database");  

 //get database templates
   $qry = "SELECT base, header FROM templates";

  $result = mysql_query($qry);
  
  if( mysql_num_rows($result) > 0)
  {
      list($base, $header) = mysql_fetch_row($result);
  }
 
 //make a new TemplatePower object
  $tpl = new TemplatePower( $base, T_BYVAR );

 //assign include template by variable
  $tpl->assignInclude( "header", $header, T_BYVAR );
  $tpl->prepare();

 //print the result
  $tpl->printToScreen();
 ?>

Index

getOutputContent

(unknown)

Devuelve una cadena con todos los datos de la plantilla, es lo mismo que imprime la función printToScreen.

Descripción

getOutputContent ()

Index

getVarValue

(unknown)

Devuelve el valor de una variable.

Descripción

getVarValue ( string [blockname.]variablename )

Nota: Solo se puede recuperar el valor de la última instancia de una variable. Esto significa que, dentro de un bloque repetitivo, solamente se pueden recuperar los valores de las variables del último bloque creado.

Ejemplo 1.

number.tpl

<html>
<head>
  <title>AssignInclude Example</title>
</head>
<body>
  
    {number}
  
  {total}
</body>
</html>

myscript.php

<?php
include_once( "./class.TemplatePower.inc.php" );

$tpl = new TemplatePower( "./number.tpl" );
$tpl->prepare();

for( $i=1; $i <= 10; $i++ )
{
 $tpl->newBlock( "number" );
 
 $tpl->assign( "number"     , $i );
 $tpl->assign( "_ROOT.total", ($tpl->getVarValue( "_ROOT.total" ) + $i) );
}

$tpl->printToScreen();
?>

Index

gotoBlock

(unknown)

Mueve el 'puntero de bloque' a un bloque convirtiendolo en el bloque actual.

Descripción

gotoBlock ( string blockname )

La función gotoBlock() mueve el 'puntero de bloque' al bloque blockname, convirtiendolo en el bloque actual. Esto es útil cuando se quiere volver a un bloque anterior y asignar sus variables.

Example 1.

newBlock.tpl

<html>
<head>
  <title>NewBlock</title>
</head>
<body>
<table>
  <tr><td>Names</td></tr>
  <!-- START BLOCK : name_row -->
  <tr>
    <td>{name}</td>
  </tr>
  <!-- END BLOCK : name_row --> 
</table>
<br>
{total_names}
</body>
</html>

myscript.php

<?php
include_once( "./class.TemplatePower.inc.php" );

$tpl = new TemplatePower( "./newBlock.tpl" );
$tpl->prepare();

$count = 0;

while( $count < 10 )
{
    $tpl->newBlock( "name_row" );
    $tpl->assign( "name", "Ron" );
 
    $count++;
}

$tpl->gotoBlock( "_ROOT" );
$tpl->assign( "total_names", $count );

$tpl->printToScreen();
?>

Index

newBlock

(unknown)

Crea un nuevo bloque.

Descripción

newBlock ( string blockname )

Después de llamar a la función newBlock() TemplatePower situará el 'puntero de bloque' en el bloque de nombre blockname. De esta manera, si se quiere asignar un valor a una variable de otro bloque, se debe mover el 'puntero de bloque' a ese bloque, (véase gotoBlock() ) o usar el nombre de esa variable junto con su nombre de bloque (véase Variables and Blocks). Si no se hace así, TemplatePower asumirá que esa variable es parte del bloque actual.

Example 1.

newBlock.tpl

<html>
<head>
  <title>NewBlock</title>
</head>
<body>
<table>
  <tr><td>Names</td></tr>
  <!-- START BLOCK : name_row -->
  <tr>
    <td>{name}</td>
  </tr>
  <!-- END BLOCK : name_row --> 
</table>
<br>
{total_names}
</body>
</html>

myscript.php

<?php
include_once( "./class.TemplatePower.inc.php" );

$tpl = new TemplatePower( "./newBlock.tpl" );
$tpl->prepare();

$count = 0;

while( $count < 10 )
{
    $tpl->newBlock( "name_row" );
    $tpl->assign( "name", "Ron" );
 
    $count++;
}

$tpl->gotoBlock( "_ROOT" );
$tpl->assign( "total_names", $count );

$tpl->printToScreen();
?>

Si no se usa la función newBlock() para crear un bloque, el código que ese bloque contiene permanecerá oculto. En el 'Ejemplo 2' se puede ver un ejemplo de esto, en el cual una dirección de correo electrónico se envia por un formulario. Si no se proporciona una dirección, se imprimirá un mensaje de error.

Ejemplo 2.

form.tpl

<html>
<head>
 <title></title>
</head>
<body>
<!-- START BLOCK : error -->
The following errors occurred.<br>
  <!-- START BLOCK : message -->
  - {message}<br>
  <!-- END BLOCK : message -->
<!-- END BLOCK : error -->

<form method="post" action="myscript.php">
  Email:
  <input type="text" name="email">
  <input type="submit" name="submit" value="Submit">
</form>
</body>
</html>

myscript.php

<?php
include_once('./class.TemplatePower.inc.php');

$tpl = new TemplatePower('form.tpl');
$tpl->prepare();

$errorMessage = Array();
$errorFound   = false;

if( isset( $submit ) )
{
  if($email == '')
  {
    $errorMessage[] = 'No emailadress entered';   
    $errorFound     = true;
  }
    
  if( $errorFound )
  {
    $tpl->newBlock('error');