manual do TemplatePower

CopyRights © 2001, 2002 Ron P.J. Velzeboer


Translated by:

Mauricio Wolff
  1. Introdução
        O que é a classe TemplatePower?
        O que ela faz?
        Por que você deveria usar a classe TemplatePower?
        Requerimentos
        GNU General Public License
  2. Formato do Template
  3. objeto TemplatePower
  4. Funções
        assign
        assignGlobal
        assignInclude
        getOutputContent
        getVarValue
        gotoBlock
        newBlock
        prepare
        printToScreen
        serializedBase
        showUnAssigned
        version

Index

O que é TemplatePower?

TemplatePower oferece a possibilidade de separar o seu código PHP e o seu arquivo de layout (HTML). É similar à classe FastTemplate, mas é muito mais rápida do que a mesma. (aproximadamente 6x).

O que a classe TemplatePower faz?

TemplatePower 1.6.2 tem as seguintes capacidades:

- suporte para blocos dinâmicos aninhados.
- suporte para inclusão de blocos / arquivos (nota: código PHP não será executado, utilize a v2.0).
- mostra / escode variáveis sem valor atribuído.

TemplatePower 2.0 inclui isso e mais:
- tag ignore.
- tag de inclusão de arquivos PHP, com execução de código.
- atribuição global de variáveis
- atribuição múltipla de variáveis em uma declaração de função assign, usando um array associativo.
- salvar / usar template já processado no / do disco.
- reutilização de tags (em testes).

TemplatePower 3.0 inclui isso e ainda mais:
- suporte para database templates.

Por que você deveria usar a classe TemplatePower?

Em primeiro lugar, é grátis para o uso pessoal (General Public License - GPL)!

O motivo que me levou a desenvolver a TemplatePower foi que a FastTemplate não é tão fácil de usar (essa é a minha opinião). Pelo menos poderia ter sido feita com uma utilização mais fácil, por isso a TemplatePower era chamada de EasyTemplate quando foi criada. Mas este nome já estava em uso por outro produto, como percebi mais tarde. Então, mudei o nome para TemplatePower. Espero que você concorde comigo, a TemplatePower é mais fácil de usar que a FastTemplate. E como já foi escrito acima, TemplatePower é muito mais rápida que a FastTemplate. Provavelmente estas são as razões mais importantes pelas quais você deveria usar a classe TemplatePower ao invés da FastTemplate.

If you find a bug(s) please fill in the bugreport which you can find here.

Requerimentos

TemplatePower requer PHP 4.0.1 ou superior e roda em sistemas baseados em windows ou unix.

GNU General Public License

TemplatePower é licenciada sob as regras da GNU General Public License. Se você quiser vende uma aplicação/website onde a TemplatePower seja parte da mesma, você pode comprar um 'Certificado de Distribuição' especial. Este certificado lhe permite vender um número (com um mínimo de 5) de aplicações/websites com TemplatePower. O Certificado custa em torno de (número de websites x US$ 3 - [três dólares americamos]).

Index

Formato do Template

Principais marcadores/tags de template

Variáveis
{variablename}

Assim como a maioria dos outros sistemas de template, TemplatePower usa {variablename} como um marcador para algum valor. O variablename deve ser ou um inteiro positivo ou uma string. No entanto esta string não pode conter chaves ( { ) ou espaços em branco. Isto signifiac que os marcadores de variáveis como {-1}, {a{name} ou {a name} não são permitidos.

No seu script de controle (PHP) você pode atribuir valores às variáveis utilizando a função assign(). Todos os marcadores, dentro de um bloco, com o mesmo nome serão vistos como uma só variável. Neste caso, elas devem ser atribuídas apenas uma vez.
Blocos dinâmicos
<!-- START BLOCK : blockname -->

<!-- END BLOCK : blockname -->

Você pode usar blocos dinâmicos, por exemplo, quando você quer criar uma tabela com produtos onde cada linha da tabela contém o código do produto, nome do produto e preço. Você somente tem de inserir o código de linha entre os marcadores de start/end acima. Estes marcadores devem estar cada um numa linha separada, para que funcionem corretamente. o blockname deve ser um inteiro positivo ou uma string. No entanto essa string não pode ser iniciada em um ponto (.).

No seu script de controle você pode usar estes blocos através da função newBlock().

Blocos também podem ser usados para mostrar ou esconder informações. Se você tem um bloco definido no seu template mas não o cria com a função newBlock(), o código do bloco será escondido. Isto é muito útil para mostrar/esconder mensagens de erro, por exemplo.
Blocos de Inclusão (Include blocks)
<!-- INCLUDE BLOCK : iblockname -->

Com os blocos de inclusão você pode incluir arquivos como subtemplates (o código de templates, não objetos), HTML, etc. No entanto, se você incluir um arquivo PHP, o código PHP não será executado. É possível incluir arquivos PHP onde o código é executado através do marcador de bloco includescript,leia a seção sobre tags de template do TemplatePower v2.0+ abaixo. Este marcador deve estar numa linha separada (exclusiva), para funcionar corretamente. O iblockname deve ser um inteiro positivo ou string, mas a string não pode conter um ponto (.).

No seu script de controle você pode atribuir arquivos para iblockname através da função assignInclude().

No TemplatePower v3.0+ também é possível criar um include block constante.

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

Tags de Template da TemplatePower v2.0+

blocos Includescript
<!-- INCLUDESCRIPT BLOCK : iblockname -->

Com o tag de includescript você pode inserir um arquivo PHP, e o seu código será executado. Este amrcador deve estar numa linha separada (exclusiva) para que funcione corretamente.O iblockname deve ser um inteiro positivo ou uma string. No entanto a string não pode conter um ponto (.).

No seu script de controle você pode atribuir arquivos para iblockname com a função assignInclude().

Assim como no marcador de include block, também é possível criar um bloco de includescript constante. Esta característica está presente no TemplatePower v3.0 ou superior.

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

bloco Ignore
<!-- START IGNORE -->

<!-- END IGNORE -->

Se você inserir qualquer código entre estes marcadores, ele será interpretado como código. Nenhuma variável ou bloco será processado. Estes marcadores devem estar numa linha separada (exclusiva) para funcionarem corretamente.

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

Com este marcador de reuse você pode reutilizar outro bloco e dar-lhe um nome de bloco diferente. Esta features não é totalmente a prova de bugs. O marcador reuse funcionará corretamente somente quando o bloco que você quiser reutilizar não contiver blocos aninhados.

O copyblockname deve ser um inteiro positivo ou uma string. No entanto a string não pode conter um ponto (.).


Database templates

Database Templates tem de ser guardados nos mesmo formato que templates normais. Então, o caracter de 'retorno de carro' [Carriage Return (cr)] e 'nova linha' [Line Feed (lf)] também devem ser guardados no banco de dados.

Index

TemplatePower object

(desconhecido)

Cria um novo objeto TemplatePower.

Descrição

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

O valor padrão para o parâmetro type é a constante T_BYFILE, no caso do primeiro parâmetro ser um nome de arquivo. No caso dele ser uma variável com o conteúdo de um template, type deve ser definido como T_BYVAR.


Veja também: assignInclude().

Exemplos dos 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();


Na versão 1.6.2 da classe TemplatePower havia apenas um parâmetro, que era basefile. Na versão 2.0 foi adicionado um segundo parâmetro, para dizer se basefile era um serialized template. Na versão version 3.0+ isto é feito de forma diferentes, usando a função serializedBase().
Exemplos 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

Define uma valor à uma variável.

Descrição

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

O valor padrão de value é ''.


 Veja também: assignGlobal(), getVarValue(), e showUnAssigned().

Exemplo 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();
?>

Examplos da função assign
$tpl->assign( "name", "Ron" );
$tpl->assign( Array( product_id  => $pid,
                     productname => $pname ));

Variáveis e Blocos

Cada variável é um elemento (child) de um bloco (parent block). Mesmo no exemplo 1, onde não ocorre a definição de bloco, a variável name está inserida no contexto de um bloco. O bloco de name é _ROOT, que é o bloco padrão se uma variável não se encontra num bloco definido pelo usuário.

Variáveis também podem ser definidas junto com o nome do seu bloco, no formato "nome_do_bloco.nome_da_variavel".

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

Index

assignGlobal

(TP 2.0+)

Define um valor para todas as variáveis de mesmo nome.

Descrição

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


A função assignGlobal() dá um valor padrão para todas as variáveis, mesmo dentro de blocos, desde que possuam o mesmo nome. O valor padrão pode ser substituído dentro de cada bloco que possui a variável, através da função assign().
Exemplo 1.
img.tpl
<html>
<head>
  <title>AssignGlobal Example</title>
</head>
<body>
  <img src="{imagedir}/logo.gif">

  <!-- START BLOCK : image -->
    <img src="{imagedir}/img_{id}.gif">
  <!-- END BLOCK : image -->
</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();
?>

Exemplos da funçãoassignGlobal
$tpl->assignGlobal( "basedir", "/usr/local/apache/www/");
$tpl->assignGlobal( Array( basedir  => "/usr/local/apache/www/",
                           imagedir => "images/" ));

Index

assignInclude

(TP 2.0+)

Diz qual arquivo/conteúdo deve ser incluído.

Descrição

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


O valor padrão do parâmetro type é a constante T_BYFILE, no caso do segundo parâmerto ser um nome de arquivo. Se o segundo parâmetro for uma variável com o conteúdo de um template, type deve ser alterado para T_BYVAR.
Exemplo 1.
include.tpl
<html>
<head>
  <title>AssignInclude Exemplo</title>
</head>
<body>
  <!-- INCLUDE BLOCK : header -->

  <!-- INCLUDESCRIPT BLOCK : content -->
</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();
?>


Exemplos da função assignInclude
$tpl->assignInclude( "header", "./header.tpl" );
$tpl->assignInclude( "content", $content, T_BYVAR );


Exemplo 2.  Database Templates

<?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

(desconhecido)

Retorna uma string com todos os dados do template, igual à saída da função printToScreen.

Descrição

getOutputContent ()

Index

getVarValue

(desconhecido)

Retona o valor de uma variável.

Descrição

getVarValue ( string [blockname.]variablename )


Nota: Somente o valor da última instância da variável poderá ser recuperado com esta função. Isto significa que se voê tem um bloco de repetição, você somente terá os valores da variável do último bloco criado.
Exemplo 1.
number.tpl
<html>
<head>
  <title>AssignInclude Exemplo</title>
</head>
<body>
  <!-- START BLOCK : number -->
    {number}
  <!-- END BLOCK : 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

(desconhecido)

Move o 'ponteiro-de-bloco' para um bloco, tornando-o o bloco corrente.

Descrição

gotoBlock ( string blockname )

A função gotoBlock() move o 'ponteiro-do-bloco' para o bloco blockname, tornando-o o bloco corrente. Isto é útil quando você quer retornar a um bloco já criado e atribuir as suas variáveis..
Exemplo 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

(desconhecido)

Cria um novo bloco.

Descrição

newBlock ( string blockname )

Depois de usar a função newBlock() TemplatePower irá definir o 'ponteiro-do-bloco' para o bloco blockname. Então, se você quiser atribuir valor à uma variável de outro bloco, você terá de mover o 'ponteiro-do-bloco' para outro (veja gotoBlock() ) ou usar o nome da variável justaposta ao nome do seu bloco (veja Variables and Blocks). Se você não fizer isso, TemplatePower irá assumir que a variável faz parte do bloco corrente.
Exemplo 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();
?>


Se você não usar a função newBlock() para criar um bloco, o código dentro do bloco será escondido. No 'Exemplo 2' você tem um exemplo disso onde o endereço de email pode ser enviado por um formulário. Se nnhum endereço de email for digitado, a página irá retornar uma mensagem de erro.
Exemplo 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');

    $size = sizeof($errorMessage);

    for( $i=0; $i < $size; $i++ )
    {
      $tpl->newBlock('message');
      $tpl->assign('message', $errorMessage[$i]);
    }
  }
  else
  {
    Header('Location: member.php');
  }
}

$tpl->printToScreen();
?>

Index

prepare

(desconhecido)

Analisa (parse) os templates.

Descrição

prepare ()

A função prepare() deve ser usada para cada objeto TemplatePower para que a classe possa funcionar. Caso contrário os templates não serão analisados e as variáveis não terão valores atribuídos.

Nota: A função prepare() deve ser executada antes que você crie novos blocos e/ou atribua valores às variáveis (assign) e depois das funções assignInclude() e serializedBase().

Index

printToScreen

(desconhecido)

Mostra (imprime na tela) o resultado final da página, em HTML.

Descrição

printToScreen ()

Index

serializedBase

(TP 3.0+)

Diz para o TemplatePower que o arquivo-base/conteúdo é serialized.

Descrição

serializedBase ()

Index

showUnAssigned

(TP 3.0+)

Mostra/esconde variáveis sem valor atribuído.

Descrição

showUnAssigned ( bool state )

Index

version

(TP 2.0+)

Retorna a versão da classe TemplatePower.

Descrição

version ()

Index