Criando Formulários

Actions e parâmetros de serviço

O jCom oferece ferramentas avançadas para facilitar o uso de formulários. Diversos serviços permitem a interação com formulários, e uma ferramenta de validação garante o correto preenchimento dos dados.

Veja por exemplo uma parte de um formulário de contato, que permite o envio de mensagens ao administrador da loja:

<form action="/contact.htm" method="POST">

<input type=hidden name="action" value="contactService.send">
<input type=hidden name="redirect" value="/contatoOk.htm">
<input type=hidden name="validator" value="formContato">
<input type=hidden name="template" value="/templates/contato.txt">
<input type=hidden name="clientTemplate" value="/templates/avisoContato.txt">
<input type=hidden name="nameField" value="nome">
<input type=hidden name="emailField" value="email">

<!-- restante do formulário -->
</form>

A propriedade "action" do formulário geralmente aponta para a própria página onde o formulário está. Isso garante que, em caso de erro, o usuário voltará para a mesma página para corrigir o preenchimento dos dados que estiverem incorretos. Neste caso, a página se chama "contact.htm".

Os dois parâmetros ocultos a seguir, "action", "redirect" e "validator", são internas ao jCom. O parâmetro "action" indica que o formulário será processado pelo serviço contactService, e executaremos o comando "send". Este é um comando do serviço responsável pelo envio de e-mails de contato.

O parâmetro "redirect" indica a página para qual o usuário será direcionado caso o formulário possa ser processado corretamente. Neste exemplo, utilizaremos uma página de agradecimento pelo contato.

O parâmetro "validator" é opcional, e indica o nome de um validador que será usado para conferir se o formulário foi preenchido corretamente. Mais adiante abordaremos os validadores mais detalhadamente.

Os demais campos ocultos acima são de uso específico do contactService; outros serviços e actions utilizam outros parâmetros conforme necessário. Para mais informações sobre estes parâmetros, veja a seção "Objetos e Serviços".

Os campos

Os campos preenchíveis pelo usuário funcionam de forma quase trivial; veja o preenchimento automático de parâmetros abaixo, em vermelho:

Nome: <input type="text" name="nome" value="$!params.nome">
e-mail: <input type="text" name="email" value="$!params.email">
Mensagem: <textarea name="mensagem">$!params.mensagem</textarea>

As variáveis $params.nome e $params.email não contém nenhum valor quando o formulário é visto pela primeira vez; porém em caso de erro no preenchimento, o usuário é levado de volta ao mesmo formulário e estes valores serão corretamente preenchidos. Para que isto ocorra, o nome da variável deve ser o mesmo da propriedade "name" da tag html "input" ou "textarea". Ou seja, o input de nome "email" causará o preenchimento da variável $params.email, automaticamente.

Se você leu a seção sobre o Velocity, deve lembrar que o símbolo "!" é usado para ocultar as variáveis que não contenham nenhum valor, no formato "$!params.nome" acima. Se não usarmos o "!", os campos virão preenchidos com o texto "$params.nome", o que é indesejável.

O botão "Submit"

O botão "submit", que deve ser pressionado para o envio do formulário, não precisa de nenhum parâmetro especial. Também é possível a utilização de uma imagem (<input type=image value=submit>) ou ainda um comando Jscript.

<input type="submit" value=" Enviar ">

Validadores

Um validator pode ser usado para verificar o correto preenchimento dos campos do formulário. Validators são definidos no arquivo de configuração /conf/jcom.xml.

Para o formulário acima, utilizaremos as seguintes regras:

Assim, definimos o validator desta forma:

<validators>

	<validator name="formContato">
		<field name="nome" label="Nome" required="true" minLength="5"/>
		<field name="email" label="e-mail" required="true" validateAs="email"/>
		<field name="mensagem" label=Mensagem" required="true" minLength=10"/>
	</validator>

	<!-- outros validadores -->

</validators>

Cada validator possui um nome, usado para identificá-lo no formulário. O nome do validator acima, "formContato", foi utilizado no campo oculto "validator" do formulário; desta forma, indicamos ao jCom que este validador deve ser satisfeito antes que a ação seja processada.

As três tags "field" do arquivo de configuração indicam que os campos "nome", "email" e "mensagem" devem ser validados. Todos os campos possuem a propriedade "required", já que são obrigatórios. Nome e mensagem possuem tamanho mínimo de 5 e 10 letras, respectivamente. O campo e-mail possui ainda a propriedade "validateAs", indicando que o campo deve obrigatoriamente ser um e-mail.

Veja abaixo os parâmetros possíveis de field:

name Nome do campo; deve ser idêntico ao parâmetro "name" do campo. Este parâmetro é obrigatório.
label Nome descritivo do campo, que será apresentado ao usuário em caso de erro. Por exemplo: "preencha corretamente o campo Mensagem". Este parâmetro é obrigatório.
required Indica se o campo é obrigatório (true) ou não (false). Se não for especificado, o campo não é obrigatório.
minLength Tamanho mínimo em caracteres (letras ou dígitos)
maxLength Tamanho máximo em caracteres
validateAs Exige o preenchimento de formatos pré-definidos; atualmente, o único valor permitido é "email"
validateEqual Exige que o campo seja igual ao campo especificado. Por exemplo, para garantir que o usuário preencha corretamente seu e-mail ou senha duas vezes: validateEqual="senha2". Esta opção só precisa ser adicionada a um dos campos.
pattern

Utiliza uma expressão regular para validar o campo. Esta é uma opção avançada que requer o conhecimento do conceito de expressões regulares.

Exemplo: para permitir apenas números, pode-se usar a expressão "[0-9]+"

É importante notar que a opção de tamanho mínimo (minLength) só é utilizada se o campo for preenchido. Para tornar o campo obrigatório e simultaneamente exigir preenchimento mínimo, é necessário combinar as opções required e minLength.

 

 

Quem Somos | Entre em Contato | ©2007 Isnet Serviços de Informática Ltda