[MANUAL] Brazilian Portuguese:

- sync to r20799


git-svn-id: http://framework.zend.com/svn/framework/standard/trunk@21114 44c647ce-9c0f-0410-b52a-842ac1e357ba

documentation/manual/pt-br/module_specs/Zend_View-Scripts.xml

@@ -1,20 +1,31 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- EN-Revision: 20799 -->
+<!-- Reviewed: no -->
 <sect1 id="zend.view.scripts">
-
     <title>Scripts de Visualização</title>
 
     <para>
-        Uma vez que seu controlador tenha atribuido as variáveis e chamado o método, Zend_View incluirá o script de visualização requerido e o executará dentro do escopo de sua própria instância.  Portanto, em seus scripts de visualização, as referências a $this apontarão para a própria instância de Zend_View.
+        Uma vez que seu controlador tenha atribuido as variáveis e chamado o método
+        <methodname>render()</methodname>, <classname>Zend_View</classname> incluirá o script de
+        visualização requerido e o executará "dentro" do escopo da instância de
+        <classname>Zend_View</classname>. Portanto, em seus scripts de visualização, as referências
+        a $this apontarão para a própria instância de <classname>Zend_View</classname>.
     </para>
 
     <para>
-        Variáveis atribuídas à visualização pelo controlador são referidas como propriedades de instância. Por exemplo, se o controlador atribuir a variável 'algumacoisa', você deve referir-se a ela como $this->algumacoisa em seu scritp de visualização.  (Isto permite um rastreamento dos valores que foram atribuidos ao script, e que são internos ao mesmo).
+        Variáveis atribuídas à visualização pelo controlador são referidas como propriedades de
+        instância. Por exemplo, se o controlador atribuir a variável 'algumacoisa', você deve
+        referir-se a ela como $this->algumacoisa em seu script de visualização. (Isto permite um
+        rastreamento dos valores que foram atribuidos ao script, e que são internos ao mesmo).
     </para>
 
     <para>
-        A fim de lembrar, aqui está um exemplo de script de visualização originado da introdução do Zend_View.
+        A fim de lembrar, aqui está um exemplo de script de visualização originado da introdução do
+        <classname>Zend_View</classname>.
     </para>
 
-    <programlisting role="php"><![CDATA[<?php if ($this->books): ?>
+    <programlisting language="php"><![CDATA[
+<?php if ($this->books): ?>
 
     <!-- Uma tabela contendo alguns livros. -->
     <table>
@@ -36,35 +47,42 @@
 
     <p>Não existem livros a serem exibidos.</p>
 
-<?php endif; ?>]]>
-    </programlisting>
+<?php endif;?>
+]]></programlisting>
 
     <sect2 id="zend.view.scripts.escaping">
-
         <title>Escapando a Saída</title>
 
         <para>
-            Uma das tarefas mais importantes a ser executada por scripts de visualização é assegurar que a saída seja corretamente escapada; entre outras coisas, isto ajuda a evitar ataques do tipo site-cruzado. A menos que você esteja usando uma função, método, ou assistente que realize o escape, você sempre deverá escapar o conteúdo das variáveis antes de exibí-lo.
+            Uma das tarefas mais importantes a ser executada por scripts de visualização é assegurar
+            que a saída seja corretamente escapada; entre outras coisas, isto ajuda a evitar ataques
+            do tipo site-cruzado. A menos que você esteja usando uma função, método, ou assistente
+            que realize o escape, você sempre deverá escapar o conteúdo das variáveis antes de
+            exibí-lo.
         </para>
 
         <para>
-            Zend_View implementa um método chamado escape() que realiza corretamente o escape para você.
+            <classname>Zend_View</classname> implementa um método chamado escape() que realiza
+            corretamente o escape para você.
         </para>
 
-        <programlisting role="php"><![CDATA[<?php
+        <programlisting language="php"><![CDATA[
 // maneira ruim:
 echo $this->variable;
 
 // maneira recomendada:
 echo $this->escape($this->variable);
-?>]]>
-        </programlisting>
+]]></programlisting>
 
         <para>
-        Por padrão, o método escape() usa a função PHP htmlspecialchars() para fazer o escape.  Mas, dependendo do seu ambiente, você pode desejar um comportamento diferente para o escape. Use o método setEscape() no nível do controlador para instruir o  Zend_View sobre qual função de callback utilizar para fazer o escape.
+            Por padrão, o método escape() usa a função htmlspecialchars() do <acronym>PHP</acronym>
+            para fazer o escape. Mas, dependendo do seu ambiente, você pode desejar um comportamento
+            diferente para o escape. Use o método setEscape() no nível do controlador para instruir
+            o <classname>Zend_View</classname> sobre qual função de callback utilizar para fazer o
+            escape.
         </para>
 
-        <programlisting role="php"><![CDATA[<?php
+        <programlisting language="php"><![CDATA[
 // cria uma instância de Zend_View
 $view = new Zend_View();
 
@@ -80,24 +98,37 @@ $view->setEscape(array($obj, 'methodName'));
 
 // e renderiza a visualização
 echo $view->render(...);
-?>]]>
-        </programlisting>
+]]></programlisting>
 
         <para>
-            A função ou método de callback deverá tomar o valor a ser escapado como seu primeiro parâmetro, e os demais parâmetros deverão ser opcionais.
+            A função ou método de callback deverá tomar o valor a ser escapado como seu primeiro
+            parâmetro, e os demais parâmetros deverão ser opcionais.
         </para>
-
     </sect2>
 
     <sect2 id="zend.view.scripts.templates">
-
-        <title>Sistemas de Template</title>
+        <title>Usando Sistemas de Template Alternativos</title>
 
         <para>
-            Embora o PHP em sí seja um poderoso sistema de template, muitos desenvolvedores sentiram que ele é muito potente ou complexo para seus designers de templates.  Como tal, o script de visualização pode ser usado para instanciar e manipular um objeto de template separadamente, tal como um template ao estilo PHPLIB (ou Smarty).  O script de visualização para este tipo de tarefa pode ser algo como isto:
+            Embora o <acronym>PHP</acronym> em si seja um poderoso sistema de template, muitos
+            desenvolvedores sentiram que ele é muito potente ou complexo para seus designers de
+            templates e acabam usando um motor de template alternativo.
+            <classname>Zend_View</classname> fornece para isso dois mecanismos, o primeiro através
+            de scripts de visualização, e o segundo implementando
+            <classname>Zend_View_Interface</classname>.
         </para>
 
-        <programlisting role="php"><![CDATA[<?php
+        <sect3 id="zend.view.scripts.templates.scripts">
+            <title>Template Systems Using View Scripts</title>
+
+            <para>
+                A view script may be used to instantiate and manipulate a
+                separate template object, such as a PHPLIB-style template. The
+                view script for that kind of activity might look something like
+                this:
+            </para>
+
+            <programlisting language="php"><![CDATA[
 include_once 'template.inc';
 $tpl = new Template();
 
@@ -118,19 +149,18 @@ if ($this->books) {
     $tpl->setFile("nobooks", "nobooks.tpl")
     $tpl->pparse("output", "nobooks");
 }
-?>]]>
-        </programlisting>
+]]></programlisting>
 
-        <para>
-            Estes seriam os arquivos de template relacionados:
-        </para>
+            <para>
+                Estes seriam os arquivos de template relacionados:
+            </para>
 
-        <programlisting role="html"><![CDATA[
+            <programlisting language="html"><![CDATA[
 <!-- booklist.tpl -->
 <table>
     <tr>
-        <th>Author</th>
-        <th>Title</th>
+        <th>Autor</th>
+        <th>Título</th>
     </tr>
     {books}
 </table>
@@ -142,13 +172,295 @@ if ($this->books) {
     </tr>
 
 <!-- nobooks.tpl -->
-<p>There are no books to display.</p>
-]]>
-        </programlisting>
+<p>Não existem livros a serem exibidos.</p>
+]]></programlisting>
+        </sect3>
+
+        <sect3 id="zend.view.scripts.templates.interface">
+            <title>Template Systems Using Zend_View_Interface</title>
+
+            <para>
+                Some may find it easier to simply provide a
+                <classname>Zend_View</classname>-compatible template engine.
+                <classname>Zend_View_Interface</classname> defines the minimum interface needed for
+                compatability:
+            </para>
+
+            <programlisting language="php"><![CDATA[
+/**
+ * Return the actual template engine object
+ */
+public function getEngine();
+
+/**
+ * Set the path to view scripts/templates
+ */
+public function setScriptPath($path);
+
+/**
+ * Set a base path to all view resources
+ */
+public function setBasePath($path, $prefix = 'Zend_View');
+
+/**
+ * Add an additional base path to view resources
+ */
+public function addBasePath($path, $prefix = 'Zend_View');
+
+/**
+ * Retrieve the current script paths
+ */
+public function getScriptPaths();
+
+/**
+ * Overloading methods for assigning template variables as object
+ * properties
+ */
+public function __set($key, $value);
+public function __isset($key);
+public function __unset($key);
+
+/**
+ * Manual assignment of template variables, or ability to assign
+ * multiple variables en masse.
+ */
+public function assign($spec, $value = null);
+
+/**
+ * Unset all assigned template variables
+ */
+public function clearVars();
+
+/**
+ * Render the template named $name
+ */
+public function render($name);
+]]></programlisting>
+
+            <para>
+                Using this interface, it becomes relatively easy to wrap a
+                third-party template engine as a <classname>Zend_View</classname>-compatible class.
+                As an example, the following is one potential wrapper for Smarty:
+            </para>
+
+            <programlisting language="php"><![CDATA[
+class Zend_View_Smarty implements Zend_View_Interface
+{
+    /**
+     * Smarty object
+     * @var Smarty
+     */
+    protected $_smarty;
+
+    /**
+     * Constructor
+     *
+     * @param string $tmplPath
+     * @param array $extraParams
+     * @return void
+     */
+    public function __construct($tmplPath = null, $extraParams = array())
+    {
+        $this->_smarty = new Smarty;
+
+        if (null !== $tmplPath) {
+            $this->setScriptPath($tmplPath);
+        }
+
+        foreach ($extraParams as $key => $value) {
+            $this->_smarty->$key = $value;
+        }
+    }
 
-    </sect2>
+    /**
+     * Return the template engine object
+     *
+     * @return Smarty
+     */
+    public function getEngine()
+    {
+        return $this->_smarty;
+    }
+
+    /**
+     * Set the path to the templates
+     *
+     * @param string $path The directory to set as the path.
+     * @return void
+     */
+    public function setScriptPath($path)
+    {
+        if (is_readable($path)) {
+            $this->_smarty->template_dir = $path;
+            return;
+        }
+
+        throw new Exception('Invalid path provided');
+    }
+
+    /**
+     * Retrieve the current template directory
+     *
+     * @return string
+     */
+    public function getScriptPaths()
+    {
+        return array($this->_smarty->template_dir);
+    }
+
+    /**
+     * Alias for setScriptPath
+     *
+     * @param string $path
+     * @param string $prefix Unused
+     * @return void
+     */
+    public function setBasePath($path, $prefix = 'Zend_View')
+    {
+        return $this->setScriptPath($path);
+    }
+
+    /**
+     * Alias for setScriptPath
+     *
+     * @param string $path
+     * @param string $prefix Unused
+     * @return void
+     */
+    public function addBasePath($path, $prefix = 'Zend_View')
+    {
+        return $this->setScriptPath($path);
+    }
+
+    /**
+     * Assign a variable to the template
+     *
+     * @param string $key The variable name.
+     * @param mixed $val The variable value.
+     * @return void
+     */
+    public function __set($key, $val)
+    {
+        $this->_smarty->assign($key, $val);
+    }
+
+    /**
+     * Allows testing with empty() and isset() to work
+     *
+     * @param string $key
+     * @return boolean
+     */
+    public function __isset($key)
+    {
+        return (null !== $this->_smarty->get_template_vars($key));
+    }
+
+    /**
+     * Allows unset() on object properties to work
+     *
+     * @param string $key
+     * @return void
+     */
+    public function __unset($key)
+    {
+        $this->_smarty->clear_assign($key);
+    }
+
+    /**
+     * Assign variables to the template
+     *
+     * Allows setting a specific key to the specified value, OR passing
+     * an array of key => value pairs to set en masse.
+     *
+     * @see __set()
+     * @param string|array $spec The assignment strategy to use (key or
+     * array of key => value pairs)
+     * @param mixed $value (Optional) If assigning a named variable,
+     * use this as the value.
+     * @return void
+     */
+    public function assign($spec, $value = null)
+    {
+        if (is_array($spec)) {
+            $this->_smarty->assign($spec);
+            return;
+        }
+
+        $this->_smarty->assign($spec, $value);
+    }
 
+    /**
+     * Clear all assigned variables
+     *
+     * Clears all variables assigned to Zend_View either via
+     * {@link assign()} or property overloading
+     * ({@link __get()}/{@link __set()}).
+     *
+     * @return void
+     */
+    public function clearVars()
+    {
+        $this->_smarty->clear_all_assign();
+    }
+
+    /**
+     * Processes a template and returns the output.
+     *
+     * @param string $name The template to process.
+     * @return string The output.
+     */
+    public function render($name)
+    {
+        return $this->_smarty->fetch($name);
+    }
+}
+]]></programlisting>
+
+            <para>
+                In this example, you would instantiate the
+                <classname>Zend_View_Smarty</classname> class instead of
+                <classname>Zend_View</classname>, and then use it in roughly the same
+                fashion as <classname>Zend_View</classname>:
+            </para>
+
+            <programlisting language="php"><![CDATA[
+//Example 1. In initView() of initializer.
+$view = new Zend_View_Smarty('/path/to/templates');
+$viewRenderer =
+    Zend_Controller_Action_HelperBroker::getStaticHelper('ViewRenderer');
+$viewRenderer->setView($view)
+             ->setViewBasePathSpec($view->_smarty->template_dir)
+             ->setViewScriptPathSpec(':controller/:action.:suffix')
+             ->setViewScriptPathNoControllerSpec(':action.:suffix')
+             ->setViewSuffix('tpl');
+
+//Example 2. Usage in action controller remains the same...
+class FooController extends Zend_Controller_Action
+{
+    public function barAction()
+    {
+        $this->view->book   = 'Zend PHP 5 Certification Study Guide';
+        $this->view->author = 'Davey Shafik and Ben Ramsey'
+    }
+}
+
+//Example 3. Initializing view in action controller
+class FooController extends Zend_Controller_Action
+{
+    public function init()
+    {
+        $this->view   = new Zend_View_Smarty('/path/to/templates');
+        $viewRenderer = $this->_helper->getHelper('viewRenderer');
+        $viewRenderer->setView($this->view)
+                     ->setViewBasePathSpec($view->_smarty->template_dir)
+                     ->setViewScriptPathSpec(':controller/:action.:suffix')
+                     ->setViewScriptPathNoControllerSpec(':action.:suffix')
+                     ->setViewSuffix('tpl');
+    }
+]]></programlisting>
+        </sect3>
+    </sect2>
 </sect1>
 <!--
 vim:se ts=4 sw=4 et:
--->
+-->