repo_zf1/documentation/manual/pt-br/module_specs/Zend_View-Helpers.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 24249 -->
<!-- Reviewed: no -->
<sect1 id="zend.view.helpers" xmlns:xi="http://www.w3.org/2001/XInclude">
    <title>Assistentes de Visualização</title>

    <para>
        Em seus scripts de visualização, frequentemente é necessário a execução de certas tarefas
        complexas repetidas vezes: p. ex.: formatar uma data, gerar um elemento de formulário, ou
        exibir links de acionamento. Você pode empregar classes assistentes para executar estas
        tarefas para você.
    </para>

    <para>
        A helper is simply a class. Let's say we want a helper named 'fooBar'.
        By default, the class is prefixed with 'Zend_View_Helper_'
        (you can specify a custom prefix when setting a helper path), and the
        last segment of the class name is the helper name; this segment should
        be TitleCapped; the full class name is then:
        <classname>Zend_View_Helper_FooBar</classname>. This class should contain at the
        minimum a single method, named after the helper, and camelCased:
        <methodname>fooBar()</methodname>.
    </para>

    <note>
        <title>Watch the Case</title>

        <para>
            Helper names are always camelCased, i.e., they never begin with an
            uppercase character. The class name itself is MixedCased, but the
            method that is actually executed is camelCased.
        </para>
    </note>

    <note>
        <title>Default Helper Path</title>

        <para>
            The default helper path always points to the Zend Framework view
            helpers, i.e., 'Zend/View/Helper/'. Even if you call
            <methodname>setHelperPath()</methodname> to overwrite the existing paths, this
            path will be set to ensure the default helpers work.
        </para>
    </note>

    <para>
        Para usar um assistente em seu script de visualização, chame-o usando
        <command>$this->helperName()</command>. Em segundo plano, <classname>Zend_View</classname>
        irá carregar a classe <classname>Zend_View_Helper_HelperName</classname>, instanciá-la e
        chamar seu método <methodname>helperName()</methodname>. O objeto criado é persistente
        dentro do escopo da instância <classname>Zend_View</classname>, e será reutilizado por todas
        as chamadas futuras a <command>$this->helperName()</command>.
    </para>

    <sect2 id="zend.view.helpers.initial">
        <title>Assistentes Padrão</title>

        <para>
            <classname>Zend_View</classname> vem com um conjunto padrão de assistentes, a maioria
            deles dedicados à geração de elementos de formulários e automaticamente escapar a saída
            apropriada. Além disso, existem assistentes para criar <acronym>URL</acronym>s baseadas
            em rotas e listas de <acronym>HTML</acronym>, bem como declarar variáveis. Os
            assistentes atualmente embarcados incluem:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <methodname>declareVars()</methodname>: Primarily for use when using
                    <methodname>strictVars()</methodname>, this helper can be used to declare
                    template variables that may or may not already be set in the
                    view object, as well as to set default values. Arrays passed as
                    arguments to the method will be used to set default values;
                    otherwise, if the variable does not exist, it is set to an empty string.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>fieldset($name, $content, $attribs)</methodname>: Creates an
                    <acronym>XHTML</acronym> fieldset. If <varname>$attribs</varname> contains a
                    'legend' key, that value will be used for the fieldset legend. The
                    fieldset will surround the <varname>$content</varname> as provided to
                    the helper.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>form($name, $attribs, $content)</methodname>: Generates an
                    <acronym>XHTML</acronym> form. All <varname>$attribs</varname> are escaped and
                    rendered as <acronym>XHTML</acronym> attributes of the form tag. If
                    <varname>$content</varname> is present and not a boolean
                    <constant>FALSE</constant>, then that content is rendered within the start and
                    close form tags; if <varname>$content</varname> is a boolean
                    <constant>FALSE</constant> (the default), only the opening form tag is
                    generated.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>formButton($name, $value, $attribs)</methodname>: Cria um elemento
                    &lt;button /&gt;.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>formCheckbox($name, $value, $attribs, $options)</methodname>:
                    Cria um elemento &lt;input type="checkbox" /&gt;.
                </para>

                <para>
                    By default, when no $value is provided and no $options are
                    present, '0' is assumed to be the unchecked value, and '1'
                    the checked value. If a $value is passed, but no $options
                    are present, the checked value is assumed to be the value
                    passed.
                </para>

                <para>
                    $options should be an array. If the array is indexed, the
                    first value is the checked value, and the second the
                    unchecked value; all other values are ignored. You may also
                    pass an associative array with the keys 'checked' and
                    'unChecked'.
                </para>

                <para>
                    If $options has been passed, if $value matches the checked
                    value, then the element will be marked as checked. You may
                    also mark the element as checked or unchecked by passing a
                    boolean value for the attribute 'checked'.
                </para>

                <para>
                    The above is probably best summed up with some examples:
                </para>

                <programlisting language="php"><![CDATA[
// '1' and '0' as checked/unchecked options; not checked
echo $this->formCheckbox('foo');

// '1' and '0' as checked/unchecked options; checked
echo $this->formCheckbox('foo', null, array('checked' => true));

// 'bar' and '0' as checked/unchecked options; not checked
echo $this->formCheckbox('foo', 'bar');

// 'bar' and '0' as checked/unchecked options; checked
echo $this->formCheckbox('foo', 'bar', array('checked' => true));

// 'bar' and 'baz' as checked/unchecked options; unchecked
echo $this->formCheckbox('foo', null, null, array('bar', 'baz'));

// 'bar' and 'baz' as checked/unchecked options; unchecked
echo $this->formCheckbox('foo', null, null, array(
    'checked' => 'bar',
    'unChecked' => 'baz'
));

// 'bar' and 'baz' as checked/unchecked options; checked
echo $this->formCheckbox('foo', 'bar', null, array('bar', 'baz'));
echo $this->formCheckbox('foo',
                         null,
                         array('checked' => true),
                         array('bar', 'baz'));

// 'bar' and 'baz' as checked/unchecked options; unchecked
echo $this->formCheckbox('foo', 'baz', null, array('bar', 'baz'));
echo $this->formCheckbox('foo',
                         null,
                         array('checked' => false),
                         array('bar', 'baz'));
]]></programlisting>

                <para>
                    In all cases, the markup prepends a hidden element with the
                    unchecked value; this way, if the value is unchecked, you
                    will still get a valid value returned to your form.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>formErrors($errors, $options)</methodname>: Generates an
                    <acronym>XHTML</acronym> unordered list to show errors.
                    <varname>$errors</varname> should be a string or an array of strings;
                    <varname>$options</varname> should be any attributes you want
                    placed in the opening list tag.
                </para>

                <para>
                    You can specify alternate opening, closing, and separator
                    content when rendering the errors by calling several methods
                    on the helper:
                </para>

                <itemizedlist>
                    <listitem>
                        <para>
                            <methodname>setElementStart($string)</methodname>; default is
                            '&lt;ul class="errors"%s"&gt;&lt;li&gt;', where %s
                            is replaced with the attributes as specified in
                            <varname>$options</varname>.
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            <methodname>setElementSeparator($string)</methodname>; default
                            is '&lt;/li&gt;&lt;li&gt;'.
                        </para>
                    </listitem>

                    <listitem>
                        <para>
                            <methodname>setElementEnd($string)</methodname>; default is
                            '&lt;/li&gt;&lt;/ul&gt;'.
                        </para>
                    </listitem>
                </itemizedlist>
            </listitem>

            <listitem>
                <para>
                    <methodname>formFile($name, $attribs)</methodname>: Cria um elemento
                    &lt;input type="file" /&gt;.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>formHidden($name, $value, $attribs)</methodname>: Cria um elemento
                    &lt;input type="hidden" /&gt;.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>formLabel($name, $value, $attribs)</methodname>: Creates a
                    &lt;label&gt; element, setting the <property>for</property> attribute to
                    <varname>$name</varname>, and the actual label text to
                    <varname>$value</varname>. If <emphasis>disable</emphasis> is passed in
                    <property>attribs</property>, nothing will be returned.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>formMultiCheckbox($name, $value, $attribs, $options,
                        $listsep)</methodname>: Creates a list of checkboxes.
                    <varname>$options</varname> should be an associative array, and may be
                    arbitrarily deep. <varname>$value</varname> may be a single value or
                    an array of selected values that match the keys in the
                    <varname>$options</varname> array. <varname>$listsep</varname> is an
                    <acronym>HTML</acronym> break ("&lt;br /&gt;") by default. By default, this
                    element is treated as an array; all checkboxes share the same name, and are
                    submitted as an array.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>formPassword($name, $value, $attribs)</methodname>: Cria um elemento
                    &lt;input type="password" /&gt;.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>formRadio($name, $value, $attribs, $options)</methodname>: Cria uma
                    série de elementos &lt;input type="radio" /&gt;, um para cada elemento em
                    $options. Na matriz $options, a chave e seu valor estão associados ao valor do
                    controle e seu rótulo, respectivamente. O conteúdo de $value será
                    pré-selecionado.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>formReset($name, $value, $attribs)</methodname>: Cria um elemento
                    &lt;input type="reset" /&gt;.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>formSelect($name, $value, $attribs, $options)</methodname>: Cria um
                    bloco &lt;select&gt;...&lt;/select&gt;, com um &lt;option&gt; para cada elemento
                    em $options. Na matriz $options, a chave e seu valor estão associados ao valor
                    do controle e seu rótulo. O conteúdo de $value será pré-selecionado.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>formSubmit($name, $value, $attribs)</methodname>: Cria um elemento
                    &lt;input type="submit" /&gt;.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>formText($name, $value, $attribs)</methodname>: Cria um elemento
                    &lt;input type="text" /&gt;.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>formTextarea($name, $value, $attribs)</methodname>: Cria um bloco
                    &lt;textarea&gt;...&lt;/textarea&gt;.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>url($urlOptions, $name, $reset)</methodname>: Creates a
                    <acronym>URL</acronym> string based on a named route.
                    <varname>$urlOptions</varname> should be an associative array of key/value pairs
                    used by the particular route.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>htmlList($items, $ordered, $attribs, $escape)</methodname>:
                    generates unordered and ordered lists based on the <varname>$items</varname>
                    passed to it. If <varname>$items</varname> is a multidimensional
                    array, a nested list will be built. If the <varname>$escape</varname>
                    flag is <constant>TRUE</constant> (default), individual items will be escaped
                    using the view objects registered escaping mechanisms; pass a
                    <constant>FALSE</constant> value if you want to allow markup in your lists.
                </para>
            </listitem>
        </itemizedlist>

        <para>
            Utilizar estes assistentes em seus scripts de visualização é muito fácil, aqui está um
            exemplo. Note que tudo que você necessita fazer é chamá-los; eles carregam e instanciam
            a sí próprios a medida que tornam-se necessários.
        </para>

        <programlisting language="php"><![CDATA[
// dentro do seu script de visualização,
// $this aponta para a instância de Zend_View.
//
// digamos que você já atribuiu uma série de valores a matriz
// $countries = array('us' => 'United States', 'il' =>
// 'Israel', 'de' => 'Germany').
?>
<form action="action.php" method="post">
    <p><label>Your Email:
<?php echo $this->formText('email', 'you@example.com', array('size' => 32)) ?>
    </label></p>
    <p><label>Your Country:
<?php echo $this->formSelect('country', 'us', null, $this->countries) ?>
    </label></p>
    <p><label>Would you like to opt in?
<?php echo $this->formCheckbox('opt_in', 'yes', null, array('yes', 'no')) ?>
    </label></p>
</form>
]]></programlisting>

        <para>
            A saída resultante do script de visualização deverá se parecer com isto:
        </para>

        <programlisting language="php"><![CDATA[
<form action="action.php" method="post">
    <p><label>Your Email:
        <input type="text" name="email" value="you@example.com" size="32" />
    </label></p>
    <p><label>Your Country:
        <select name="country">
            <option value="us" selected="selected">United States</option>
            <option value="il">Israel</option>
            <option value="de">Germany</option>
        </select>
    </label></p>
    <p><label>Would you like to opt in?
        <input type="hidden" name="opt_in" value="no" />
        <input type="checkbox" name="opt_in" value="yes" checked="checked" />
    </label></p>
</form>
]]></programlisting>

        <xi:include href="Zend_View-Helpers-Action.xml" />
        <xi:include href="Zend_View-Helpers-BaseUrl.xml" />
        <xi:include href="Zend_View-Helpers-Currency.xml" />
        <xi:include href="Zend_View-Helpers-Cycle.xml" />
        <xi:include href="Zend_View-Helpers-Partial.xml" />
        <xi:include href="Zend_View-Helpers-Placeholder.xml" />
        <xi:include href="Zend_View-Helpers-Doctype.xml" />
        <xi:include href="Zend_View-Helpers-Gravatar.xml" />
        <xi:include href="Zend_View-Helpers-HeadLink.xml" />
        <xi:include href="Zend_View-Helpers-HeadMeta.xml" />
        <xi:include href="Zend_View-Helpers-HeadScript.xml" />
        <xi:include href="Zend_View-Helpers-HeadStyle.xml" />
        <xi:include href="Zend_View-Helpers-HeadTitle.xml" />
        <xi:include href="Zend_View-Helpers-HtmlObject.xml" />
        <xi:include href="Zend_View-Helpers-InlineScript.xml" />
        <xi:include href="Zend_View-Helpers-Json.xml" />
        <xi:include href="Zend_View-Helpers-Navigation.xml" />
        <xi:include href="Zend_View-Helpers-Translate.xml" />
        <xi:include href="Zend_View-Helpers-UserAgent.xml" />
    </sect2>

    <sect2 id="zend.view.helpers.paths">
        <title>Localizando os Assistentes</title>

        <para>
            Assim como os scripts de visualização, seu controlador pode especificar uma lista de
            caminhos onde o <classname>Zend_View</classname> deve procurar pelas classes
            assistentes. Por padrão, <classname>Zend_View</classname> procura pelas classes
            assistentes em "Zend/View/Helper/*". Você pode instruir o
            <classname>Zend_View</classname> a procurar em outros locais usando os métodos
            <methodname>setHelperPath()</methodname> e <methodname>addHelperPath()</methodname>.
            Além disso, você pode indicar um prefixo da classe a ser usado para os assistentes no
            caminho fornecido, permitindo o uso de namespaces em suas classes assistentes. Por
            padrão, se nenhum prefixo da classe for fornecido, 'Zend_View_Helper_' é assumido.
        </para>

        <programlisting language="php"><![CDATA[
$view = new Zend_View();

// Set path to /path/to/more/helpers, with prefix 'My_View_Helper'
$view->setHelperPath('/path/to/more/helpers', 'My_View_Helper');
]]></programlisting>

        <para>
            De fato, você pode "empilhar" caminhos usando o método
            <methodname>addHelperPath()</methodname>. A medida que você adiciona caminhos à pilha,
            <classname>Zend_View</classname> procurará no caminho mais recentemente adicionado.
            Isto permite a você incrementar o conjunto original de assistentes (ou susbstituir) com
            os seus próprios personalizados.
        </para>

        <programlisting language="php"><![CDATA[
$view = new Zend_View();
// Add /path/to/some/helpers with class prefix 'My_View_Helper'
$view->addHelperPath('/path/to/some/helpers', 'My_View_Helper');
// Add /other/path/to/helpers with class prefix 'Your_View_Helper'
$view->addHelperPath('/other/path/to/helpers', 'Your_View_Helper');

// now when you call $this->helperName(), Zend_View will look first for
// "/path/to/some/helpers/HelperName" using class name
// "Your_View_Helper_HelperName", then for
// "/other/path/to/helpers/HelperName.php" using class name
// "My_View_Helper_HelperName", and finally for
// "Zend/View/Helper/HelperName.php" using class name
// "Zend_View_Helper_HelperName".
]]></programlisting>
    </sect2>

    <sect2 id="zend.view.helpers.custom">
        <title>Escrevendo Assistentes Personalizados</title>

        <para>
            Escrever assistentes personalizados é fácil; basta seguir estas regras:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    While not strictly necessary, we recommend either implementing
                    <classname>Zend_View_Helper_Interface</classname> or extending
                    <classname>Zend_View_Helper_Abstract</classname> when creating your
                    helpers. Introduced in 1.6.0, these simply define a
                    <methodname>setView()</methodname> method; however, in upcoming releases, we
                    plan to implement a strategy pattern that will simplify much of
                    the naming schema detailed below. Building off these now will
                    help you future-proof your code.
                </para>
            </listitem>

            <listitem>
                <para>
                    The class name must, at the very minimum, end with the helper
                    name itself, using MixedCaps. E.g., if you were writing a
                    helper called "specialPurpose", the class name would minimally
                    need to be "SpecialPurpose". You may, and should, give the class
                    name a prefix, and it is recommended that you use 'View_Helper'
                    as part of that prefix: "My_View_Helper_SpecialPurpose". (You
                    will need to pass in the prefix, with or without the trailing
                    underscore, to <methodname>addHelperPath()</methodname> or
                    <methodname>setHelperPath()</methodname>).
                </para>
            </listitem>

            <listitem>
                <para>
                    A classe deve ter um método público que coincida com o nome do assistente; este
                    é o método que será chamado quando o seu template chamar
                    "$this->specialPurpose()". Em nosso exemplo "specialPurpose", o método requerido
                    deverá ser declarado como "public function specialPurpose()".
                </para>
            </listitem>

            <listitem>
                <para>
                    Em geral, a classe não deve ecoar ou imprimir a saída gerada. Em lugar disso,
                    ela deve retornar os valores a serem impressos. Os valores retornados deverão
                    estar devidamente escapados.
                </para>
            </listitem>

            <listitem>
                <para>
                    A classe deve estar em um arquivo chamado após a classe assistente. Voltando ao
                    exemplo "specialPurpose", o arquivo recebeu o nome "SpecialPurpose.php".
                </para>
            </listitem>
        </itemizedlist>

        <para>
            Localize o arquivo com a classe assistente em algum dos caminhos armazenados na pilha,
            e o <classname>Zend_View</classname> automaticamente irá carregar, instanciar,
            persistir, e executar o código para você.
        </para>

        <para>
            Aqui está um exemplo do assistente <classname>SpecialPurpose</classname>:
        </para>

        <programlisting language="php"><![CDATA[
class My_View_Helper_SpecialPurpose extends Zend_View_Helper_Abstract
{
    protected $_count = 0;
    public function specialPurpose()
    {
        $this->_count++;
        $output = "I have seen 'The Jerk' {$this->_count} time(s).";
        return htmlspecialchars($output);
    }
}
]]></programlisting>

        <para>
            Em um script de visualização, você pode chamar o assistente
            <classname>SpecialPurpose</classname> quantas vezes desejar; ele será instanciado apenas
            uma vez; e persistirá durante todo o tempo de vida da instância de
            <classname>Zend_View</classname>.
        </para>

        <programlisting language="php"><![CDATA[
// remember, in a view script, $this refers to the Zend_View instance.
echo $this->specialPurpose();
echo $this->specialPurpose();
echo $this->specialPurpose();
]]></programlisting>

        <para>
            A saída deverá se parecer com isto:
        </para>

        <programlisting language="php"><![CDATA[
I have seen 'The Jerk' 1 time(s).
I have seen 'The Jerk' 2 time(s).
I have seen 'The Jerk' 3 time(s).
]]></programlisting>

        <para>
            Sometimes you will need access to the calling <classname>Zend_View</classname>
            object -- for instance, if you need to use the registered encoding,
            or want to render another view script as part of your helper. To get
            access to the view object, your helper class should have a
            <methodname>setView($view)</methodname> method, like the following:
        </para>

        <programlisting language="php"><![CDATA[
class My_View_Helper_ScriptPath
{
    public $view;

    public function setView(Zend_View_Interface $view)
    {
        $this->view = $view;
    }

    public function scriptPath($script)
    {
        return $this->view->getScriptPath($script);
    }
}
]]></programlisting>

        <para>
            If your helper class has a <methodname>setView()</methodname> method, it will be
            called when the helper class is first instantiated, and passed the
            current view object. It is up to you to persist the object in your
            class, as well as determine how it should be accessed.
        </para>

        <para>
            If you are extending <classname>Zend_View_Helper_Abstract</classname>, you do
            not need to define this method, as it is defined for you.
        </para>
    </sect2>

    <sect2 id="zend.view.helpers.registering-concrete">
        <title>Registering Concrete Helpers</title>

        <para>
            Sometimes it is convenient to instantiate a view helper, and then register it with the
            view. As of version 1.10.0, this is now possible using the
            <methodname>registerHelper()</methodname> method, which expects two arguments: the
            helper object, and the name by which it will be registered.
        </para>

        <programlisting language="php"><![CDATA[
$helper = new My_Helper_Foo();
// ...do some configuration or dependency injection...

$view->registerHelper($helper, 'foo');
]]></programlisting>

        <para>
            If the helper has a <methodname>setView()</methodname> method, the view object will call
            this and inject itself into the helper on registration.
        </para>

        <note>
            <title>Helper name should match a method</title>

            <para>
                The second argument to <methodname>registerHelper()</methodname> is the name of the
                helper. A corresponding method name should exist in the helper; otherwise,
                <classname>Zend_View</classname> will call a non-existent method when invoking the
                helper, raising a fatal <acronym>PHP</acronym> error.
            </para>
        </note>
    </sect2>
</sect1>
<!--
vim:se ts=4 sw=4 et:
-->