4D Doc Center : Ações URL e Formulário

4D v14.3

Ações URL e Formulário

O servidor web 4D oferece diferentes URLs e ações de formulários HTML especiais que permitem implementar diferentes ações em seu banco.
Essas URLs são as seguintes:

4DACTION/, para associar um objeto HTML a um método de projeto de su banco,
4DCGI/, para chamar o Método de banco de dados On Web Connection desde um objeto HTML.
4DSYNC/, para sincronizar os dados das tabelas.

Adicionalmente, o servidor web 4D aceita várias URLs adicionais:

/4DSTATS, /4DHTMLSTATS, /4DCACHECLEAR e /4DWEBTEST, para permitir-lhe obter informação sobre o funcionamento de seu site Web 4D. Essas URLs são descritas na seção Informação sobre o Website.
/4DWSDL, permite o acesso ao arquivo de declaração dos Serviços web publicados no servidor. Para maior informação, consulte a seção Comandos de Serviços Web (Servidor) e o Manual de Disenho.

URL 4DACTION/

Sintaxe: 4DACTION/MeuMétodo{/Param}

Uso: URL ou ação de formulário.

Esta URL permite associar um objeto HTML (texto, imagem, botão...) a um método de projeto 4D. Este link será do tipo /4DACTION/MeuMetodo/Param onde MeuMétodo é o nome do método de projeto 4D a ser executado quando o usuário clicar no link e Param um parâmetro opcional de tipo Texto passado ao método em $1 (ver o parágrafo “Os parâmetros Texto passados a os métodos através os URLs”).

Quando 4D recebe uma petição /4DACTION/MeuMetodo/Param, se chama o método de banco On Web Authentication Database Method (se existir). Se retorna True, se executa o método MeuMétodo.
4DACTION/ pode estar associado a uma URL em uma página web estática. A sintaxe da URL deve ser desta forma:

<A HREF="/4DACTION/MeuMetodo/Param"> Fazer algo</A>

O método de projeto MeuMétodo geralmente deve devolver uma "resposta" (envio de página HTML utilizando WEB SEND FILE ou SEND HTML BLOB, etc.). Tenha certeza de fazer os processos tão curtos quanto possível para não bloquear o navegador.

Nota: um método chamado por 4DACTION não deve chamar aos elementos de interface (DIALOG, ALERT...).

Advertência: para que um método 4D possa ser executado através da URL 4DACTION/, deve ter o atributo “Disponível através 4DACTION, 4DMETHOD e 4DSCRIPT” (deselecionado por padrão), definido nas propriedades do método. Para maior informação sobre este ponto, consulte a seção Conexões de Segurança.

Exemplo 1

Este exemplo descreve a associação da URL 4DACTION/ com um objeto HTML imagem com o objetivo de mostrar dinamicamente uma imagem na página. Insira a seguinte instrução em uma página HTML estática:

<IMG SRC="/4DACTION/IMAGENDESDELIB/1000">

O método IMAGENDESDELIB é o seguinte:

 C_TEXT($1) `Este parâmetro deve ser declarada sempre

 C_PICTURE($PictVar)

 C_BLOB($BlobVar)

 C_LONGINT($Numero)

  `Recuperamos o número de imagem na string $1

 $Numero:=Num(Substring($1;2;99))

 GET PICTURE FROM LIBRARY($Numero;$PictVar)

 PICTURE TO GIF($PictVar;$BlobVar)

 SEND HTML BLOB($BlobVar;"Pict/gif")

4DACTION to post forms

O servidor web 4D oferece uma possibilidade adicional quando utiliza formulários “enviados”, os quais são páginas HTML estáticas que enviam dados ao servidor web. A ação do formulário deve obrigatoriamente começar por /4DACTION/NomeMetodo.

Nota: Um formulário pode ser enviado através de dois métodos (ambos podem ser utilizados com 4D):

POST, geralmente utilizado para adicionar dados ao servidor web, em um banco de dados,
GET, geralmente utilizado para fazer petições ao servidor web, dados que venham de um banco.

Neste caso, quando o servidor web recebe um formulário enviado, chama ao método de projeto COMPILER_WEB (se existir, ver abaixo), depois chama ao On Web Authentication Database Method (se existir). Se retorna True, se executa o método NomeMetodo. 4D analisa os campos HTML presentes no formulário, recupera seus valores e preenche automaticamente as variáveis 4D com seus conteúdos. O campo no formulário e a variável 4D devem ter o mesmo nome.

Nota: Para maior informação, consulte a seção QR RUN.

A sintaxe HTML a aplicar no formulário é do seguinte tipo:

Para a definição da ação do formulário:

<FORM ACTION="/4DACTION/NomeMetodo" METHOD=POST>

Para definir um campo em um formulário:

<INPUT TYPE=Tipodecampo NAME=Nomedocampo VALUE="ValorPadrão">

Para cada campo no formulário, 4D define o valor do campo para o valor da variável com o mesmo nome. Para as opções de formulários (por exemplo, caixas de seleção), 4D atribui o valor 1 à variável associada se estiver selecionada, do contrário 0.

Para as entradas de tipo numérico, 4D converte o valor do campo de Alfa–>Numérico.

Nota: Se um campo de formulário for chamado OK (por exemplo um botão Enviar), a variável sistema OK assume o valor 1 se o valor do campo não estiver vazio, do contrário assume o valor 0.

Exemplo 2

Em um banco web 4D, queremos que os navegadores possam buscar registros utilizando uma página estática HTML. Esta página se chama “buscar.html”. O banco contém outras páginas estáticas que lhe permitem, por exemplo, mostrar o resultado da pesquisa (“resultados.html”). O tipo POST foi associado a página, assim como a ação /4DACTION/SEARCH.
Este é o código HTML que corresponde a esta página:

<FORM ACTION="/4DACTION/PROCESSFORM" METHOD=POST><INPUT TYPE=TEXT NAME=VNAME VALUE=""><BR>
<!-- Geralmente colocamos o nome do botão em VALUE, por razões de interpretação, você deve colocar um número em VALUE-->
<INPUT TYPE=CHECKBOX NAME=EXACT VALUE="1">Palavra completa<BR>
<!-- OK é um caso particular-->
<INPUT TYPE=SUBMIT NAME=OK VALUE="Search">
</FORM>

Durante a entrada de dados, escreva “ABCD” na área de entrada de dados, revise a opção e confirme-a clicando no botão Pesquisar.
4D depois chama ao método de projeto COMPILER_WEB, que é o seguinte:

 C_TEXT(VNAME)

 VNAME:=""

 C_LONGINT(vEXACT)

 vEXACT:=0

 OK:=0 `particular case

No exemplo, vNOME contém a string “ABCD”, vEXACT é igual a 1 e OK é igual a 1 (porque o nome do botão é OK).

4D chama ao On Web Authentication Database Method (se existir), depois se chama ao método de processo PROCESSARFORM, que é o seguinte:

 If(OK=1)

    If(vEXACT=0) `Se a opção não for selecionada

       vNAME:=VNAME+"@"

    End if

    QUERY([Jockeys];[Jockeys]Name=vNAME)

    vLIST:=Char(1) `Return the list in HTML

    FIRST RECORD([Jockeys])

    While(Not(End selection([Jockeys])))

       vLIST:=vLIST+[Jockeys]Name++[Jockeys]Tel+<BR>

       NEXT RECORD([Jockeys])

    End while

    SEND HTML FILE(results.htm) `Envia a lista ao formuolário results.htm

  `que contém uma referência à variável vLIST (que é <!--4DVAR vLIST––>)

    ...

 End if

URL 4DCGI/

Sintaxe: 4DCGI/<action>
Modo: Both.

Uso: URL.

Quando o servidor web 4D recebe a URL /4DCGI/<action> se chama o Método de banco On Web Authentication Database Method (se existir). Se retornar True, o servidor web chama ao Método de banco de dados On Web Connection enviando a URL “tal qual” a $1.

A URL 4DCGI/ URL não corresponde a nenhum arquivo. Seu papel é chamar 4D utilizando o Método de banco de dados On Web Connection. O parâmetro “<action>” pode conter todo tipo de informação.

Esta URL lhe permite efetuar todo tipo de ação. Só necessita testar o valor de $1 no Método de banco de dados On Web Connection ou em um de seus submétodos e realizar em 4D a ação apropriada. Por exemplo, pode criar páginas HTML estáticas totalmente personalizadas para adicionar, buscar, ou ordenar registros, ou gerar imagens GIF rapidamente. Exemplos de como utilizar este URL se encontram nas descrições dos comandos PICTURE TO GIF e WEB SEND HTTP REDIRECT
Depois de uma ação, deve ser devolvida uma “resposta”, utilizando um dos comandos de envio de dados (WEB SEND FILE, SEND HTML BLOB, etc.).

Advertência: tenha certeza de executar as ações mais curtas possíveis, com o fim de não bloquear o navegador.

The Text Parameters Passed to 4D Methods Called via URLs

4D envia os parâmetros de Texto aos métodos 4D chamados pelos URLs especiais (4DACTION/ e 4DCGI/), em modos contextual e não-contextual aqui algumas observações sobre esses parâmetros:

Mesmo que não utilize esses parâmetros, deve declará-los explicitamente com o comando C_TEXT, do contrário se produzirão erros de runtime quando acessar por web a um banco executado em modo compilado. A mensagem é do tipo "Um erro runtime ocorreu na linha: 0 durante a execução do método * ON WEB CONNETION. Parâmetro inválido em um comando Executar".

Este erro runtime se produz pela ausência da declaração do parâmetro texto $1 no método 4D chamado ao fazer clic no link HTML. Como o contexto da execução é a página HTML atual, o erro hace referência a a linha "0" do método que enviou a página ao navegador web. Declarar explicitamente o parâmetro texto $1 permite eliminar esses erros:

  `M_ADD_RECORDS método projeto  *

 C_TEXT($1) ` Esse parâmetro DEVE ser explicitamente declarado

 Repeat

    ADD RECORD([Clientes])

 Until(OK=0)

O parâmetro $1 retorna os dados adicionais localizados ao final do URL e podem ser utilizados para passar os dados do ambiente HTML ao ambiente 4D.

Parâmetros para declarar de forma explícita no método 4D chamado

Deve declarar diferentes parâmetros em função da origem e da natureza da chamada do método 4D.

On Web Authentication Database Method (se existir) e Método de banco de dados On Web Connection
Deve declarar os seis parâmetros da conexão:

  //On Web Connection Database Method

 C_TEXT($1;$2;$3;$4;$5;$6) //Esses parâmetros DEVEM ser declarados explicitamente

Método chamado pela URL 4DACTION/
Deve declarar o parâmetro $1:

  //Método chamado pela URL 4DACTION/

 C_TEXT($1) //Esse parâmetro DEVE ser declarado explicitamente

Método chamado pela etiqueta 4DSCRIPT/ como uma comentário HTML em um documento
O método deve retornar o valor em $0. Você deve declarar o parâmetro $0 e $1 :

  //Método chamado pela tag 4DSCRIPT/ como um comentário HTML

 C_TEXT($0;$1) //Esses parâmetros DEVEM ser declarados explicitamente

URL 4DSYNC/

Sintaxe:
4DSYNC/$catalog{/NomTabela}
4DSYNC/NomTabela{/NomTabela}{/nomCampo1,...,nomCampoN}{Params}

Uso: URL em método POST ou GET

Esta URL sincroniza os dados das tabelas do banco 4D local com um banco remoto através HTTP. Se utiliza para sincronizar um banco 4D com uma aplicação cliente instalada em um Smartphone ou com aplicações HTTP de terceiros.

A URL 4DSYNC/ é utilizada em método GET para recuperar os dados do banco 4D ou em método POST para atualizar os dados no banco 4D.

Por razões de segurança, lhe recomendamos filtrar especificamente as URLs 4DSYNC/ dependendo de se permitem ou não a sincronização com uma aplicação ou um sistema remoto (ver abaixo as Notas sobre a sincronização com HTTP).

Estas são as diferentes petições HTTP utilizáveis:

GET /4DSYNC/$catalog

Retorna a lista das tabelas da banco e o número de registros que contém. Por exemplo para uma estrutura com duas tabelas PERSONS (2 registros) e INVOICES (3 registros), a sintaxe: http://localhost/4DSYNC/$catalog/ devolve no navegador : PERSONS 2 INVOICES 3
GET /4DSYNC/$catalog/NomTabela
Retorna a descripção da estrutura de NomTabela (formato XML).
GET /4DSYNC/NomTabela/NomCampo1{,NomCampo2},...
Retorna os dados do campo NomCampo na tabela NomTabela a partir do stamp 0 e ao formato json.
POST /4DSYNC/NomTabela/NomCampo1{,NomCampo2},...
Integra no banco 4D as modificações efetuadas no cliente.

Nota: O formato utilizado para o intercambio de dados é o JSON (JavaScript Objet Notation). A gramática completa está disponível desde o serviço de suporte técnico de 4D.

Nota: Para que os mecanismos de sincronização se ativem, a opção Autorizar o acesso via os URLs 4DSYNC deve ser selecionada na página "Web/Configuração" das Propriedades da base (ver a continuação). Caso contrário, as petições que contém o URL 4DSYNC falharão.

Notas sobre sincronização com HTTP

Quando utilizar o URL 4DSYNC/ deve considerar os seguintes princípios:

4D trabalha com a estrutura virtual da banco, se existe. Neste caso, os parâmetros NomTabela e NomCampo correspondem aos nomes de tabelas e campos que foram especificados utilizando os comandos SET FIELD TITLES e SET TABLE TITLES. Note que o alcance desses comandos é a sessão e ao utilizar 4D Server deve chamá-los em procedimento armazenado no servidor.
A replicação dos campos de tipo Blob e Imagem não é suportada.
Para poder sincronizar os dados:
- O servidor HTTP deve ser lançado
- A propriedade "Ativar replicação" deve estar selecionada para cada tabela onde deseja sincronizar os dados. Se uma estrutura tiver sido definida, estas tabelas devem ser incluidas nesta estrutura virtual. Advertência: selecionar esta opção pública informação adicional; deve ser garantida de que o acesso a seu banco esteja protegido (ver a descrição desta opção em Replicação via SQL).
- Quando 4D receber uma petição /4DSYNC, ou Método de banco On Web Aunthentication é chamado (exceto quando a senha for incorreta, ver o diagrama de conexão na seção Conexões de Segurança). Se retornar True, a petição será executada, do contrário será recusada.