mirror of
https://github.com/smarty-php/smarty.git
synced 2026-02-13 18:40:18 +01:00
803 lines
29 KiB
XML
803 lines
29 KiB
XML
<?xml version="1.0" encoding="iso-8859-1"?>
|
|
<!-- $Revision$ -->
|
|
<chapter id="plugins">
|
|
<title>Extendendo a Smarty com Plugins</title>
|
|
<para>
|
|
A Versão 2.0 introduziu a arquitetura de plugin que é usada para quase todas as
|
|
funcionalidades customizáveis da Smarty. Isto inclui:
|
|
<itemizedlist spacing="compact">
|
|
<listitem><simpara>funções</simpara></listitem>
|
|
<listitem><simpara>modificadores</simpara></listitem>
|
|
<listitem><simpara>funções de bloco</simpara></listitem>
|
|
<listitem><simpara>funções de compilador</simpara></listitem>
|
|
<listitem><simpara>prefiltros</simpara></listitem>
|
|
<listitem><simpara>posfiltros</simpara></listitem>
|
|
<listitem><simpara>filtros de saída</simpara></listitem>
|
|
<listitem><simpara>recursos</simpara></listitem>
|
|
<listitem><simpara>inserir</simpara></listitem>
|
|
</itemizedlist>
|
|
Com a exceção de recursos, a compatibilidade com a forma antiga de funções de
|
|
manipulador de registro via register_* API é preservada. Se você não usou o API mas no lugar disso
|
|
modificou as variáveis de classe <literal>$custom_funcs</literal>, <literal>$custom_mods</literal>, e
|
|
outras diretamente, então você vai
|
|
precisar ajustar seus scripts para ou usar API ou converter suas
|
|
funcionalidade customizadas em plugins.
|
|
</para>
|
|
|
|
<sect1 id="plugins.howto">
|
|
<title>Como os Plugins Funcionam</title>
|
|
<para>
|
|
Plugins são sempre lidos quando requisitados. Apenas os modificadores específicos,
|
|
funções, recursos, etc convocados em scripts de template serão lidos. Além disso, cada plugin
|
|
é lido apenas uma vez, mesmo se você tem várias instâncias diferentes da Smarty rodando na mesma
|
|
requisição.
|
|
</para>
|
|
<para>
|
|
Pre/posfiltros e filtros de saída são uma parte de um caso especial. Visto que eles não são mencionados
|
|
nos templates, eles devem ser registrados ou lidos explicitamente via funções de API antes do template
|
|
ser processado.
|
|
A ordem em que multiplos filtros do mesmo
|
|
tipo são executados dependem da ordem em que eles são registrados ou lidos.
|
|
</para>
|
|
<para>
|
|
O <link linkend="variable.plugins.dir">diretório de plugins</link>
|
|
pode ser uma string contendo um caminho ou um array
|
|
contendo multiplos caminhos. Para instalar um plugin,
|
|
simplesmente coloque-o em um dos diretórios e a Smarty irá usá-lo automaticamente.
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 id="plugins.naming.conventions">
|
|
<title>Convenções de Aparência</title>
|
|
<para>
|
|
Arquivos e funções de Plugin devem seguir uma convenção de aparência muito específica
|
|
a fim de ser localizada pela Smarty.
|
|
</para>
|
|
<para>
|
|
Os arquivos de plugin devem ser nomeados da sequinte forma:
|
|
<blockquote>
|
|
<para>
|
|
<filename>
|
|
<replaceable>tipo</replaceable>.<replaceable>nome</replaceable>.php
|
|
</filename>
|
|
</para>
|
|
</blockquote>
|
|
</para>
|
|
<para>
|
|
Onde <literal>tipo</literal> é um dos seguintes tipos de plugin:
|
|
<itemizedlist spacing="compact">
|
|
<listitem><simpara>function</simpara></listitem>
|
|
<listitem><simpara>modifier</simpara></listitem>
|
|
<listitem><simpara>block</simpara></listitem>
|
|
<listitem><simpara>compiler</simpara></listitem>
|
|
<listitem><simpara>prefilter</simpara></listitem>
|
|
<listitem><simpara>postfilter</simpara></listitem>
|
|
<listitem><simpara>outputfilter</simpara></listitem>
|
|
<listitem><simpara>resource</simpara></listitem>
|
|
<listitem><simpara>insert</simpara></listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
<para>
|
|
E <literal>nome</literal> seria um identificador válido (letras,
|
|
números, e underscores apenas).
|
|
</para>
|
|
<para>
|
|
Alguns exemplos: <literal>function.html_select_date.php</literal>,
|
|
<literal>resource.db.php</literal>,
|
|
<literal>modifier.spacify.php</literal>.
|
|
</para>
|
|
<para>
|
|
As funções de plugin dentro dos arquivos do plugin devem ser nomeadas da seguinte forma:
|
|
<blockquote>
|
|
<para>
|
|
<function>smarty_<replaceable>tipo</replaceable>_<replaceable>nome</replaceable></function>
|
|
</para>
|
|
</blockquote>
|
|
</para>
|
|
<para>
|
|
O significado de <literal>tipo</literal> e
|
|
<literal>nome</literal> são os mesmos de antes.
|
|
</para>
|
|
<para>
|
|
A Smarty mostrará mensagens de erro apropriadas se o arquivo de plugins que é necessário não é encontrado,
|
|
ou se o arquivo ou a função de plugin
|
|
estão nomeadas inadequadamente.
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 id="plugins.writing">
|
|
<title>Escrevendo Plugins</title>
|
|
<para>
|
|
Os Plugins podem ser ou lidos pela Smarty automaticamente do sistema de arquivos ou eles podem
|
|
ser registrados no tempo de execução via uma das funções
|
|
de API register_* . Eles podem também ser
|
|
com o uso da função API unregister_* .
|
|
</para>
|
|
<para>
|
|
Para os plugins que são registrados no tempo de execução, o nome da(s) função(ões) de plugin
|
|
não têm que seguir a convenção de aparência.
|
|
</para>
|
|
<para>
|
|
Se um plugin depende de alguma funcionalidade fornecida por um outro plugin (como é o caso com alguns
|
|
plugins embutidos com a Smarty),
|
|
então a forma apropriada para ler o plugin necessário é esta:
|
|
</para>
|
|
<programlisting>
|
|
require_once $smarty->_get_plugin_filepath('function', 'html_options');</programlisting>
|
|
<para>
|
|
Como uma regra geral, o objeto da Smarty é sempre passado para os plugins como o último parâmetro
|
|
(com duas exceções: modificadores não passam o objeto da Smarty em tudo e blocks passam
|
|
<parameter>&$repeat</parameter> depois do objeto da Smarty
|
|
para manter compatibilidade a antigas
|
|
versões da Smarty).
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 id="plugins.functions"><title>Funções de Template</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>void <function>smarty_function_<replaceable>name</replaceable></function></funcdef>
|
|
<paramdef>array <parameter>$params</parameter></paramdef>
|
|
<paramdef>object <parameter>&$smarty</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
Todos os atributos passados para as funções de template a
|
|
partir do template estão contidas em
|
|
<parameter>$params</parameter> como um array associativo. Ou acessa esses valores
|
|
diretamente i.e <varname>$params['start']</varname> ou usa
|
|
<varname>extract($params)</varname> para
|
|
importá-los para dentro da tabela símbolo.
|
|
</para>
|
|
<para>
|
|
A saída (valor de retorno) da função será substituída no lugar da tag da função no template
|
|
(a função <function>fetch</function>, por exemplo). Alternativamente, a função pode simplesmente executar
|
|
alguma outra tarefa sem ter alguma saída
|
|
(a função <function>assign</function>).
|
|
</para>
|
|
<para>
|
|
Se a função precisa passar valores a algumas variáveis para o template ou utilizar alguma outra funcionalidade
|
|
fornecida com a Smarty, ela pode usar
|
|
o objeto <parameter>$smarty</parameter> fornecido para fazer isso.
|
|
</para>
|
|
<para>
|
|
Veja também:
|
|
<link linkend="api.register.function">register_function()</link>,
|
|
<link linkend="api.unregister.function">unregister_function()</link>.
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title>função de plugin com saída</title>
|
|
<programlisting>
|
|
<?php
|
|
/*
|
|
* Smarty plugin
|
|
* -------------------------------------------------------------
|
|
* File: function.eightball.php
|
|
* Type: function
|
|
* Name: eightball
|
|
* Purpose: outputs a random magic answer
|
|
* -------------------------------------------------------------
|
|
*/
|
|
function smarty_function_eightball($params, &$smarty)
|
|
{
|
|
$answers = array('Yes',
|
|
'No',
|
|
'No way',
|
|
'Outlook not so good',
|
|
'Ask again soon',
|
|
'Maybe in your reality');
|
|
|
|
$result = array_rand($answers);
|
|
return $answers[$result];
|
|
}
|
|
?></programlisting>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
que pode ser usada no template da seguinte forma:
|
|
</para>
|
|
<programlisting>
|
|
Pergunta: Nós sempre teremos tempo para viajar?
|
|
Resposta: {eightball}.</programlisting>
|
|
<para>
|
|
<example>
|
|
<title>função de plugin sem saída</title>
|
|
<programlisting>
|
|
<?php
|
|
/*
|
|
* Smarty plugin
|
|
* -------------------------------------------------------------
|
|
* File: function.assign.php
|
|
* Type: function
|
|
* Name: assign
|
|
* Purpose: assign a value to a template variable
|
|
* -------------------------------------------------------------
|
|
*/
|
|
function smarty_function_assign($params, &$smarty)
|
|
{
|
|
extract($params);
|
|
|
|
if (empty($var)) {
|
|
$smarty->trigger_error("assign: missing 'var' parameter");
|
|
return;
|
|
}
|
|
|
|
if (!in_array('value', array_keys($params))) {
|
|
$smarty->trigger_error("assign: missing 'value' parameter");
|
|
return;
|
|
}
|
|
|
|
$smarty->assign($var, $value);
|
|
}
|
|
?></programlisting>
|
|
</example>
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 id="plugins.modifiers"><title>Modifiers</title>
|
|
<para>
|
|
Modificadores são funções que são aplicadas a uma variável no template antes dela ser mostrada
|
|
ou usada em algum outro contexto.
|
|
Modificadores podem ser encadeados juntos.
|
|
</para>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>mixed <function>smarty_modifier_<replaceable>name</replaceable></function></funcdef>
|
|
<paramdef>mixed <parameter>$value</parameter></paramdef>
|
|
<paramdef>[mixed <parameter>$param1</parameter>, ...]</paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
O primeiro parâmetro para o plugin midificador é o valor em que o modificador é suposto
|
|
operar. O resto dos parâmetros podem ser opcionais,
|
|
dependendo de qual tipo de operação é para
|
|
ser executada.
|
|
</para>
|
|
<para>
|
|
O modificador deve retornar o resultado de seu processamento.
|
|
</para>
|
|
<para>
|
|
Veja também:
|
|
<link linkend="api.register.modifier">register_modifier()</link>,
|
|
<link linkend="api.unregister.modifier">unregister_modifier()</link>.
|
|
</para>
|
|
<example>
|
|
<title>Plugin modificador simples</title>
|
|
<para>
|
|
Este plugin basiamente é um alias de uma
|
|
função do PHP. Ele não tem nenhum parâmetro adicional.
|
|
</para>
|
|
<programlisting>
|
|
<?php
|
|
/*
|
|
* Smarty plugin
|
|
* -------------------------------------------------------------
|
|
* File: modifier.capitalize.php
|
|
* Type: modifier
|
|
* Name: capitalize
|
|
* Purpose: capitalize words in the string
|
|
* -------------------------------------------------------------
|
|
*/
|
|
function smarty_modifier_capitalize($string)
|
|
{
|
|
return ucwords($string);
|
|
}
|
|
?></programlisting>
|
|
</example>
|
|
<para></para>
|
|
<example>
|
|
<title>Plugin modificador mais complexo</title>
|
|
<programlisting>
|
|
<?php
|
|
/*
|
|
* Smarty plugin
|
|
* -------------------------------------------------------------
|
|
* File: modifier.truncate.php
|
|
* Type: modifier
|
|
* Name: truncate
|
|
* Purpose: Truncate a string to a certain length if necessary,
|
|
* optionally splitting in the middle of a word, and
|
|
* appending the $etc string.
|
|
* -------------------------------------------------------------
|
|
*/
|
|
function smarty_modifier_truncate($string, $length = 80, $etc = '...',
|
|
$break_words = false)
|
|
{
|
|
if ($length == 0)
|
|
return '';
|
|
|
|
if (strlen($string) > $length) {
|
|
$length -= strlen($etc);
|
|
$fragment = substr($string, 0, $length+1);
|
|
if ($break_words)
|
|
$fragment = substr($fragment, 0, -1);
|
|
else
|
|
$fragment = preg_replace('/\s+(\S+)?$/', '', $fragment);
|
|
return $fragment.$etc;
|
|
} else
|
|
return $string;
|
|
}
|
|
?></programlisting>
|
|
</example>
|
|
</sect1>
|
|
|
|
<sect1 id="plugins.block.functions"><title>Block Functions</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>void <function>smarty_block_<replaceable>name</replaceable></function></funcdef>
|
|
<paramdef>array <parameter>$params</parameter></paramdef>
|
|
<paramdef>mixed <parameter>$content</parameter></paramdef>
|
|
<paramdef>object <parameter>&$smarty</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
Funções de Block são funções da forma: {func} .. {/func}. Em outras palavras, ele enclausura
|
|
um bloco de template e opera no conteúdo deste bloco. Funções de Block tem precedência sobre
|
|
funções customizadas com mesmo nome,
|
|
assim, você não pode ter ambas, função customizável {func} e
|
|
função de Bloco {func} .. {/func}.
|
|
</para>
|
|
<para>
|
|
Por definição a implementação de sua função é chamada duas vezes pela Smarty: uma vez pela tag de abertura,
|
|
e outra pela tag de fechamento
|
|
(veja <literal>&$repeat</literal> abaixo para como mudar isto).
|
|
</para>
|
|
<para>
|
|
Apenas a tag de abertura da função de bloco pode ter atributos.
|
|
Todos os atributos passados para as funções de
|
|
template estão contidos em <parameter>$params</parameter> como um array associativo. Você pode ou acessar
|
|
esses valores diretamente, i.e. <varname>$params['start']</varname>
|
|
ou usar <varname>extract($params)</varname>
|
|
para importá-los para dentro da tabela símbolo. Os atributos da tag de
|
|
abertura são também acessíveis a sua função
|
|
quando processando a tag de fechamento.
|
|
</para>
|
|
<para>
|
|
O valor da variável <parameter>$content</parameter>
|
|
depende de que se sua função é chamada pela tag de
|
|
fechamento ou de abertura. Caso seja a de abertura, ele será
|
|
<literal>null</literal>, se for a de fechamento
|
|
o valor será do conteúdo do bloco de template.
|
|
Note que o bloco de template já terá sido processado pela
|
|
Smarty, então tudo que você receberá é saída do template, não o template original.
|
|
</para>
|
|
|
|
<para>
|
|
O parâmetro <parameter>&$repeat</parameter> é passado por
|
|
referência para a função de implementação
|
|
e fornece uma possibilidade para ele controlar quantas
|
|
vezes o bloco é mostrado. Por definição
|
|
<parameter>$repeat</parameter> é <literal>true</literal> na primeira chamada da block-function
|
|
(a tag de abertura do bloco) e <literal>false</literal>
|
|
em todas as chamadas subsequentes à função de bloco
|
|
(a tag de fechamento do bloco). Cada vez que a
|
|
implementação da função retorna com o <parameter>&$repeat</parameter>
|
|
sendo true, o conteúdo entre {func} .. {/func} é avaliado
|
|
e a implementação da função é chamada novamente com
|
|
o novo conteúdo do bloco no parâmetro <parameter>$content</parameter>.
|
|
|
|
</para>
|
|
|
|
<para>
|
|
Se você tem funções de bloco aninhadas, é possível
|
|
descobrir qual é a função de bloco pai acessando
|
|
a variável <varname>$smarty->_tag_stack</varname>. Apenas faça um var_dump()
|
|
nela e a estrutura estaria visível.
|
|
</para>
|
|
<para>
|
|
See also:
|
|
<link linkend="api.register.block">register_block()</link>,
|
|
<link linkend="api.unregister.block">unregister_block()</link>.
|
|
</para>
|
|
<example>
|
|
<title>função de bloco</title>
|
|
<programlisting>
|
|
<?php
|
|
/*
|
|
* Smarty plugin
|
|
* -------------------------------------------------------------
|
|
* File: block.translate.php
|
|
* Type: block
|
|
* Name: translate
|
|
* Purpose: translate a block of text
|
|
* -------------------------------------------------------------
|
|
*/
|
|
function smarty_block_translate($params, $content, &$smarty)
|
|
{
|
|
if (isset($content)) {
|
|
$lang = $params['lang'];
|
|
// do some intelligent translation thing here with $content
|
|
return $translation;
|
|
}
|
|
}</programlisting>
|
|
</example>
|
|
</sect1>
|
|
|
|
<sect1 id="plugins.compiler.functions"><title>Funções Compiladoras</title>
|
|
<para>
|
|
Funções compiladoras só são chamadas durante a compilação do template.
|
|
Elas são úteis para injeção de código PHP ou conteúdo estático time-sensitive
|
|
dentro do template. Se há ambos, uma função
|
|
compiladora e uma função customizável
|
|
registrada sob o mesmo nome, a função compiladora tem precedência.
|
|
</para>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>mixed <function>smarty_compiler_<replaceable>name</replaceable></function></funcdef>
|
|
<paramdef>string <parameter>$tag_arg</parameter></paramdef>
|
|
<paramdef>object <parameter>&$smarty</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
À função compiladora são passados dois parâmetros:
|
|
a tag string de argumento da tag - basicamente, tudo a partir
|
|
do nome da função até o delimitador de fechamento, e o objeto da Smarty. É suposto que retorna o código PHP
|
|
para ser injetado dentro do template compilado.
|
|
</para>
|
|
<para>
|
|
See also
|
|
<link linkend="api.register.compiler.function">register_compiler_function()</link>,
|
|
<link linkend="api.unregister.compiler.function">unregister_compiler_function()</link>.
|
|
</para>
|
|
<example>
|
|
<title>função compiladora simples</title>
|
|
<programlisting>
|
|
<?php
|
|
/*
|
|
* Smarty plugin
|
|
* -------------------------------------------------------------
|
|
* File: compiler.tplheader.php
|
|
* Type: compiler
|
|
* Name: tplheader
|
|
* Purpose: Output header containing the source file name and
|
|
* the time it was compiled.
|
|
* -------------------------------------------------------------
|
|
*/
|
|
function smarty_compiler_tplheader($tag_arg, &$smarty)
|
|
{
|
|
return "\necho '" . $smarty->_current_file . " compiled at " . date('Y-m-d H:M'). "';";
|
|
}
|
|
?></programlisting>
|
|
<para>
|
|
Esta função pode ser chamada em um template da seguinte forma:
|
|
</para>
|
|
<programlisting>
|
|
{* esta função é executada somente no tempo de compilação *}
|
|
{tplheader}</programlisting>
|
|
<para>
|
|
O código PHP resultante no template compilado seria algo assim:
|
|
</para>
|
|
<programlisting>
|
|
<php
|
|
echo 'index.tpl compiled at 2002-02-20 20:02';
|
|
?></programlisting>
|
|
</example>
|
|
</sect1>
|
|
|
|
<sect1 id="plugins.prefilters.postfilters">
|
|
<title>Prefiltros/Posfiltros</title>
|
|
<para>
|
|
Plugins Prefilter e postfilter são muito similares
|
|
em conceito; onde eles diferem é na execução -- mais
|
|
precisamente no tempo de suas execuções.
|
|
</para>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>string <function>smarty_prefilter_<replaceable>name</replaceable></function></funcdef>
|
|
<paramdef>string <parameter>$source</parameter></paramdef>
|
|
<paramdef>object <parameter>&$smarty</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
Prefilters são usados para processar o fonte do template
|
|
imediatamente antes da compilação. O primeiro parâmetro da
|
|
função de prefilter é o fonte do template, possivelmente modificado por alguns outros prefilters. O Plugin
|
|
é suposto retornar o fonte modificado. Note que este fonte não é salvo em lugar nenhum, ele só é usado para
|
|
a compilação.
|
|
</para>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>string <function>smarty_postfilter_<replaceable>name</replaceable></function></funcdef>
|
|
<paramdef>string <parameter>$compiled</parameter></paramdef>
|
|
<paramdef>object <parameter>&$smarty</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
Postfilters são usados para processar a saída compilada do template (o código PHP) imediatamente após
|
|
a compilação ser feita e antes do template compilado ser
|
|
salvo no sistema de arquivo. O primeiro parâmetro
|
|
para a função postfilter é o código do template compilado,
|
|
possivelmente modificado por outros postfilters.
|
|
O plugin é suposto retornar a versão modificada deste código.
|
|
</para>
|
|
<example>
|
|
<title>Plugin prefilter</title>
|
|
<programlisting>
|
|
<?php
|
|
/*
|
|
* Smarty plugin
|
|
* -------------------------------------------------------------
|
|
* File: prefilter.pre01.php
|
|
* Type: prefilter
|
|
* Name: pre01
|
|
* Purpose: Convert html tags to be lowercase.
|
|
* -------------------------------------------------------------
|
|
*/
|
|
function smarty_prefilter_pre01($source, &$smarty)
|
|
{
|
|
return preg_replace('!<(\w+)[^>]+>!e', 'strtolower("$1")', $source);
|
|
}
|
|
?></programlisting>
|
|
</example>
|
|
<para></para>
|
|
<example>
|
|
<title>Plugin postfilter</title>
|
|
<programlisting>
|
|
<?php
|
|
/*
|
|
* Smarty plugin
|
|
* -------------------------------------------------------------
|
|
* File: postfilter.post01.php
|
|
* Type: postfilter
|
|
* Name: post01
|
|
* Purpose: Output code that lists all current template vars.
|
|
* -------------------------------------------------------------
|
|
*/
|
|
function smarty_postfilter_post01($compiled, &$smarty)
|
|
{
|
|
$compiled = "<pre>\n<?php print_r(\$this->get_template_vars()); ?>\n</pre>" . $compiled;
|
|
return $compiled;
|
|
}
|
|
?></programlisting>
|
|
</example>
|
|
</sect1>
|
|
|
|
<sect1 id="plugins.outputfilters"><title>Filtros de saída</title>
|
|
<para>
|
|
Filtros de saída operam na saída do template, depois que o template é lido e executado, mas
|
|
antes a saída é mostrada.
|
|
</para>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>string <function>smarty_outputfilter_<replaceable>name</replaceable></function></funcdef>
|
|
<paramdef>string <parameter>$template_output</parameter></paramdef>
|
|
<paramdef>object <parameter>&$smarty</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
O primeiro parâmetro para a função do filtro de saída é a saída do template que precisa ser processada, e
|
|
o segundo parâmetro é a instância da Smarty invocando o plugin.
|
|
O plugin deve fazer o precessamento e
|
|
retornar os resultados.
|
|
</para>
|
|
<example>
|
|
<title>output filter plugin</title>
|
|
<programlisting>
|
|
/*
|
|
* Smarty plugin
|
|
* -------------------------------------------------------------
|
|
* File: outputfilter.protect_email.php
|
|
* Type: outputfilter
|
|
* Name: protect_email
|
|
* Purpose: Converts @ sign in email addresses to %40 as
|
|
* a simple protection against spambots
|
|
* -------------------------------------------------------------
|
|
*/
|
|
function smarty_outputfilter_protect_email($output, &$smarty)
|
|
{
|
|
return preg_replace('!(\S+)@([a-zA-Z0-9\.\-]+\.([a-zA-Z]{2,3}|[0-9]{1,3}))!',
|
|
'$1%40$2', $output);
|
|
}
|
|
</programlisting>
|
|
</example>
|
|
</sect1>
|
|
|
|
<sect1 id="plugins.resources"><title>Recursos (Resources)</title>
|
|
<para>
|
|
Os plugins de Recursos são como uma forma genérica de fornecer códigos fontes de template
|
|
ou componentes de script PHP para a Smarty. Alguns exemplos de recursos:
|
|
banco de dados, LDAP, memória compartilhada, sockets, e assim por diante.
|
|
</para>
|
|
|
|
<para>
|
|
Há um total de 4 funções que precisam estar registradas
|
|
para cada tipo de recurso. Cada função receberá
|
|
o recurso requisitado como o primeiro parâmetro e o objeto da Smarty como o último parâmetro. O resto
|
|
dos parâmetros dependem da função.
|
|
</para>
|
|
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>bool <function>smarty_resource_<replaceable>name</replaceable>_source</function></funcdef>
|
|
<paramdef>string <parameter>$rsrc_name</parameter></paramdef>
|
|
<paramdef>string <parameter>&$source</parameter></paramdef>
|
|
<paramdef>object <parameter>&$smarty</parameter></paramdef>
|
|
</funcprototype>
|
|
<funcprototype>
|
|
<funcdef>bool <function>smarty_resource_<replaceable>name</replaceable>_timestamp</function></funcdef>
|
|
<paramdef>string <parameter>$rsrc_name</parameter></paramdef>
|
|
<paramdef>int <parameter>&$timestamp</parameter></paramdef>
|
|
<paramdef>object <parameter>&$smarty</parameter></paramdef>
|
|
</funcprototype>
|
|
<funcprototype>
|
|
<funcdef>bool <function>smarty_resource_<replaceable>name</replaceable>_secure</function></funcdef>
|
|
<paramdef>string <parameter>$rsrc_name</parameter></paramdef>
|
|
<paramdef>object <parameter>&$smarty</parameter></paramdef>
|
|
</funcprototype>
|
|
<funcprototype>
|
|
<funcdef>bool <function>smarty_resource_<replaceable>name</replaceable>_trusted</function></funcdef>
|
|
<paramdef>string <parameter>$rsrc_name</parameter></paramdef>
|
|
<paramdef>object <parameter>&$smarty</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
|
|
<para>
|
|
A primeira função deve devolver o recurso. Seu segundo parâmetro é uma variável passada por
|
|
referência onde o resultado seria armazenado.
|
|
A função deve retornar <literal>true</literal> se
|
|
ela está apta a devolver com sucesso o recurso e
|
|
caso contrário retorna <literal>false</literal>.
|
|
</para>
|
|
|
|
<para>
|
|
A segunda função deve devolver a última modificação do
|
|
recurso requisitado (como um timestamp Unix).
|
|
O segundo parâmetro é uma variável passada por referência onde o timestamp seria armazenado.
|
|
A função deve retornar <literal>true</literal>
|
|
se o timestamp poderia ser determinado com sucesso,
|
|
e caso contrário retornaria <literal>false</literal>.
|
|
</para>
|
|
|
|
<para>
|
|
A terceira função deve retornar <literal>true</literal> ou
|
|
<literal>false</literal>, dependendo do recurso requisitado
|
|
está seguro ou não. Esta função é usada
|
|
apenas para recursos de template mas ainda assim seria definida.
|
|
</para>
|
|
|
|
<para>
|
|
A quarta função deve retornar <literal>true</literal>
|
|
ou <literal>false</literal>, dependendo
|
|
do recurso requisitado ser confiável ou não.
|
|
Esta função é usada apenas para componentes de
|
|
script PHP requisitados pelas tags <command>include_php</command> ou
|
|
<command>insert</command> com o atributo <structfield>src</structfield>.
|
|
Entretanto, ela ainda assim mesmo seria definida para os recursos de template.
|
|
</para>
|
|
<para>
|
|
Veja também:
|
|
<link linkend="api.register.resource">register_resource()</link>,
|
|
<link linkend="api.unregister.resource">unregister_resource()</link>.
|
|
</para>
|
|
<example>
|
|
<title>Plugin resource (recurso)</title>
|
|
<programlisting>
|
|
<?php
|
|
/*
|
|
* Smarty plugin
|
|
* -------------------------------------------------------------
|
|
* File: resource.db.php
|
|
* Type: resource
|
|
* Name: db
|
|
* Purpose: Fetches templates from a database
|
|
* -------------------------------------------------------------
|
|
*/
|
|
function smarty_resource_db_source($tpl_name, &$tpl_source, &$smarty)
|
|
{
|
|
// do database call here to fetch your template,
|
|
// populating $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 smarty_resource_db_timestamp($tpl_name, &$tpl_timestamp, &$smarty)
|
|
{
|
|
// faz o banco de dados chamar aqui para preencher $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 smarty_resource_db_secure($tpl_name, &$smarty)
|
|
{
|
|
// assume que todos os templates são seguros
|
|
return true;
|
|
}
|
|
|
|
function smarty_resource_db_trusted($tpl_name, &$smarty)
|
|
{
|
|
// não usado para templates
|
|
}
|
|
?></programlisting>
|
|
</example>
|
|
</sect1>
|
|
|
|
<sect1 id="plugins.inserts"><title>Inserts</title>
|
|
<para>
|
|
Plugins Insert são usados para implementar funções que são invocadas por tags
|
|
<link linkend="language.function.insert"><command>insert</command></link>
|
|
no template.
|
|
</para>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>string <function>smarty_insert_<replaceable>name</replaceable></function></funcdef>
|
|
<paramdef>array <parameter>$params</parameter></paramdef>
|
|
<paramdef>object <parameter>&$smarty</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
O primeiro parâmetro para a função é um array
|
|
associativo de atributos passados para o
|
|
insert. Ou acessa esses valores diretamente,
|
|
i.e. <varname>$params['start']</varname> ou usa
|
|
<varname>extract($params)</varname> para importá-los para dentro da tabela símbolo.
|
|
</para>
|
|
<para>
|
|
A função insert deve retornar o
|
|
resultado que será substituído no lugar da tag
|
|
<command>insert</command> no template.
|
|
</para>
|
|
<example>
|
|
<title>Plugin insert</title>
|
|
<programlisting>
|
|
<?php
|
|
/*
|
|
* Smarty plugin
|
|
* -------------------------------------------------------------
|
|
* File: insert.time.php
|
|
* Type: time
|
|
* Name: time
|
|
* Purpose: Inserts current date/time according to format
|
|
* -------------------------------------------------------------
|
|
*/
|
|
function smarty_insert_time($params, &$smarty)
|
|
{
|
|
if (empty($params['format'])) {
|
|
$smarty->trigger_error("insert time: missing 'format' parameter");
|
|
return;
|
|
}
|
|
|
|
$datetime = strftime($params['format']);
|
|
return $datetime;
|
|
}
|
|
?></programlisting>
|
|
</example>
|
|
</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
|
|
-->
|