mirror of
https://github.com/smarty-php/smarty.git
synced 2026-02-13 18:40:18 +01:00
547 lines
19 KiB
XML
547 lines
19 KiB
XML
<?xml version="1.0" encoding="iso-8859-1"?>
|
|
<!-- $Revision$ -->
|
|
<chapter id="advanced.features">
|
|
<title>Advanced Features</title>
|
|
<sect1 id="advanced.features.objects">
|
|
<title>Objetos</title>
|
|
<para>
|
|
O Smarty permite acesso a objetos do PHP através de seus templates. Há duas formas de acessá-los.
|
|
Uma forma é registrar objetos para o template, então os acessa via sintaxe similar a funções
|
|
customizáveis. A outra forma é atribuir objetos para os templates e acessá-los como se fossem
|
|
uma variável atribuída. O primeiro método tem uma sintaxe de template muito mais legal. E também
|
|
mais segura, à medida que um objeto registrado pode ser restrito a certos métodos e
|
|
propriedades. Entretanto, um objeto registrado não pode ser
|
|
posto em loop ou ser atribuido em arrays de
|
|
objetos, etc. O método que você escolher será determinado pelas suas necessidades, mas use o
|
|
primeiro método se possível para
|
|
manter um mínimo de sintaxe no template.
|
|
</para>
|
|
<para>
|
|
Se a segurança está habilitada, nenhum dos métodos privados ou funções podem acessados
|
|
(começando com "_"). Se um método e propriedade de um mesmo nome existir, o método será
|
|
usado.
|
|
</para>
|
|
<para>
|
|
Você pode restringir os métodos e propriedades que podem ser acessados listando os em um array
|
|
como o terceiro parâmetro de registração.
|
|
</para>
|
|
<para>
|
|
Por definição, parâmetros passados para objetos através dos templates são passados da mesma
|
|
forma que funções customizáveis os obtém. Um array associativo é passado como o primeiro parâmetro,
|
|
e o objeto smarty como o segundo. Se você quer que os parâmetros passados um de cada vez
|
|
por cada argumento como passagem de parâmetro de objeto tradicional, defina o quarto parâmetro
|
|
de registração para falso.
|
|
</para>
|
|
<para>
|
|
O quinto parâmetro opcional só tem efeito com <parameter>format</parameter>
|
|
sendo <literal>true</literal> e contém
|
|
uma lista de métods de ob que seriam tratados como
|
|
blocos. Isso significa que estes métodos
|
|
tem uma tag de fechamento no template
|
|
(<literal>{foobar->meth2}...{/foobar->meth2}</literal>) e
|
|
os parâmetros para os métodos tem a mesma sinopse como os parâmetros para
|
|
block-function-plugins: Eles pegam 4 parâmetros
|
|
<parameter>$params</parameter>,
|
|
<parameter>$content</parameter>,
|
|
<parameter>&$smarty</parameter> e
|
|
<parameter>&$repeat</parameter> e eles também comportam-se como
|
|
block-function-plugins.
|
|
</para>
|
|
<example>
|
|
<title>usando um objeto registrado ou atribuído</title>
|
|
<programlisting>
|
|
<?php
|
|
// O objeto
|
|
|
|
class My_Object {
|
|
function meth1($params, &$smarty_obj) {
|
|
return "this is my meth1";
|
|
}
|
|
}
|
|
|
|
$myobj = new My_Object;
|
|
// registrando o objeto (será por referência)
|
|
$smarty->register_object("foobar",$myobj);
|
|
// Se você quer restringie acesso a certos métodos ou propriedades, liste-os
|
|
$smarty->register_object("foobar",$myobj,array('meth1','meth2','prop1'));
|
|
// Se você quer usar o formato de parâmetro de objeto tradicional, passe um booleano de false
|
|
$smarty->register_object("foobar",$myobj,null,false);
|
|
|
|
// Você pode também atribuir objetos. Atribua por referência quando possível.
|
|
$smarty->assign_by_ref("myobj", $myobj);
|
|
|
|
$smarty->display("index.tpl");
|
|
?>
|
|
|
|
TEMPLATE:
|
|
|
|
{* accessa nosso objeto registrado *}
|
|
{foobar->meth1 p1="foo" p2=$bar}
|
|
|
|
{* você pode também atribuir a saída *}
|
|
{foobar->meth1 p1="foo" p2=$bar assign="output"}
|
|
the output was {$output}
|
|
|
|
{* acessa nosso objeto atribuído *}
|
|
{$myobj->meth1("foo",$bar)}</programlisting>
|
|
</example>
|
|
</sect1>
|
|
<sect1 id="advanced.features.prefilters">
|
|
<title>Prefilters</title>
|
|
<para>
|
|
Os prefilters de Template são funções de PHP nas quais seus templates são rodados
|
|
antes de serem compilados. Isto é bom para preprocessamento de seus templates para remover
|
|
comentários indesejados, mantendo o olho no que as pessoas estão colocando nos seus templates,
|
|
etc. Prefilters podem ser ou <link linkend="api.register.prefilter">registrado</link>
|
|
ou carregado do diretório de plugins usando a função
|
|
<link linkend="api.load.filter">load_filter()</link>
|
|
ou pela configuração da variável
|
|
<link linkend="variable.autoload.filters">$autoload_filters</link>.
|
|
O Smarty passará o código fonte do template como o
|
|
primeiro argumeto, e espera a função retornar
|
|
o código fonte do template resultante.
|
|
</para>
|
|
<example>
|
|
<title>Usando um prefilter de template</title>
|
|
<programlisting>
|
|
<?php
|
|
// Ponha isto em sua aplicação
|
|
function remove_dw_comments($tpl_source, &$smarty)
|
|
{
|
|
return preg_replace("/<!--#.*-->/U","",$tpl_source);
|
|
}
|
|
|
|
// registrar o prefilter
|
|
$smarty->register_prefilter("remove_dw_comments");
|
|
$smarty->display("index.tpl");
|
|
?>
|
|
|
|
{* Smarty template index.tpl *}
|
|
<!--# esta linha será removida pelo prefilter --></programlisting>
|
|
</example>
|
|
</sect1>
|
|
|
|
<sect1 id="advanced.features.postfilters">
|
|
<title>Postfilters</title>
|
|
<para>
|
|
Os postfilters de template são funções de PHP nas quais seus templates são rodados
|
|
imediatamente depois de serem compilados. Os postfilters podem ser ou
|
|
<link linkend="api.register.postfilter">registrado</link>carrgados do diretório de
|
|
plugins usando a função
|
|
<link linkend="api.load.filter">load_filter()</link> ou pela
|
|
variável de configuração
|
|
<link linkend="variable.autoload.filters">$autoload_filters</link>.
|
|
O Smarty passará o código fonte do template compilado
|
|
como o primeiro argumento, e espera
|
|
a função retornar o resultado do processamento.
|
|
</para>
|
|
<example>
|
|
<title>usando um postfilter de template</title>
|
|
<programlisting>
|
|
<?php
|
|
// ponha isto em sua aplicação
|
|
function add_header_comment($tpl_source, &$smarty)
|
|
{
|
|
return "<?php echo \"<!-- Created by Smarty! -->\n\" ?>\n".$tpl_source;
|
|
}
|
|
|
|
// registra o postfilter
|
|
$smarty->register_postfilter("add_header_comment");
|
|
$smarty->display("index.tpl");
|
|
?>
|
|
|
|
{* compiled Smarty template index.tpl *}
|
|
<!-- Created by Smarty! -->
|
|
{* rest of template content... *}</programlisting>
|
|
</example>
|
|
</sect1>
|
|
|
|
<sect1 id="advanced.features.outputfilters">
|
|
<title>Output Filters (Filtros de Saída)</title>
|
|
<para>
|
|
Quando o template é invocado via display() ou fetch(), sua saída pode ser enviada
|
|
através de um ou mais filtros de saída. Estes diferem dos postfilters porque postfilters
|
|
operam em templates compilados antes de serem salvos para o disco, e os filtros de saída
|
|
operam na saída do template quando
|
|
ele é executado.
|
|
</para>
|
|
|
|
<para>
|
|
Filtros de Saída podem ser ou
|
|
<link linkend="api.register.outputfilter">registrado</link> ou carregado
|
|
do diretório de plugins usando a função
|
|
<link linkend="api.load.filter">load_filter()</link> ou configurando a variável
|
|
<link linkend="variable.autoload.filters">$autoload_filters</link>.
|
|
O Smarty passará a saída como o primeiro argumento,
|
|
e espera a função retornar o resultado
|
|
do processamento.
|
|
</para>
|
|
<example>
|
|
<title>usando um filtro de saída de template</title>
|
|
<programlisting>
|
|
<?php
|
|
// ponha isto em sua aplicação
|
|
function protect_email($tpl_output, &$smarty)
|
|
{
|
|
$tpl_output =
|
|
preg_replace('!(\S+)@([a-zA-Z0-9\.\-]+\.([a-zA-Z]{2,3}|[0-9]{1,3}))!',
|
|
'$1%40$2', $tpl_output);
|
|
return $tpl_output;
|
|
}
|
|
|
|
// registra o outputfilter
|
|
$smarty->register_outputfilter("protect_email");
|
|
$smarty->display("index.tpl");
|
|
|
|
// agora qualquer ocorrência de um endereço de email na saída do template terá uma
|
|
// simples proteção contra spambots
|
|
?></programlisting>
|
|
</example>
|
|
</sect1>
|
|
|
|
<sect1 id="section.template.cache.handler.func">
|
|
<title>Função Manipuladora de Cache</title>
|
|
<para>
|
|
Como uma alternativa ao uso do mecanismo de caching padrão baseado em arquivo, você pode
|
|
especificar uma função de manipulação de cache customizada que será usada para ler, escrever
|
|
e limpar arquivos de cache.
|
|
</para>
|
|
<para>
|
|
Crie uma função em sua aplicação que o Smarty usará como um manipulador de cache. Defina o
|
|
nome dela na variável de classe
|
|
<link linkend="variable.cache.handler.func">$cache_handler_func</link>.
|
|
O Smarty agora usará esta para manipular dados no cache. O primeiro argumento é a ação,
|
|
que é um desses 'read', 'write' e 'clear'. O segundo parâmetro é o objeto do Smarty. O
|
|
terceiro parâmetro é o conteúdo que está no cache.
|
|
No write, o Smarty passa o conteúdo em
|
|
cache nestes parâmetros. No 'read', o Smarty espera sua função aceitar este parâmetro por
|
|
referência e preenche ele com os dados em cache. No 'clear', passa uma variável simulacra aqui
|
|
visto que ela não é usada. O quarto parâmetro
|
|
é o nome do arquivo de template (necessário para
|
|
ler/escrever), o quinto parâmetro é a cache_id (opcional),
|
|
e o sexto é a compile_id (opcional).
|
|
</para>
|
|
<para>
|
|
Note que: O último parâmetro ($exp_time)foi adicionado no Smarty-2.6.0.
|
|
</para>
|
|
<example>
|
|
<title>exemplo usando MySQL como uma fonte de cache</title>
|
|
<programlisting>
|
|
<?php
|
|
/*
|
|
|
|
exemplo de uso:
|
|
|
|
include('Smarty.class.php');
|
|
include('mysql_cache_handler.php');
|
|
|
|
$smarty = new Smarty;
|
|
$smarty->cache_handler_func = 'mysql_cache_handler';
|
|
|
|
$smarty->display('index.tpl');
|
|
|
|
|
|
mysql database is expected in this format:
|
|
|
|
create database SMARTY_CACHE;
|
|
|
|
create table CACHE_PAGES(
|
|
CacheID char(32) PRIMARY KEY,
|
|
CacheContents MEDIUMTEXT NOT NULL
|
|
);
|
|
|
|
*/
|
|
|
|
function mysql_cache_handler($action, &$smarty_obj, &$cache_content, $tpl_file=null, $cache_id=null, $compile_id=null, $exp_time=null)
|
|
{
|
|
// set db host, user and pass here
|
|
$db_host = 'localhost';
|
|
$db_user = 'myuser';
|
|
$db_pass = 'mypass';
|
|
$db_name = 'SMARTY_CACHE';
|
|
$use_gzip = false;
|
|
|
|
// cria um cache id unico
|
|
$CacheID = md5($tpl_file.$cache_id.$compile_id);
|
|
|
|
if(! $link = mysql_pconnect($db_host, $db_user, $db_pass)) {
|
|
$smarty_obj->_trigger_error_msg("cache_handler: could not connect to database");
|
|
return false;
|
|
}
|
|
mysql_select_db($db_name);
|
|
|
|
switch ($action) {
|
|
case 'read':
|
|
// save cache to database
|
|
$results = mysql_query("select CacheContents from CACHE_PAGES where CacheID='$CacheID'");
|
|
if(!$results) {
|
|
$smarty_obj->_trigger_error_msg("cache_handler: query failed.");
|
|
}
|
|
$row = mysql_fetch_array($results,MYSQL_ASSOC);
|
|
|
|
if($use_gzip && function_exists("gzuncompress")) {
|
|
$cache_contents = gzuncompress($row["CacheContents"]);
|
|
} else {
|
|
$cache_contents = $row["CacheContents"];
|
|
}
|
|
$return = $results;
|
|
break;
|
|
case 'write':
|
|
// save cache to database
|
|
|
|
if($use_gzip && function_exists("gzcompress")) {
|
|
// compress the contents for storage efficiency
|
|
$contents = gzcompress($cache_content);
|
|
} else {
|
|
$contents = $cache_content;
|
|
}
|
|
$results = mysql_query("replace into CACHE_PAGES values(
|
|
'$CacheID',
|
|
'".addslashes($contents)."')
|
|
");
|
|
if(!$results) {
|
|
$smarty_obj->_trigger_error_msg("cache_handler: query failed.");
|
|
}
|
|
$return = $results;
|
|
break;
|
|
case 'clear':
|
|
// clear cache info
|
|
if(empty($cache_id) && empty($compile_id) && empty($tpl_file)) {
|
|
// clear them all
|
|
$results = mysql_query("delete from CACHE_PAGES");
|
|
} else {
|
|
$results = mysql_query("delete from CACHE_PAGES where CacheID='$CacheID'");
|
|
}
|
|
if(!$results) {
|
|
$smarty_obj->_trigger_error_msg("cache_handler: query failed.");
|
|
}
|
|
$return = $results;
|
|
break;
|
|
default:
|
|
// error, unknown action
|
|
$smarty_obj->_trigger_error_msg("cache_handler: unknown action \"$action\"");
|
|
$return = false;
|
|
break;
|
|
}
|
|
mysql_close($link);
|
|
return $return;
|
|
|
|
}
|
|
|
|
?></programlisting>
|
|
</example>
|
|
</sect1>
|
|
|
|
<sect1 id="template.resources">
|
|
<title>Recursos (Resources)</title>
|
|
<para>
|
|
Os templates podem vir de uma variedade de fontes. Quando você exibe (display) ou
|
|
busca (fetch) um template, ou inclui um template de dentro de outro template, você
|
|
fornece um tipo de recurso, seguido pelo
|
|
caminho e nome do template apropriado. Se um
|
|
recurso não é dado explicitamente o valor de
|
|
<link linkend="variable.default.resource.type">$default_resource_type</link> é assumido.
|
|
</para>
|
|
<sect2 id="templates.from.template.dir">
|
|
<title>Templates partindo do $template_dir</title>
|
|
<para>
|
|
Templates a partir do $template_dir não exigem um recurso de template,
|
|
apesar de você usar o arquivo: resource for consistancy.
|
|
Apenas forneça o caminho para o template que você quer usar em relação ao diretório
|
|
root $template_dir.
|
|
</para>
|
|
<example>
|
|
<title>Usando templates partindo do $template_dir</title>
|
|
<programlisting>
|
|
// from PHP script
|
|
$smarty->display("index.tpl");
|
|
$smarty->display("admin/menu.tpl");
|
|
$smarty->display("file:admin/menu.tpl"); // Igual ao de cima
|
|
|
|
{* de dentro do template do Smarty *}
|
|
{include file="index.tpl"}
|
|
{include file="file:index.tpl"} {* igual ao de cima *}</programlisting>
|
|
</example>
|
|
</sect2>
|
|
<sect2 id="templates.from.any.dir">
|
|
<title>Templates partindo de qualquer diretório</title>
|
|
<para>
|
|
Os Templates de fora do $template_dir exigem o arquivo:
|
|
tipo de recurso do template,
|
|
seguido pelo caminho absoluto e nome do template.
|
|
</para>
|
|
<example>
|
|
<title>usando templates partindo de qualquer diretório</title>
|
|
<programlisting>
|
|
// de dentro do script PHP
|
|
$smarty->display("file:/export/templates/index.tpl");
|
|
$smarty->display("file:/path/to/my/templates/menu.tpl");
|
|
|
|
{* de dentro do template do Smarty *}
|
|
{include file="file:/usr/local/share/templates/navigation.tpl"}</programlisting>
|
|
</example>
|
|
|
|
<sect3 id="templates.windows.filepath">
|
|
<title>Caminhos de arquivos do Windows</title>
|
|
<para>
|
|
Se você está usando uma máquina windows, caminhos de arquivos normalmente incluem uma letra
|
|
do drive (C:) no começo do nome do caminho.
|
|
Esteja certo de usar "file:" no caminho para
|
|
evitar conflitos de nome e obter os resultados desejados.
|
|
</para>
|
|
<example>
|
|
<title>usando templates com caminhos de arquivo do windows</title>
|
|
<programlisting>
|
|
// de dentro do script PHP
|
|
$smarty->display("file:C:/export/templates/index.tpl");
|
|
$smarty->display("file:F:/path/to/my/templates/menu.tpl");
|
|
|
|
{* de dentro do template do Smarty *}
|
|
{include file="file:D:/usr/local/share/templates/navigation.tpl"}</programlisting>
|
|
</example>
|
|
</sect3>
|
|
</sect2>
|
|
|
|
<sect2 id="templates.from.elsewhere">
|
|
<title>Templates partindo de outras fontes</title>
|
|
<para>
|
|
Você pode resgatar templates usando qualquer fonte possível de você acessar com PHP: banco
|
|
de dados, sockets, LDAP, e assim por diante.
|
|
Você faz isto escrevendo as funções de plugin
|
|
de recurso e registrando elas com o Smarty.
|
|
</para>
|
|
|
|
<para>
|
|
Veja a seção <link linkend="plugins.resources">plugins de recurso</link>
|
|
para mais informação sobre as funções
|
|
que você deve fornecer.
|
|
</para>
|
|
|
|
<note>
|
|
<para>
|
|
Note que você pode ativar manualmente o recurso de <literal>arquivo</literal> embutido, mas não pode fornecer um recurso que busca templates a partir do sistema de arquivos de alguma outra forma registrando sob um outro nome de recurso.
|
|
<literal>file</literal> resource, but you can provide a resource
|
|
that fetches templates from the file system in some other way by
|
|
registering under another resource name.
|
|
</para>
|
|
</note>
|
|
<example>
|
|
<title>usando recursos customizáveis</title>
|
|
<programlisting>
|
|
// no script PHP
|
|
|
|
// ponha estas funções em algum lugar de sua aplicação
|
|
function db_get_template ($tpl_name, &$tpl_source, &$smarty_obj)
|
|
{
|
|
// faça o banco de dados chamar aqui para buscar o seu template,
|
|
// preenchendo o $tpl_source
|
|
$sql = new SQL;
|
|
$sql->query("select tpl_source
|
|
from my_table
|
|
where tpl_name='$tpl_name'");
|
|
if ($sql->num_rows) {
|
|
$tpl_source = $sql->record['tpl_source'];
|
|
return true;
|
|
} else {
|
|
return false;
|
|
}
|
|
}
|
|
|
|
function db_get_timestamp($tpl_name, &$tpl_timestamp, &$smarty_obj)
|
|
{
|
|
// faça o banco de dados chamar daqui para preencher a $tpl_timestamp.
|
|
$sql = new SQL;
|
|
$sql->query("select tpl_timestamp
|
|
from my_table
|
|
where tpl_name='$tpl_name'");
|
|
if ($sql->num_rows) {
|
|
$tpl_timestamp = $sql->record['tpl_timestamp'];
|
|
return true;
|
|
} else {
|
|
return false;
|
|
}
|
|
}
|
|
|
|
function db_get_secure($tpl_name, &$smarty_obj)
|
|
{
|
|
// assume-se que todos os templates são seguros
|
|
return true;
|
|
}
|
|
|
|
function db_get_trusted($tpl_name, &$smarty_obj)
|
|
{
|
|
// não usado para templates
|
|
}
|
|
|
|
// registrar o nome de recurso "db"
|
|
$smarty->register_resource("db", array("db_get_template",
|
|
"db_get_timestamp",
|
|
"db_get_secure",
|
|
"db_get_trusted"));
|
|
|
|
// usando o recurso a partir do script PHP
|
|
$smarty->display("db:index.tpl");
|
|
|
|
{* usando o recurso de dentro do template do Smarty *}
|
|
{include file="db:/extras/navigation.tpl"}</programlisting>
|
|
</example>
|
|
</sect2>
|
|
|
|
<sect2 id="default.template.handler.function">
|
|
<title>Função Manipuladora de Template Padrão</title>
|
|
<para>
|
|
Você pode especificar a função que é usada para devolver o conteúdo do template no evento
|
|
em que o template não pode ser devolvido de seu recurso. Um uso disto é para criar templates
|
|
que não existem "on-the-fly"
|
|
(templates cujo conteúdo flutua muito, bastante variável).
|
|
</para>
|
|
<example>
|
|
<title>usando a função manipuladora de template padrão</title>
|
|
<programlisting>
|
|
<?php
|
|
// ponha esta função em algum lugar de sua aplicação
|
|
|
|
function make_template ($resource_type, $resource_name, &$template_source, &$template_timestamp, &$smarty_obj)
|
|
{
|
|
if( $resource_type == 'file' ) {
|
|
if ( ! is_readable ( $resource_name )) {
|
|
// cria um arquivo de template, retorna o conteúdo.
|
|
$template_source = "This is a new template.";
|
|
$template_timestamp = time();
|
|
$smarty_obj->_write_file($resource_name,$template_source);
|
|
return true;
|
|
}
|
|
} else {
|
|
// não é arquivo
|
|
return false;
|
|
}
|
|
}
|
|
|
|
// defina a manipuladora padrão
|
|
$smarty->default_template_handler_func = 'make_template';
|
|
?></programlisting>
|
|
</example>
|
|
</sect2>
|
|
</sect1>
|
|
</chapter>
|
|
<!-- Keep this comment at the end of the file
|
|
Local variables:
|
|
mode: sgml
|
|
sgml-omittag:t
|
|
sgml-shorttag:t
|
|
sgml-minimize-attributes:nil
|
|
sgml-always-quote-attributes:t
|
|
sgml-indent-step:1
|
|
sgml-indent-data:t
|
|
indent-tabs-mode:nil
|
|
sgml-parent-document:nil
|
|
sgml-default-dtd-file:"../../../../manual.ced"
|
|
sgml-exposed-tags:nil
|
|
sgml-local-catalogs:nil
|
|
sgml-local-ecat-files:nil
|
|
End:
|
|
vim600: syn=xml fen fdm=syntax fdl=2 si
|
|
vim: et tw=78 syn=sgml
|
|
vi: ts=1 sw=1
|
|
-->
|