Como sempre tive (e ainda tenho) problemas com os decorators, grande parte dos acessos para esse blog são provenientes de buscas por “decorators” e principalmente por ter recebido uma sugestão direta do XAngel, eu resolvi criar uma série de post em duas partes sobre o assunto.

Nessa primeira parte, irei apenas traduzir a página sobre Decorators do ZF Reference Guide. Ela contém uma boa explicação sobre o seu funcionamento e algumas dicas bem úteis que podem resolver alguns problemas rapidamente.

A segunda parte será um pouco mais interessante, pois irei exemplificar a criação de decorators customizados, que alteram o layout dos forms “automagicamente”.

Sem mais enrolação, vamos para o post.

Decorators

Um ponto em particular (e penoso) para muitos desenvolvedores web é a criação automática de forms XHTML. O desenvolvedor precisa, para cada elemento, criar marcas para o próprio elemento (típicamente um label) e marcas especiais para exibir as mensagens de validações de erros. Quanto mais elementos na página, mais trabalhosa a tarefa se torna.

O Zend_Form_Element tenta resolver esse problema usando “decorators”. Decorators são classes simples que possuem acesso ao elemento e métodos para renderizar seu conteúdo. Para mais informações sobre como os decorators funcionam, por favor, veja a seção Zend_Form_Decorator.

Os decorators padrões, utilizado pelo Zend_Form_Element, são:

• ViewHelper: Específica o view helper utilizado para renderizar o elemento. O atributo “helper” do elemento pode ser usado para especificar qual view helper utilizar. Por padrão, o Zend_Form_Element especifica o helper “formText”, mas subclasses individuais especificam outros helpers.

• Errors: Anexa a mensagem de erro ao elemento utilizando o Zend_View_Helper_FormErrors. Se não existe erros, nada aparecerá.

• Description: Adiciona uma descrição para o elemento. Se nenhuma descrição foi setada, nada aparecerá. Por padrão, a descrição é renderizada dentro de uma tag “<p>” com a classe (css) “description”.

• HtmlTag: Agrupa o elemento e os erros na tag HTML “<dd>”.

• Label: Anexa um label para o elemento, utilizando o Zend_View_Helper_FormLabel, e o empacora na tag “<dt>”. Se nenhum label for especificado apenas a tag é renderizada.

Decorators padrões não precisam ser carregados

Os decorators padrões são carregados durante a inicialização do objeto. Você pode disabilitar isso passando a opção ‘disableLoadDefaultDecorators’  para o construtor:

$element = new Zend_Form_Element('foo',
array('disableLoadDefaultDecorators' =>
true)
);

Essa opção pode ser enviada junto com qualquer outra opção que você passar, tanto como array quanto como um objeto Zend_Config.

Uma vez que a ordem, em que os decorators foram registrados, é importante – o primeiro decorator registrado é executado em primeiro – você precisa ter certeza que está registrando seus decorators em uma ordem apropriada, ou garantir que você setou as opções de posicionamento em um design compreensivel. Para ilustrar melhor, esse é o código que registra os decorators padrões:

$this->addDecorators(array(
array('ViewHelper'),
array('Errors'),
array('Description', array('tag' => 'p', 'class' => 'description')),
array('HtmlTag', array('tag' => 'dd')),
array('Label', array('tag' => 'dt')),
));

<dt><label for="foo" class="optional">Foo</label></dt>
<dd>
<input type="text" name="foo" id="foo" value="123" />
<ul class="errors">
<li>Mensagem de erro</li>
</ul>
<p class="description">
Descrição do elemento
</p>
</dd>

Utilizando múltiplos decorators de um mesmo tipo

Internamente, o Zend_Form_Element usa uma classe de decorator como mecanismo de busca para obter decorators. Como resultado, você não pode registrar mais de um decorator do mesmo tipo; Os decorators subsequentes irão simplesmente sobrescrever o anterior.

Para contornar isso, você pode utilizar aliases. Ao invés de passar o decorator ou o seu nome como primeiro argumento para o “addDecorator()”, passe um array com um único elemento, com um alias apontando para o objeto do decorator ou seu nome:

// Alias para 'FooBar':
$element->addDecorator(array('FooBar' => 'HtmlTag'),
array('tag' => 'div'));

//obtendo:
$decorator = $element->getDecorator('FooBar');

Nos métodos “addDecorators()” e “setDecorators()”, você precisa informar no array a opção “decorator” representando o decorator:

// Adiciona dois decorator "HtmlTag", um deles apontando para "FooBar"
$element->addDecorators(
array('HtmlTag', array('tag' => 'div')),
array(
'decorator' => array('FooBar' => 'HtmlTag'),
'options' => array('tag' => 'dd')
),
);

//Obtendo:
$htmlTag = $element->getDecorator('HtmlTag');
$fooBar  = $element->getDecorator('FooBar');

Métodos associados com os decoratos:

• addDecorator($nomeOuDecorator, array $options = null)
• addDecorators(array $decorators)
• setDecorators(array $decorators) (Sobrescreve todos os decorators)
• getDecorator($name) (obtém um decorator pelo nome)
• getDecorators() (obtém todos os decorators)
• removeDecorator($name) (remove um decorator pelo nome)
• clearDecorators() (remove todos os decorators)

O Zend_Form_Element usa também “overloading” para permitir a renderização de decorator específicos. “__call()”  irá interceptar os métodos que iniciam com “render” e usa o restante do nome para buscar pelo decorator; Se encontrar, ele irá renderiza-lo. Qualquer argumento passado pela chamada do método será utilizado como conteúdo informado para o método “render()” do decorator. Por exemplo:

// Renderiza apenas o decorator ViewHelper:
echo $element->renderViewHelper();

// Renderiza apenas o decorator ViewHelper, passando o conteúdo:

echo $element->renderHtmlTag("Esse é o conteúdo da tag HTML.");

Se um decorator não existe uma exceção é criada.

Posts relacionados:

1. Zend Framework – Tutorial – Personalizando os decorators php, zend, hospedagem, ajax, programação, tutorial, curso, apostila, site, criar...
2. Dica Rápida: Decorators Aceitando a sugestão do XAngel irei providenciar um artigo bem...
3. Integrando o Zend Framework com o Dojo – Parte III Dando continuidade a nossa integração, vamos dar uma rapida olhada...