35.4. Assistentes de Visualização (Modificadores)

Em seus scripts de visualização, frequentemente é necessário a execução de certas tarefas complexas repetidas vezes; exemplo: 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 usar um assistente em seu script de visualização, chame-o usando $this->helperName(). Em segundo plano, Zend_View irá carregar a classe Zend_View_Helper_HelperName, instanciá-la e chamar seu método helperName(). O objeto criado é persistente dentro do escopo da instância Zend_View e será reutilizado por todas as chamadas futuras a $this->helperName().

35.4.1. Assistentes Padrão

Zend_View vem com um conjunto padrão de assistentes, todos dedicados à geração de elementos de formulários. Cada um deles automaticamente escapa a saída apropriada. São eles:

  • formButton($name, $value, $attribs): Cria um elemento <input type="button" />.

  • formCheckbox($name, $value, $attribs, $options): Cria um elemento <input type="checkbox" />. O parâmetro $options é um array cujo primeiro valor é o valor "checked" e o segundo é o valor "unchecked" (os valores padrão são '1' e '0'). O controle sera preselecionado de acordo com o conteúdo de $value.

  • formFile($name, $value, $attribs): Cria um elemento <input type="file" />.

  • formHidden($name, $value, $attribs): Cria um elemento <input type="hidden" />.

  • formPassword($name, $value, $attribs): Cria um elemento <input type="password" />.

  • formRadio($name, $value, $attribs, $options): Cria uma série de elementos <input type="radio" />, um para cada elemento em $options. No array $options, a chave e seu valor estão associados ao valor do controle e seu rótulo, respecitvamente. O conteúdo de $value será preselecionado.

  • formReset($name, $value, $attribs): Cria um elemento <input type="reset" />.

  • formSelect($name, $value, $attribs, $options): Cria um bloco <select>...</select>, com um <option>para elemento em $options. No array $options, a chave e seu valor estão associados ao valor do controle e seu rótulo. O conteúdo de $value será preselecionado.

  • formSubmit($name, $value, $attribs): Cria um elemento <input type="submit" />.

  • formText($name, $value, $attribs): Cria um elemento <input type="text" />.

  • formTextarea($name, $value, $attribs): Cria um bloco <textarea>...</textarea>.

Utilizar estes assistentees 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.

<?php
// dentro do seu script de visualização, $this aponta para a instância de Zend_View.
// digamos que você já atribuiu uma serie de valores ao array 
// $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>
        

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

<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>
        

35.4.2. Localizando os Assistentes

Assim como os scripts de visualização, seu controlador pode especificar uma lista de caminhos onde o Zend_View deve procurar pelas classes assistentes. Por padrão, Zend_View procura pelas classes assistentes em "Zend/View/Helper/*". Você pode instruir o Zend_View a procurar em outros locais usando os métodos setHelperPath() e addHelperPath().

<?php
$view = new Zend_View();
$view->setHelperPath('/path/to/more/helpers');
?>
        

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

<?php
$view = new Zend_View();
$view->addHelperPath('/path/to/some/helpers');
$view->addHelperPath('/other/path/to/helpers');

// now when you call $this->helperName(), Zend_View will look first for
// "/other/path/to/helpers/HelperName.php", then for
// "/path/to/some/helpers/HelperName", and finally for
// "Zend/View/Helpers/HelperName.php".
?>
        

35.4.3. Escrevendo Assistentes Personalizados

Escrever assistentes personalizados é fácil; basta seguir estas regras:

  • O nome da classe deve ser no formato Zend_View_Helper_*, onde * é o nome do assistente a ser criado. Ex:, se você criar um assistente chamado "specialPurpose", o nome da classe deverá ser "Zend_View_Helper_SpecialPurpose" (Observe a capitalização).

  • 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()".

  • 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.

  • A classe deve estar no arquivo chamado após o método assistente. Voltando ao exemplo "specialPurpose", o arquivo rebeu o nome "SpecialPurpose.php".

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

Aqui está um exemplo do assistente SpecialPurpose:

<?php
class Zend_View_Helper_SpecialPurpose {
    protected $_count = 0;
    public function specialPurpose()
    {
        $this->_count++;
        $output = "I have seen 'The Jerk' {$this->_count} time(s).";
        return htmlspecialchars($output);
    }
}
?>
        

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

<?php
// remember, in a view script, $this refers to the Zend_View instance.
echo $this->specialPurpose();
echo $this->specialPurpose();
echo $this->specialPurpose();
?>
        

A saída deverá se parecer com isto:

I have seen 'The Jerk' 1 time(s).
I have seen 'The Jerk' 2 time(s).
I have seen 'The Jerk' 3 time(s).