Utilizando PEAR

Recentemente decidi procurar por uma solução que aerodinamizasse o processo de construir 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.

[ Hits: 31.314 ]

Por: Pedro César em 20/04/2006


Introdução



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:
Voltando à minha grande descoberta, o pacote HTML_QuickForm. Uma revisão rápida de suas características, está listada em:
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é:
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:
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:

<?php
// include the required PEAR class
require_once('HTML/QuickForm.php');
// define a new HTML_QuickForm object
$obj_registration_form = new HTML_QuickForm('frmRegistration');
// snip
?>

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:

<?php
// snip
$obj_registration_form->addElement('header', '', 'Registration');
$obj_registration_form->addElement('html', '<tr><td colspan="2"> </td></tr>');
$obj_registration_form->addElement('header', '', 'Artist Information');
$obj_registration_form->addElement('html', '<tr><td colspan="2"> </td></tr>');
// snip
?>

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:

<?php
// snip
$obj_registration_form->addElement('text', 'txtFullName', 'Full Name:', array('size' => 40, 'maxlength' => 50));
$obj_registration_form->addElement('textarea', 'txtAddress', 'Address:', array('rows' => 3, 'cols' => 30));
$obj_registration_form->addElement('select', 'txtCountry', 'Country:', array ("" => "Select Country", "USA" => "United States","UK" => "United Kingdom","IND" => "India", "Other" => "Other"));
$obj_registration_form->addElement('text', 'txtEmailAddress', 'e-mail Address:', array( 'size' => 40, 'maxlength' => 255));
$obj_registration_form->addElement('radio', 'txtGender', 'Select Gender:', 'Male', 'M');
$obj_registration_form->addElement('radio', 'txtGender', '', 'Female', 'F');
// snip
?>

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.

<?php
// snip
$obj_registration_form->addElement('checkbox', 'txtNewsletter', 'Subscribe to Newsletter:', 'Yes');
$obj_registration_form->addElement('html', '<tr><td colspan="2"> </td></tr>');
$obj_registration_form->addElement('submit', 'btnSubmit', 'Register');
$obj_registration_form->addElement('reset', 'btnReset', 'Start Again');
// snip
?>

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:

<?php
// snip
// filters before validation comes here
// validation rules come here
// validate form
if($obj_registration_form->validate()) {
// filters after validation comes here
// if data is valid, process form details
echo '<pre>';
var_dump($obj_registration_form->exportValues());
echo '</pre>';
// free the form values
$obj_registration_form->freeze();
}
// snip
?>

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.

<?php
  // snip
  // display the form
  $obj_registration_form->display();
  // snip
?>

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

    Próxima página

Páginas do artigo
   1. Introdução
   2. Agrupando elementos do Form
   3. Validando os dados do formulário
   4. Persistindo os dados no banco MySQL
Outros artigos deste autor

Uma introdução à biblioteca GD

Dicas simples para dar mais usabilidades aos formulários

Uma introdução à classe ADODB

Paginação de resultados com a classe ADODB

Leitura recomendada

Usando Blocos Dinâmicos com a Classe FastTemplate (Parte 1)

Método de Newton e PHP

Relatórios com PHP e XSLT - Conceitos iniciais e utilização básica

Organizando projetos com a classe FastTemplate (parte 1)

Usando Blocos Dinâmicos com a Classe FastTemplate (Parte 2)

  
Comentários
[1] Comentário enviado por removido em 20/04/2006 - 02:58h

O PEAR é um repositório de diversas classes prontas. Uma delas, muito útil, é a PEAR-DB, utilizada como forma de abstrair a integração com diversos SGBD's modificando uma única linha de configuração.

[2] Comentário enviado por celiojs em 20/04/2006 - 14:16h

Realmente o PEAR parece ajudar.
Muito bom o seu artigo.
Parabéns!!

[3] Comentário enviado por redstyle em 20/04/2006 - 14:45h

Alguém aqui já instalou alguma classe manualmente ? Ou seja, não usou os comandos linux ou o go-pear do windows.

É que se você fizer um sistema e tem controle no server blz...mas e em sites hospedados eles não tem essa classe.

Tem como subir os arquivos e fazer funcionar corretamente?
Tentei, mas sempre dava caminho de includes errado já que uma classe chama a outra.

Muito bom o artigo, realmente ajuda muito.

Dica pra validar com javascript é a biblioteca YAV http://yav.sourceforge.net

T+

[4] Comentário enviado por gurski em 20/04/2006 - 22:04h

Otimo artigo, estou utilizando a classe HTML_Template_IT junto com a HTML_QuickForm e seu artigo vai ajudar bastante.

[5] Comentário enviado por taiar em 05/02/2009 - 08:47h

Excelente artigo.

Abordou muito bem os aspectos que qualquer um precisa na prática.

Excelente!


Contribuir com comentário