Data da última atualização: 06/07/2000
©2000 - Alexandre de Oliveira Stauffer & José Maciel Franco Junior

CGI e Formulários HTML

------------------------------------------------------------------------

  1. Introdução ao HTML
  2. Introdução ao CGI
  3. Formulários em HTML
    1. Campos Texto (text, textarea e password)
    2. Caixas de Seleção e Botões de Rádio (checkbox e radiobutton)
    3. Campos de Seleção de Arquivos (browse)
    4. Campos de Imagens (image)
    5. Campos Ocultos (hidden)
    6. Botões de Pressão (button)
    7. Botões de Processamento (submit e reset)
  4. Sobre a C_CGI
    1. Onde Obter
    2. Definições
    3. void iniciar_cgi(char *tipo);
    4. tcgivar* pega_arg();
    5. int tot_arg(tcgivar* t);
    6. char* val_arg(const char *arg, tcgivar* args);
    7. char** val_marg(const char *arg, tcgivar* args);
  5. Construindo um CGI, usando a C_CGI
  6. Compilando um Programa que use a C_CGI
  7. Exercícios

------------------------------------------------------------------------

Introdução ao HTML

O que é um documento HTML

A sigla HTML significa HyperText Markup Language. Documentos HTML são formados por texto puro (formato ASCII), portanto podem ser criados e editados por qualquer editor de textos (como o Bloco de Notas no Windows, Edit do DOS ou vi no Linux/Unix). Este formato texto possui algumas particularidades, pois sua formatação é feita através das chamadas tags. Estas são estruturas formadas por um sinal de menor que (<), o nome da tag, e um sinal de maior que (>), o que é usado para iniciar a instrução. Para finalizar a instrução de uma tag, normalmente usa-se a mesma tag, mas com um sinal de barra (/) antes do nome da tag.

Tags HTML

Um exemplo o ajudará a entender melhor como funciona a inserção de tags em documentos HTML:
Em um documento texto criado com o Bloco de Notas do Windows, por exemplo, não podemos criar um documento em que um determinado texto apareça em negrito. Entretanto, em um documento HTML isso é possível usando-se uma instrução, que inicia com a tag <B> e termina com </B>. Por exemplo:

Texto <B>Exemplo</B> em Negrito.

Num documento HTML, a palavra Exemplo do texto apareceria em negrito e a frase seria exibida como mostrada abaixo:

Texto Exemplo em Negrito.

Como você pode ver, podemos usar uma tag para fazer com que um determinado texto fique em negrito. Mas não é apenas isso, também podemos usar tags de diferentes nomes para mudar a fonte do texto, deixa-lo em itálico, sublinhado, criar tabelas, caixas de texto e muitas outras coisas que vemos em documentos deste tipo. Assim como a tag <B> pode deixar o texto em negrito, a tag <I> pode deixa-lo em itálico.

Editores HTML

Existem editores especializados na criação de documentos HTML. Alguns deles auxiliam na inserção de tags HTML, outros mostram visualmente como ficará sua página quando for visualizada (são os chamados editores WYSIWYG - What You See Is What You Get). O Microsoft Word (a partir de sua versão 97), pode ser usado como exemplo de editor WYSIWYG, pois seus documentos podem ser salvos em formato HTML. Se você edita no Word o seguinte texto:

Este é um exemplo de uso do Word para criar documentos HTML...

e salva o mesmo como um documento HTML, ele se parecerá com o seguinte quando for aberto em um editor de texto puro (como o Bloco de Notas):

Este é um <B>exemplo</B> de uso do <I>Word</I> para criar documentos <B><I>HTML</I></B>...

Observe que como a palavra HTML está em negrito e itálico, as duas tags são usadas em conjunto.

Tags Fundamentais

Existem algumas tags que são fundamentais para que um documento seja reconhecido pelo browser (navegador) como um documento HTML. Embora o exemplo mostrado na seção anterior seja correto, quando formos abrir no Bloco de Notas um documento que o word salvou como HTML, não veremos apenas o texto com as tags mostradas. Veremos, na verdade, algo mais parecido com:

<html>
<head>
<title>Este é um exemplo de uso do Word para criar documentos HTML</title>
</head>

<body>
Este é um <b>exemplo</b> de uso do <i>Word</i> para criar
documentos <b><i>HTML</i></b>...
</body>

</html>

Tags como <HTML> e <BODY> sempre estão presentes em um documento HTML. Note que neste exemplo usamos as tags com letras minúsculas, o que mostra que o navegador não faz distinção entre maiúsculas e minúsculas.

Vamos analisar as tags usadas no documento mostrado anteriormente.

HTML
Esta instrução informa para o browser que o arquivo contem informações de um documento HTML. A extenção de arquivo .html (ou apenas .htm)  também indica isso e deve ser usada. É dentro desta tag que estão localizadas as de cabeçalho (head) e corpo de texto (body).

HEAD e TITLE
Indica a primeira parte do código HTML (o cabeçalho), que contém o título. Este título é exibido normalmente na barra de título da janela de seu browser. Normalmente você deve deixar seu título com no máximo 64 caracteres.

BODY
A segunda e maior parte de seu documento. Dentro desta tag ficará o corpo de seu documento, e é onde você usará as tags de negrito, itálico, sublinhado etc. Todas as tags que serão mencionadas neste pequeno tutorial ficarão dentro de <BODY>.

------------------------------------------------------------------------

Introdução ao CGI

Primeiramente, CGI é a sigla para Common Gateway Interface e serve, basicamente, para permitir que uma página web possua um conteúdo dinâmico, isto é, que a página seje criada baseada em informações entradas pelo usuário. Exemplos muito evidentes de páginas que possam ser criadas através de um CGI são: mecanismos de buscas, formulários para cadastramento de clientes, consulta de boletim escolar e etc..

Um script CGI pode ser criado usando qualquer linguagem suportada pela plataforma em uso (entenda-se como plataforma o sistema operacional e o servidor WEB que estão rodando na máquina em que o CGI será executado). Por exemplo, se estivermos usando o Apache sob Linux, podemos rodar um CGI em perl, c, flagship (uma ferramenta para fazer programas em clipper rodarem sob Linux), pascal; mas não poderíamos executar um CGI feito em Delphi, pois ele não rodaria no Linux. Isto se deve ao fato de que o CGI nada mais é que a execução de um programa com as entradas pré-definidas, sendo que a saída do programa será a própria página a ser enviada pro usuário.

O processo de execução de um script CGI segue os seguintes passos:

  1. O usuário preenche um formulário e envia esse formulário para o CGI (normalmente esse envio é feito ao se pressionar um botão no formulário);
  2. O servidor WEB receberá essa informação, identificará que ela se destina a um programa e executa esse programa.
  3. O programa então pega e trata as entradas fornecidas pelo usuário, enviando ao servidor WEB uma página no formato HTML como resposta.
  4. O servidor WEB, por sua vez, remete essa página para o usuário como se fosse uma simples página estática.

Vale a pena ressaltar dois aspectos relativos ao CGI: primeiramente ele é executado na máquina servidor e, portanto, se o CGI precisar ler, escrever ou executar algum arquivo ele (o usuário no qual o CGI é utilizado, em alguns casos será o nobody) deve ter permissão para tal; por último, o usuário, que está na máquina cliente, não pode ver o código fonte do CGI porque ele não baixa o programa, ele apenas recebe a saída que o programa gera.

------------------------------------------------------------------------

Formulários em HTML

Os formulários são usados para enviar dados entrados pelo usuário para o servidor web. O servidor é o responsável por fornecer as informações do formulário para o programa CGI que será executado e tratará as mesmas, enviando como resposta a saída de dados que será enviada ao computador do usuário.

Por exemplo, vamos imaginar que você esteja fazendo um cadastro de pessoas que vão no seu site, mas você deseja que a pessoa forneça apenas seu nome, e-mail e o esporte que ele mais gosta, sendo este último escolhido entre três opções (futebol, basquete e handball). Um formulário como o mostrado abaixo será apresentado:

Nome:
E-mail:
Esporte favorito: futebol basquete handball

O código HTML para o formulário acima é:

<form method="POST" action="/cgi-bin/submit.exe">
<p>

Nome:
<input type="text" name="nome" maxlength="15" size="20"><br>
E-mail: <input type="text" name="email" size="20"><br>
Esporte favorito: <input type="radio" value="futebol" name="esporte">
futebol <input type="radio" value="basquete" name="esporte">basquete
<input type="radio" value="handball" name="esporte">handball
</p>
<p>
<input type=
"submit" value="Enviar" name="submit_button">
<input type=
"reset" value="Apagar" name="reset_button"></p>
</form>

Repare que todo o formulário está entre as tags <FORM> e </FORM>, que definem o limite dos campos que nele estão contidos. O tag FORM mostrado acima possui dos parâmetros. O primeiro indica o método de envio dos dados (GET ou POST) e o segundo indica o que deve ser feito ou o programa que deve ser executado quando clicado o botão para envio do formulário. No caso acima, será chamado o CGI submit.exe, que está no diretório de CGI's cgi-bin. Os tipos de campos utilizados acima (caixas de texto e botões de rádio) serão analisados a seguir. A maior parte dos campos são formados pela tag input, e tem seu tipo alterado de acordo com o valor do parâmetro type.


Campos de Texto e Senha (text, textarea e password)

Caixa de texto de uma linha

A caixa de texto é utilizada para obter uma informação escrita em um campo de uma única linha. No exemplo mostrado acima, podemos ver a caixa de texto onde o usuário entra seu nome, que possui o seguinte código HTML:

<input type="text" name="nome" maxlength="15" size="20">

Os parâmetros utilizados são os seguintes:

type="text"
informa que o tipo de entrada será um campo de texto, que consiste em uma caixa de texto de uma só linha.

name="nome"
define um nome qualquer para a tag.

size="20"
define o tamanho da caixa de texto (em caracteres).

maxlength="15"
define o número máximo de caracteres que poderão ser digitados.

Área de texto (várias linhas)

A área de texto é utilizada para obter uma informação escrita em um campo de mais de uma linha. Veja o exemplo abaixo:

O bloco de código abaixo mostra como é montada a área de texto acima em código HTML

<textarea name="text_field" rows="5" cols="60">Texto Inicial</textarea>

Os parâmetros são, respectivamente, o nome do campo, o número de linha e o número de colunas. Entre o tag inicial e final existe o texto padrão que entrará no campo.

Caixa de texto com senha

Os campos de senha  (password) são semelhantes ao campo de caixa de texto de uma linha, porém, o texto digitado pelo usuário é substituído por asteriscos (*). Veja o exemplo abaixo:

Digite sua senha:

que possui o seguinte código:

<input type="password" name="pass1" maxlength="5" size="20">

O parâmetro "Value"

Os campos de texto e de senha, além dos parâmetros mostrados, possuem um outro, denominado value. Este campo é usado para guardar o texto neles contido. Você pode escolher um valor iniciar para o mesmo adicionando o parâmetro value="texto padrão", onde texto padrão será o texto inicialmente contido neste campo. A caixa de texto abaixo possui o parâmetro value, que é igual a "teste".

Nome:

Este valor pode ser alterado pelo usuário, e o texto final será o enviado pelo formulário.


Caixas de Seleção e Botões de Rádio (checkbox e radiobutton)

As caixas de seleção são usadas para que o usuário marque ou desmarque determinadas opções, dentre várias. Já os botões de rádio são usados para selecionar uma só entre várias opções. Veja os exemplos abaixo:

Marque os esportes pelos quais você se interessa:

futebol vôlei basquete baseball handball

Código da caixa de seleção: <input type="checkbox" name="futebol" value="SIM">

Cada campo tem um nome diferente e você pode escolher quantas opções quiser, inclusive nenhuma, ou todas.
Cada uma das opções possui um nome e um valor (parâmetro value), assim como o campo de texto, entretanto, aqui o valor não será definido pelo usuário, vai apenas conter o valor predeterminado caso o usuário marque esta opção. Assim como uma caixa de texto que pede para o usuário digitar seu esporte favorito irá conter como valor o texto digitado (se o usuário digitar "vôlei", este será o valor da caixa de texto), a caixa de seleção futebol possuirá o valor do parâmetro value, se o usuário a tiver marcado, ou simplesmente não existirá, caso o usuário não a tenha marcado. No caso acima, as caixas de seleção têm o valor SIM, então este será o valor deste campo (considerando q ele esteja marcado) quando o formulário for enviado.

Marque o esporte do qual você mais gosta:

futebol vôlei basquete baseball handball

Cödigo: <input type="radio" value="futebol" name="esportes">

No caso acima, o que temos são botões de rádio, isto é, campos de seleção em que apenas um dentre os campos com o mesmo name podem ser marcados. Assim sendo o que será enviado pelo formulário será um campo com o nome igual a esportes e com valor igual ao valor do campo que o usuário selecionou, funcionando assim da mesma forma que uma caixa de texto com name="esportes" e em que o usuário digitou o que está no parâmetro value do campo selecionado.


Campos de Seleção de Arquivos (browse)

Estes campos são usados para que o usuário escolha um arquivo em disco. Veja o exemplo abaixo:

Este formulário tem o seguinte código:
<input type="file" name="select_file">

O parâmetro type informa que o campo é do tipo file e o parâmetro name informa o nome do campo.


Campos de Imagens (image)

Também é possível inserir imagens como campos de formulário. Uma imagem pode funcionar como um botão de envio do formulário. Veja o exemplo abaixo:

... esta imagem possui o seguinte código dentro do formulário: <input type="image" border="0" src="submit.gif" name="image1" width="69" height="24">

Os parâmetros são semelhantes ao de uma imagem comum:

type
border
src
name
width
height
tipo de campo de formulário
espessura da borda ao redor da imagem
url da localização da imagem
nome atribuído ao objeto de formulário (neste caso a imagem)
largura da imagem, que pode ser o tamanho real ou diferente deste (neste caso a imagem será distorcida)
altura da imagem, que pode ser o tamanho real ou diferente deste (neste caso a imagem será distorcida)

Clicar na imagem mostrada possui o mesmo efeito que um clique no botão de envio (submit) do formulário.


Campos Ocultos (hidden)

Os campos oculto são como todos os outros, no entanto serve apenas para enviar somente informações que não precisam ser lidas pelo usuário. Por exemplo, um campo que informe para que pagina devemos ir após o envio dos dados.
Veja o exemplo abaixo:

<input type="hidden" name="forward" value="http://www.dcc.ufrj.br">

Neste caso um CGI poderia pegar o valor do campo forward, e redirecionar para esta URL, através de uma tag ou de um java script, por exemplo.
Note que isto funciona como uma caixa de edição, só que o usuário não pode ver este campo, que possui valor fixo.


Botões de Pressão (button)

São botões como os que vemos em quase qualquer programa, como o mostrado abaixo:

A tag para este botão fica como mostrado abaixo:

<input type="button" value="mensagem" name="buttonmsg">

O campo value especifica o rótulo do botão, que é o valor que será enviado para o CGI. Você pode usar botões como esse para fornecer ajuda sobre determinados campos. Por exemplo, poderia usar um botão com o rótulo "ajuda" associado a um javascript para fornecer uma caixa de mensagem dizendo o que o usuário deve preencher naquele campo...


Botões de Processamento (submit e reset)

Estes botões funcionam como os anteriores, no entanto, os botões submit e reset, enviam e resetam as informações de formulário, respectivamente.

<input type="submit" value="Enviar" name="enviar">
<input type=
"reset" value="Apagar" name="apaga">

O exemplo acima teria como resultado:

Caso o formulário tenha como parâmetro action="sumit.exe", então o botão Enviar, mostrado acima, enviará as informações do formulário preenchido para o CGI submit.exe. O botão Apagar, fará com que todos os campos voltem a ter seus valores iniciais.

------------------------------------------------------------------------

Sobre a C_CGI

A C_CGI foi criada com o objetivo único de fazer com que o programador não tenha que se preocupar em como pegar os argumentos passados por um formulário HTML. Assim a tarefa de se criar um CGI, fica resumida apenas a criar o algoritmo necessário para implementar o que se deseja sem perder tempo tratando se o formulário foi enviado pelo método GET ou POST.

Todos os argumentos passados por um formulário html ficam armazenados numa variável do tipo tcgivar, após o uso da função pega_arg. Para se acessar o valor de um argumento, têm-se duas funções: val_arg e val_marg

A C_CGI traz ainda duas outras funções: tot_arg e iniciar_cgi. A primeira simplesmente retorna o número total de valores armazenados na variavel tcgivar e a segunda envia, ao servidor web, o content-type.


Onde Obter

Voce poderá fazer o download aqui mesmo, por seu próprio risco. A C_CGI funciona perfeitamente sob Linux ou Windows, pois possui apenas funções de bibliotecas padrão do C. O arquivo compactado abaixo vem com o código fonte. Para saber como compilar seus programas em C, usando a C_CGI, veja a seção abaixo.

Download: c_cgi.tar.gz


Definições

São valores definidos na C_CGI.H que dão informações importantes ao programador. No momento há apenas quatro definições:

Exemplos (rodando na máquina local, como teste):

printf("%s", PAG_CGI); retornaria algo como /cgi-bin/teste.

printf("%s", PAG_ORIG); retornaria algo como http://127.0.0.1/teste/.

printf("%s", USU_NAVEG); retornaria algo como Mozilla/4.7 [pt_BR] (X11; U; Linux 2.2.12-5cl i686).

printf("%s", USU_IP); retornaria algo como 10.0.0.1.


void iniciar_cgi(char *tipo)

Objetivo: Enviar ao servidor web qual será o tipo da saída do CGI.

Parâmetros:

Exemplos:


tcgivar* pega_arg();

Objetivo: Armazenar todos os argumentos passados pelo formulário, já decodificando os caracteres estranhos. Essa função tem que ser usada antes das funções tot_arg, val_arg e val_marg.

Exemplo:


int tot_arg(tcgivar* t);

Objetivo: Retornar o total de argumentos passados pelo formulário.

Parâmetros:

Exemplo:


char* val_arg(const char *arg, tcgivar* args);

Objetivo: Retornar o valor do argumento identificado por arg.

Parâmetros:

Exemplo:


char** val_marg(const char *arg, tcgivar* args);

Objetivo: Retornar o valor de todos os argumentos identificados pelo nome arg.

Parâmetros:

Exemplo:

------------------------------------------------------------------------

Construindo um CGI, usando a C_CGI

Para construir um CGI você precisará primeiramente de um formulário em HTML que remeta os dados ao CGI (isso não é necessário, mas na maioria dos casos será utilizado). Neste exemplo eu usarei o formulário HTML cgi_exemplo.htm.

Abaixo esta transcrito o CGI criado para interpretar os dados do formulário de exemplo. Esse CGI será explicado calmamente mais tarde. O formulário de exemplo contém todos os tipos de campos de um formulário (exceto o campo file) a fim de ilustrar o uso da C_CGI com esses campos.

O CGI acima foi dividido em diversas partes, para facilitar a explicação:

Parte 1:
É a simples declaração das bibliotecas que serão utilizadas pelo programa. Se você for usar as funções de C_CGI, não poderá esquecer de declarar a c_cgi.h.

Parte 2:
Ao declarar as variáveis que serão utilizadas no programa deve-se, obrigatoriamente, declarar um ponteiro do tipo tcgivar que receberá as informações da função pega_arg(), caso contrário nenhuma outra função da c_cgi poderá ser utilizada. Nesse exemplo eu declarei também um ponteiro do tipo char para cada um dos campos do formulário. Repare que o campo fpagto é um ponteiro para ponteiro, visto que ele receberá as informações de quais formas de pagamento foram escolhidas (todos os checkboxes referentes à forma de pagamento possuem o mesmo nome). Já na escolha do sistema operacional cada um dos checkboxes possui um nome diferente, por isso fui obrigado a declarar uma variável para cada opção de sistema operacional. O uso da primeira forma (todos os checkboxes com o mesmo nome) é util quando se quer saber quais opções foram selecionadas (no caso da forma de pagamento), já o segundo caso (cada checkbox com um nome diferente) se faz necessário quando se deseja saber se uma determinada opção está selecionada ou não (que é o caso do sistema operacional, visto que eu posso permitir que o usuário baixe determinados arquivos caso seu sistema operacional for X).

Parte 3:
Após declarar cada uma das variáveis, preciso dar valores a elas. É para isso que serve a função val_arg e val_marg. A função val_arg retorna o valor especificado pelo primeiro parâmetro, enquanto que a função val_marg retorna todas as opções marcadas de um checkbox onde todos os itens possuem o mesmo nome.

Parte 4:
Devo agora testar se todos os campos foram preenchidos, para isso eu atribuo valor 1 à OK caso todos os campos foram preenchidos e atribuo 0 se ocorrer o contrário. Para os campos de tipo texto eu devo testar se seu comprimento é zero (para isso uso a função strlen da stdio). Já os campos booleanos (checkboxes) e campos de múltiplas escolhas (radios) eu simplesmente testo se o valor da variável é nulo.

Parte 5:
Antes de escrever qualquer coisa na página, devo informar ao servidor que o resultado desse cgi é uma página HTML, para isso uso a função iniciar_cgi passando o valor nulo. Logo em seguida eu coloco a parte inicial da página que será escrita tendo o usuário preenchido todos os campo ou não.

Parte 6:
Agora testo o valor da variável ok e, caso seje zero, forneço uma mensagem de erro ao usuário.

Parte 7:
Se a variável ok tiver valor 1, simplesmente imprimo o valor de cada variável. Se a variável se referir a um campo texto ou a um textarea eu simplesmente trato eles como se fossem strings normais do C (podendo usar qualquer função que imprima uma string).

Parte 8:
Se a variável for um checkbox onde cada opção possui um nome diferente, eu devo testar se o valor dessa variável é nulo. Se for é porque a opção referente não foi marcada, caso contrário ela foi marcada.

Parte 9:
Se a variável for um checkbox onde todas as opções possuem o mesmo nome, eu devo fazer um loop dentro da variável até encontrar um nulo.

Parte 10:
Resta apenas colocar a parte final da página que será escrita tendo o usuário preenchido todos os campo ou não.

------------------------------------------------------------------------

Compilando um Programa que use a C_CGI

Para explicar como se compila um programa usando a C_CGI, irei usar como convenção que o nome do arquivo fonte é fonte.c e que a c_cgi.c (ou c_cgi.o) está no mesmo diretório de fonte.c. Explicarei como compilar o fonte.c usando os seguintes compiladores: Borland C 3.1 para DOS, Borland C/C++ para Windows, DJGPP com Rhide e GCC do Linux. Além disso, será mostrada uma forma genérica para o uso da c_chi, que deverá funcionar em qualquer compilador.

 

Você pode criar um CGI com estes e quaisquer outros compiladores da forma que mostraremos a seguir. Para isto basta ter os arquivos c_cgi.c e c_cgi.h, que são os fontes da C_CGI. Vamos supor novamente que estes estão no mesmo diretório do seu arquivo fonte.c
Primeiramente, abra seu código fonte (fonte.c) com um editor qualquer.
Deve haver uma referência ao arquivo da c_cgi.c, tal como mostrada abaixo:
#include "c_cgi.c"
Isto fará com que as funcões da c_cgi sejam reconhecidas em seu programa e você as possa usar normalmente
Feito isso, basta recompilar seu projeto como se ele fosse um simples programa, isto é, como se ele não utilizasse nenhuma biblioteca adicional. A forma como você fará isso depende do seu compilador.
No caso do Borland C/C++ 5, por exemplo, vá no menu Compile e escolha Build All.

------------------------------------------------------------------------

Exercícios

 

Índice