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.
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:
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
?>
// 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
?>
// 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.
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
?>
// 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.
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
?>
// 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
?>
// 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
?>
// snip
// display the form
$obj_registration_form->display();
// snip
?>
E finalmente vamos exibir o formulário na tela chamando o método display().