Recentemente fui chamado para desenvolver um projeto para o desenvolvimento de um portal de uma comunidade, a ser desenvolvido na plataforma LAMP (Linux Apache MySQL PHP) - minha plataforma preferida. Minha primeira responsabilidade seria construir um protótipo que permitisse o a entrada dos dados dos usuários usando um formulário simples.

Em tal cenário, a reação usual de um programador é utilizar um editor HTML WYSIWYG, usar funções Javascript dos projetos arquivados e fazer o código de PHP para controlar a interação da base de dados. E voilá - o protótipo está pronto para rodar!

Então decidi sair dessa rotina de copiar-colar e procurar por uma solução que aerodinamizasse o processo de construir tais formulários. Um de meus objetivos durante esta pesquisa era procurar um mecanismo que permitisse que eu me focasse em executar a lógica do negócio associada com a aplicação ao invés de me preocupar com coisas mundanas, como a escrita do código do HTML ou scripting validations usando o Javascript.

Comecei com uma revisão rápida de alguns motores "templating" populares a procura de uma que me permitisse abstrair a lógica do programa da interface com o usuário e conseguisse ser realmente o autor de um modelo - ou seja, abster-me da escrita do código HTML.

Então encontrei o pacote de HTML_QuickForm no Web site da biblioteca PEAR para PHP. O sumário oficial para o pacote indicou que o pacote "fornece métodos para criar, validar, processar formulários do HTML". Eu vi que finalmente tinha encontrado o ouro.

Vou dar uma explanação rápida sobre a PEAR antes de começar a falar do pacote HTML_QuickForm: de acordo com o Web site oficial, PEAR (um acrônimo para o PHP Extension and Application Repository) é "um sistema da estrutura e distribuição para componentes reusáveis de PHP".

Simplificando, é uma biblioteca de código aberto de classes para exigências de programação comuns, tais como o acesso de uma base de dados ou envio de email, usando as melhores práticas e predefinido padrões de codificação. Você pode aprender mais sobre a PEAR em:

• http://pear.php.net

Voltando à minha grande descoberta, o pacote HTML_QuickForm. Uma revisão rápida de suas características, está listada em:

• http://pear.php.net/package/HTML_QuickForm

Isso indica que o sumário acima mencionado era simplesmente a ponta do iceberg. A única maneira de aprender mais sobre esse maravilhoso pacote é fazer um pequeno "test-drive".

Espera aí... não tão rápido.

Primeiramente preciso ter a certeza de que temos a biblioteca PEAR instalada e configurada corretamente. Felizmente o manual oficial vem com um passo-a-passo que mostra como fazer essa configuração. Portanto não falarei sobre isso aqui, pois foge do escopo do artigo. Para ver esse manual vá até:

• http://pear.php.net/manual/en/installation.php

Partindo do pressuposto que já está tudo instalado e configurado perfeitamente, vamos por a "mão na massa".

Como você pôde ter percebido, o alvo deste artigo é demonstrar a facilidade com que se pode gerar um formulário da Web usando o pacote de HTML_QuickForm. Clique no link abaixo para ver o código de nosso primeiro formulário:

• example01.txt

Você verá a tela como a seguinte:

Uma olhada rápida do código e você verá que não fiz o código de todos os elementos - ainda assim o browser mostra um pequeno formulário quando o script é carregado.

Neste momento posso com segurança concluir que este pacote cumpre definitivamente um de meus objetivos originais: não devo digitar nenhum código HTML durante o desenvolvimento.

Agora é hora de "dissecar" o código. Pra começar tenho que fazer um REQUIRE com o arquivo que contém a definição da classe HTML_QuickForm(), como demonstrado a seguir:

Na próxima linha eu crio uma instância (chamada "$obj_registration_form") da classe HTML_QuickForm. O construtor dessa classe tem um parâmetro obrigatório - o nome do formulário.

O resto dos parâmetros de entrada são opcionais, dentre outras coisas esses parâmetros opcionais permitem definir vários atributos do elemento <FORM>.

Perceba que o valor padrão para o atributo METHOD é POST, então se quisermos utilizar o método GET, precisamos passar esse valor explicitamente para o construtor.

Agora irei adicionar diferentes elementos HTML no meu formulário:

Todos os elementos de HTML_QuickForm são divididos em duas categorias:

• Elementos padrão;
• Elementos customizados.

Primeiro adicionei dois elementos customizados através do método addElement(), o primeiro é o elemento HEADER, que permite o texto como cabeçalho - com a fonte maior e destacada - do meu formulário.

Depois incluo um pouco de HTML puro usando o elemento customizado HTML. Um pequeno aviso sobre esse procedimento: a documentação oficial não recomenda o uso do elemento HTML, pois pode gerar um código estilo "espaguete" no seu script PHP. Ao invés disso ele recomenda o uso de templates para organizar o layout do seu formulário. Aprenderemos mais sobre templates na segunda parte desse tutorial.

Note que o número de parâmetros utilizados no método AdElement() depende do tipo de elemento que estamos inserindo no form. Enquanto são necessários apenas dois elementos para os elementos HTML e HEADER, nos elementos padrões o jogo muda um pouco. Dê uma olhada no código a seguir:

Primeiro adicionei um elemento TEXT para entrada de dados, perceba que eu utilizei quatro parâmetros:

• O primeiro “text” para indicar que é um campo <INPUT> desse tipo;
• O segundo parâmetro indica o nome do campo;
• O terceiro é o LABEL para esse campo, ou seja o que será exibido ao seu lado;
• O quarto um array contendo os valores-chaves para a configuração do campo. Você perceberá que são atributos comumente utilizados nos elementos no código HTML.

É bem parecida com a inserção de um campo <INPUT> do tipo <TEXTAREA>, basicamente a alteração seria no primeiro parâmetro, por razões obvias. Você perceberá também que o quarto parâmetro serve para definir o tamanho do campo.

Depois adiciono um campo do tipo <SELECT>, como você deve ter percebido eu utilizei SELECT no tipo do campo e continuei a utilizar o parâmetro LABEL (o 3º parâmetro). Mas e os valores que serão exibidos?? Eu utilizarei um array onde o valor é o que será exibido no browser e a chave o valor que será submetido via form como se estivéssemos utilizando o parâmetro <OPTION> do código HTML.

O nosso próximo elemento <INPUT> é o Rádio Button, é claro que eu adicionei dois elementos com o mesmo nome, pois isso faz com que somente um deles seja selecionado, todos os elementos adicionados com o mesmo nome fazem parte do mesmo grupo de RadioButtons.

Depois temos a inserção dos elementos checkbox, submit e reset.

Por padrão o valor do atributo ACTION do formulário é enviar para a própria página, dessa forma, se não forem explicitamente declarados os devidos parâmetros, a página enviará os dados para ela mesma via POST quando clicarmos no botão SUBMIT.

Dê uma olhada no código a seguir:

Aqui chamei o método validate() para testar se os dados já foram enviados pelo usuário, eu ainda não implementei nenhuma validação (veremos isso mais tarde), você verá no seu browser a tela a seguir:

Na tela acima mostra os valores armazenados no array retornado pelo método exportValues(), logo depois eu chamo o método freeze() para "congelar" os campos e não permitir sua edição.

E finalmente vamos exibir o formulário na tela chamando o método display().