/documentation/pt_BR/getting-started.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 1.13 Maintainer: fernandoc Status: ready -->

<part id="getting.started">
 <title>Iniciando</title>

 <chapter id="what.is.smarty">
   <title>O que é o Smarty?</title>
   <para>
    O Smarty é um sistema de templates para PHP. Mais especificamente, ele fornece uma maneira 
	fácil de controlar a separação da aplicação lógica e o conteúdo de sua apresentação. Isto é 
	melhor descrito em uma situação onde o programador da aplicação e o designer do template executam 
	diferentes funções, ou na maioria dos casos não são a mesma pessoa.
    
   </para>
   <para>
    Por exemplo, digamos que você 
	está criando uma página para web para mostrar um artigo de um jornal. O autor, a manchete, 
	a conclusão e o corpo do artigo são elementos de conteúdo, eles não contém informação alguma 
	sobre como eles devem ser mostrados. Ele são enviados ao Smarty pela aplicação, então o designer 
	do template edita o template e usa uma combinação de tags HTML e tags de templates para formatar 
	a apresentação destes elementos (tabelas HTML, cores de fundo, tamanhos de fontes, folhas de estilos, etc.). 
	Se algum dia o programador precisar alterar a maneira como o conteúdo do artigo é tratado (uma mudança na 
	lógica da aplicação). Esta mudança não afeta o design do template, o conteúdo será enviado ao template 
	exatamente da mesma forma. De modo semelhante, se o designer do template quiser redesenhar completamente 
	os templates, não é necessária nenhuma alteração na lógica da aplicação. Sendo assim, o programador 
	pode fazer mudanças na lógica da aplicação sem a necessidade de reestruturar os templates, e o designer 
	do template pode fazer mudanças nos templates sem alterar a lógica da aplicação.
	</para>
	<para>
    Um objetivo do projeto Smarty é a separação da lógica do negócio e da lógica da apresentação. 
	Isto significa que os templates podem certamente conter a lógica sob a circunstância que é somente 
	para  apresentação. Alguns exemplos são: a inclusão de outros templates, alternação de cores nas linhas 
	das tabelas, colocar o texto de uma variável em maiúsculo, percorrer uma matriz de dados e mostrá-la, etc. 
	são todos exemplos de apresentação lógica. Isto não significa que o Smarty força a separação da lógica de 
	negócios e da lógica de apresentação. O Smarty não tem conhecimento do que é o que em sua aplicação, portanto 
	colocar sua a lógica de negócio no template é problema seu. Caso você deseje que não haja <emphasis>nenhuma</emphasis> lógica 
	em seus templates você pode certamente fazer isso trocando o conteúdo para textos e variáveis somente.
<!-- ficou legal o texto abaixo, mas não segue exatamente toda tradução, espero aprovação do meu acima, ou mistura entre os dois: 
	Agora um resumo sobre o que o Smarty faz e NÃO faz. O Smarty não tenta separar completamente
	a lógica dos templates. Não há problema com a lógica em seus templates sob a condição de que 
	esta lógica seja estritamente para apresentação. Uma palavra de aviso: mantenha a lógica
	fora dos templates, e a lógica da apresentação fora da aplicação. Isto definitivamente
	manterá as coisas mais manipuláveis
	e escaláveis para o futuro próximo. -->
	</para>
	<para>
    Um dos aspectos únicos do Smarty é seu sistema de compilação de templates. O Smarty lê os arquivos 
	de templates e cria scripts PHP à partir deles. Uma vez criados, eles são executados sem ser necessário 
	uma outra compilação do template novamente. Com isso, os arquivos de template não são 'parseados'(analisados) 
	toda vez que um template é solicitado, e cada template tem a total vantagem de soluções de cache do 
	compilador PHP, tais como: Zend Accelerator (<ulink url="&url.zend;">&url.zend;</ulink>) ou PHP Accelerator
	(<ulink url="&url.ion-accel;">&url.ion-accel;</ulink>).
   </para>
   <para>
    Algumas das características do Smarty:
   </para>
   <itemizedlist>
    <listitem>
     <para>
      Ele é extremamente rápido.
     </para>
    </listitem>
    <listitem>
     <para>
      Ele é eficiente visto que o interpretador do PHP faz o trabalho mais pesado.
     </para>
    </listitem>
    <listitem>
     <para>
      Sem elevadas interpretações de template, apenas compila uma vez.
     </para>
    </listitem>
    <listitem>
     <para>
      Ele está atento para só recompilar os arquivos de template que foram mudados.
     </para>
    </listitem>
    <listitem>
     <para>
      Você pode fazer <link linkend="language.custom.functions">funções próprias</link>
      e seus próprios <link linkend="language.modifiers">modificadores de variáveis</link>, assim
      a linguagem de templates é extremamente extensível.
     </para>
    </listitem>
    <listitem>
     <para>
      <link linkend="variable.left.delimiter">Delimitadores de tag</link> 
      configuráveis, sendo assim você pode usar {}, {{}}, &lt;!--{}--&gt;, etc.
     </para>
    </listitem>
    <listitem>
     <para>
      Os construtores <link linkend="language.function.if">if/elseif/else/endif</link> são passados
      para o interpretador de PHP, assim a sintaxe de expressão {if ...} pode ser tanto simples quanto
      complexa da forma que você queira.
     </para>
    </listitem>
    <listitem>
     <para>
      Aninhamento ilimitado de <link linkend="language.function.section">sections</link>,
      ifs, etc. permitidos.
     </para>
    </listitem>
    <listitem>
     <para>
      É possível <link linkend="language.function.php">embutir o código PHP</link> diretamente em
      seus arquivos de template, apesar de que isto pode não ser necessário (não recomendado) visto que a
      ferramenta é tão customizável.
     </para>
    </listitem>
    <listitem>
     <para>
      Suporte de <link linkend="caching">caching embutido</link>.
     </para>
    </listitem>
    <listitem>
     <para>
      <link linkend="template.resources">Fontes de template</link> arbitrários.
     </para>
    </listitem>
    <listitem>
     <para>
      Funções de <link linkend="section.template.cache.handler.func">manipulação
      de cache</link> customizadas.
     </para>
    </listitem>
    <listitem>
     <para>
      <link linkend="plugins">Arquitetura de Plugin</link>.
     </para>
    </listitem>
   </itemizedlist>
 </chapter>
 <chapter id="installation">
  <title>Instalação</title>

  <sect1 id="installation.requirements">
   <title>Requisitos</title>
   <para>
   Smarty requer um servidor web rodando o PHP 4.0.6 superior.
   </para>
  </sect1>

  <sect1 id="installing.smarty.basic">
    <title>Instalação Básica</title>
	<para>
	Instale os arquivos da biblioteca do Smarty que estão no subdiretório /libs/ da
	distribuição. Estes são os arquivos PHP que você NÃO PRECISA editar. Eles são comuns
	a todas as aplicações e eles só são atualizados quando você atualiza para uma nova
	versão do Smarty.
	</para>
	<example>
     <title>Arquivos da biblioteca do Smarty necessários</title>
     <screen>
Smarty.class.php
Smarty_Compiler.class.php
Config_File.class.php
debug.tpl
/internals/*.php (all of them)
/plugins/*.php (todos eles para ser seguro, talvés a sua pagina precise de apenas alguns)
     </screen>
	</example>

	<para>
     O Smarty utiliza uma <ulink url="&url.php-manual;define">constante</ulink> do PHP chamada
     <link linkend="constant.smarty.dir">SMARTY_DIR</link> que é o 
     <emphasis role="bold">caminho completo</emphasis> para o diretório 'libs/' do Smarty. 
     Basicamente, se sua aplicação puder encontrar o arquivo
     <filename>Smarty.class.php</filename>, você não precisa
     definir <link linkend="constant.smarty.dir">SMARTY_DIR</link>,
     o Smarty irá encontrar por si só. Entretanto, se
     <filename>Smarty.class.php</filename> não estiver em seu include_path, ou você
     não indicar um caminho absoluto para ele em sua aplicação, então você
     deverá definir SMARTY_DIR manualmente. SMARTY_DIR <emphasis role="bold">deve incluir uma
     barra ao final</emphasis>.
	</para>
	<para>
	Aqui está um exemplo de como você cria uma instância do Smarty em seus scripts PHP:
	</para>

	<example>
     <title>Cria uma instância do Smarty</title>
     <screen>
NOTE: Smarty has a capital 'S'
require_once('Smarty.class.php');
$smarty = new Smarty();
     </screen>
	</example>

	<para>
	 Tente rodar o script acima. Se você obtiver um erro dizendo que o arquivo
	 <filename>Smarty.class.php</filename> não pôde ser encontrado, você tem que fazer uma
	 das coisas a seguir:
	</para>

	<example>
     <title>Definir a constante SMARTY_DIR manualmente</title>
     <screen>
// *nix style (note capital 'S')
define('SMARTY_DIR', '/usr/local/lib/php/Smarty-v.e.r/libs/');

// windows style
define('SMARTY_DIR', 'c:/webroot/libs/Smarty-v.e.r/libs/');

// hack version example that works on both *nix and windows
// Smarty is assumend to be in 'includes/' dir under current script
define('SMARTY_DIR',str_replace("\\","/",getcwd()).'/includes/Smarty-v.e.r/libs/');

require_once(SMARTY_DIR . 'Smarty.class.php');
$smarty = new Smarty();
     </screen>
	</example>

	<example>
     <title>Adicionar o diretório da biblioteca para o include_path do PHP</title>
     <screen>
// Edite o seu arquivo php.ini, adicione o diretório da biblioteca do Smarty
// para o include_path e reinicie o servidor web.
// Então o código a seguir funcionaria:
require('Smarty.class.php');
$smarty = new Smarty;
     </screen>
	</example>

	<example>
     <title>Defina a constante SMARTY_DIR manualmente</title>
     <screen>
define('SMARTY_DIR','/usr/local/lib/php/Smarty/');
require(SMARTY_DIR.'Smarty.class.php');
$smarty = new Smarty;
     </screen>
	</example>

	<para>
     Agora que os arquivos da biblioteca estão no lugar, é hora de configurar os diretórios
     do Smarty para a sua aplicação.
    </para>
    <para>
     O Smarty necessita de quatro diretórios, que são chamados
     por padrão <filename class="directory">'templates/'</filename>,
     <filename class="directory">'templates_c/'</filename>, <filename
     class="directory">'configs/'</filename> e <filename
     class="directory">'cache/'</filename>.
    </para>
    <para>
     Cada um deles pode ser definido
     pelas propriedades da classe Smarty
     <link linkend="variable.template.dir">
     <varname>$template_dir</varname></link>,
     <link linkend="variable.compile.dir">
     <varname>$compile_dir</varname></link>,
     <link linkend="variable.config.dir">
     <varname>$config_dir</varname></link>, e
     <link linkend="variable.cache.dir">
     <varname>$cache_dir</varname></link> repectivamente.
     É altamente recomendado que
     você configure um conjunto diferente destes diretórios para cada aplicação
     que for usar o Smarty.
	</para>
	<para>
	Certifique-se que você sabe a localização do 'document root' do seu servidor web. Em nosso exemplo,
    o 'document root' é  <filename class="directory">"/web/www.mydomain.com/docs/"</filename>. Os diretórios do Smarty
	só são acessados pela biblioteca do Smarty e nunca acessados diretamente pelo navegador. Então para
	evitar qualquer preocupação com segurança, é recomendado colocar estes diretórios
	<emphasis>fora</emphasis> do document root.
	</para>
	<para>
	Para o nosso exemplo de instalação, nós estaremos configurando o ambiente do Smarty
	para uma aplicação de livro de visitas. Nós escolhemos uma aplicação só para o propósito
	 de uma convenção de nomeação de diretório. Você pode usar o mesmo ambiente para qualquer
	 aplicação, apenas substitua "guestbook" com o nome de sua aplicação. Nós colocaremos nossos
	 diretórios do Smarty dentro de 
     <filename class="directory">"/web/www.mydomain.com/smarty/guestbook/"</filename>.
	</para>
	<para>
	Você precisará pelo menos de um arquivo dentro de seu 'document root', e que seja acessado pelo
	navegador. Nós chamamos nosso
	script de <emphasis>"index.php"</emphasis>, e o colocamos em um subdiretório dentro
    do 'document root' chamado  <filename class="directory">"/guestbook/"</filename>.
	</para>
	
	<note>
	 <title>Nota Técnica</title>
	  <para>
       É conveniente configurar o servidor web para que 'index.php' possa ser
       idendificado como o índice padrão do diretório, asssim se você acessar
       http://www.example.com/guestbook/, o script 'index.php' será executado
       sem adicionar 'index.php' na URL. No Apache você pode configurar isto adicioanando
       "index.php" ao final da sua configuração <emphasis>DirectoryIndex</emphasis>
       (separe cada item com um espaço.) como no exemplo de httpd.conf
    </para>
    <para>
        <emphasis>DirectoryIndex
            index.htm index.html index.php index.php3 default.html index.cgi
    </emphasis>
	</para>
	</note>
	
	<para>
    Vamos dar uma olhada na estrutura de arquivos até agora:
	</para>

	<example>
     <title>Exemplo de estrutura de arquivo</title>
     <screen>
<![CDATA[
/usr/local/lib/php/Smarty-v.e.r/libs/Smarty.class.php
/usr/local/lib/php/Smarty-v.e.r/libs/Smarty_Compiler.class.php
/usr/local/lib/php/Smarty-v.e.r/libs/Config_File.class.php
/usr/local/lib/php/Smarty-v.e.r/libs/debug.tpl
/usr/local/lib/php/Smarty-v.e.r/libs/internals/*.php
/usr/local/lib/php/Smarty-v.e.r/libs/plugins/*.php

/web/www.example.com/smarty/guestbook/templates/
/web/www.example.com/smarty/guestbook/templates_c/
/web/www.example.com/smarty/guestbook/configs/
/web/www.example.com/smarty/guestbook/cache/

/web/www.example.com/docs/guestbook/index.php
]]>
     </screen>
	</example>

	<para>
     O Smarty irá precisar de <emphasis role="bold">acesso de escrita</emphasis>
     (usuários de windows por favor ignorem) em
     <link linkend="variable.compile.dir">
     <emphasis>$compile_dir</emphasis></link> e
     <link linkend="variable.cache.dir">
     <emphasis>$cache_dir</emphasis></link>,
     então tenha certesa que o usuário do servidor web possa escrever. 
     Este é geralmente o usuário "nobody" e o grupo "nobody" (ninguém). Para
	 SO com X usuários, o usuário padrão é "www" e o grupo "www". Se você está usando Apache, você
	 pode olhar em seu arquivo httpd.conf (normalmente em "/usr/local/apache/conf/") para ver
	 qual o usuário e grupo estão sendo usados.
	</para>

	<example>
     <title>Configurando permissões de arquivos</title>
     <screen>
<![CDATA[
chown nobody:nobody /web/www.example.com/smarty/guestbook/templates_c/
chmod 770 /web/www.example.com/smarty/guestbook/templates_c/

chown nobody:nobody /web/www.example.com/smarty/guestbook/cache/
chmod 770 /web/www.example.com/smarty/guestbook/cache/
]]>
     </screen>
	</example>

	<note>
	 <title>Nota Técnica</title>
	 <para>
	 chmod 770 será a segurança correta suficientemente restrita, só permite ao usuário "nobody" e
	 o grupo "nobody" acesso de leitura/escrita aos diretórios. Se você gostaria de abrir o acesso de leitura
	 para qualquer um (na maioria das vezes para sua própria conveniência de querer ver estes
	 arquivos), você pode usar o 775 ao invés do 770.
     </para>
	</note>

	<para>
	 Nós precisamos criar o arquivo "index.tpl" que o Smarty vai ler. Ele estará localizado  em seu
     <link linkend="variable.template.dir">$template_dir</link>.
	</para>

	<example>
        <title>Editando /web/www.example.com/smarty/guestbook/templates/index.tpl</title>
     <screen>

{* Smarty *}

Ola! {$name}, bem vindo ao Smarty!
     </screen>
	</example>


	<note>
	<title>Nota Técnica</title>
	<para>
     {* Smarty *} é um <link linkend="language.syntax.comments">comentário</link>
     de template. Ele não é exigido, mas é uma prática boa
	 iniciar todos os seus arquivos de template com este com este comentário. Isto faz com
	 que o arquivo seja reconhecido sem levar em consideração a sua extensão. Por exemplo,
	 editores de texto poderiam reconhecer o arquivo e habilitar coloração de sintaxe especial.
	</para>
	</note>

	<para>
     Agora vamos editar 'index.php'. Nós vamos criar uma instancia do Smarty, 
     <link linkend="api.assign">assign</link>(definir) uma
     variável do template e <link linkend="api.display">display</link>
     (mostrar) o arquivo 'index.tpl'. 
	</para>

	<example>
        <title>Editando /web/www.example.com/docs/guestbook/index.php</title>
     <screen>
<![CDATA[
<?php

// load Smarty library
require_once(SMARTY_DIR . 'Smarty.class.php');

$smarty = new Smarty();

$smarty->template_dir = '/web/www.example.com/smarty/guestbook/templates/';
$smarty->compile_dir = '/web/www.example.com/smarty/guestbook/templates_c/';
$smarty->config_dir = '/web/www.example.com/smarty/guestbook/configs/';
$smarty->cache_dir = '/web/www.example.com/smarty/guestbook/cache/';

$smarty->assign('name','Ned');

$smarty->display('index.tpl');
?>
]]>
     </screen>
	</example>

	<note>
	 <title>Nota Técnica</title>
	 <para>
      No nosso exemplo, nós estamos definindo caminhos absolutor para todos os diretórios
      do Smarty. Se <filename class="directory">/web/www.example.com/smarty/guestbook/</filename>
      estiver dentro do seu include_path do PHP, então estas definições não são necessárias.
      Entretando, é mais eficinte e (com experiência) causa
      menos erros definir como caminhos absolutos. Isto faz ter certeza que o Smarty
      esta lendo os arquivos dos diretórios que você quer.
	 </para>
	</note>

	<para>
	 Agora carregue o arquivo <filename>index.php</filename> em seu navegador.
	 Você veria "Olá, Thomas! bem vindo ao Smarty" 
	</para>
	<para>
	 Você completou a configuração básica para o Smarty!
	</para>
   </sect1>
   <sect1 id="installing.smarty.extended">
   <title>Estendendo a configuração</title>

   <para>
   Esta é uma continuação da <link
   linkend="installing.smarty.basic">instalação básica</link>,
   por favor leia a instalação básica primeiro!
   </para>
   <para>
   Uma forma um pouco mais flexível de configurar o Smarty é estender a classe e inicializar seu ambiente de
   Smarty. Então, ao invés de configurar caminhos de diretórios repetidamente, preencher as mesmas variáveis,
   etc., nós podemos fazer isso para facilitar. Vamos criar um novo diretório "/php/includes/guestbook/" e criar um
   novo arquivo chamado <filename>"setup.php"</filename>. Em nosso ambiente de exemplo, "/php/includes" está em nosso
   include_path. Certifique-se de que você 
   também definiu isto, ou use caminhos de arquivos absolutos.
   </para>

   <example>
    <title>Editando /php/includes/guestbook/setup.php</title>
    <screen>
<![CDATA[
<?php
// Carrega a biblioteca Smarty
require('Smarty.class.php');

// O arquivo setup.php é um bom lugar para carregar
// arquivos necessarios para a aplicação e você
// pode faze-lo aqui mesmo. Um exemplo:
// require('guestbook/guestbook.lib.php');

class Smarty_GuestBook extends Smarty {

    function Smarty_GuestBook()
    {

        // Construtor da classe.
        // Este é chamado a cada nova instância.

        $this->Smarty();

        $this->template_dir = '/web/www.example.com/smarty/guestbook/templates/';
        $this->compile_dir  = '/web/www.example.com/smarty/guestbook/templates_c/';
        $this->config_dir   = '/web/www.example.com/smarty/guestbook/configs/';
        $this->cache_dir    = '/web/www.example.com/smarty/guestbook/cache/';

        $this->caching = true;
        $this->assign('app_name', 'Guest Book');
    }

}
?>
]]>
     </screen>
   </example>

  <para>
  Agora vamos alterar o arquivo index.php para usar o setup.php:
  </para>
   
   <example>
    <title>Editando  /web/www.example.com/docs/guestbook/index.php</title>
    <screen>

require('guestbook/setup.php');

$smarty = new Smarty_GuestBook;

$smarty->assign('nome','Thomas');

$smarty->display('index.tpl');
     </screen>
   </example>

  <para>
  Agora você pode ver que é extremamente simples criar uma instância do Smarty, apenas use
  Smarty_GuestBook que automaticamente inicializa tudo para a nossa aplicação.
  </para>
   
  </sect1>

 </chapter>
</part>