Protheus e AdvPL ASP – Parte 02

Introdução

No post anterior, começamos a entrar no mundo do AdvPL ASP. Dando continuação a esta jornada, agora vamos ver alguns recursos deveras interessantes desse universo.

Recebendo parâmetros do Browse em AdvPL ASP

Como mencionado no post anterior, a utilização dos arquivos APH é uma parte fundamental para criarmos com facilidade páginas dinâmicas usando AdvPL ASP. E, como também vimos, as páginas são compiladas no RPO, e sua execução está atrelada a uma configuração de um pool de threads de processamento — indicado na seção HTTP ou no host pela configuração RESPONSEJOB, e da passagem pela função configurada neste job para atender uma conexão — configuração ONCONNECT. Um ponto interessante sobre o Pool de Processos configurado é o seu tipo — TYPE=WEBEX.

Esta configuração habilita um recurso chamado de “Alias Virtuais” para receber valores do Browse, via URL (GET) ou via POST de formulário, bem como criar e utilizar variáveis de SESSION por usuário, verificar parâmetros recebidos no cabeçalho (header) da conexão HTTP, Cookies de memória e até criar parâmetros de retorno no cabeçalho HTTP que será enviado junto da string de retorno ao Browser.

*** Existem alguns métodos no protocolo HTTP com outras funcionalidades, porém os mais usados para recuperação e envio de informação são os métodos GET e POST, que são tratados pelo Protheus como HTTP Server. Os demais métodos são ignorados ***

A definição de “Alias Virtual” é exclusiva do AdvPL, o “Alias” é um apelido que nós podemos dar a uma tabela ou query aberta em um programa, que permite acessar o valor de um campo da tabela usando a sintaxe ALIAS->CAMPO. Os Alias Virtuais do AdvPL ASP são nomes reservados de componentes que na verdade não são tabelas, mas permitem o uso da mesma sintaxe, com algumas vantagens.

Todos os Alias Virtuais mencionados nesta documentação são criados automaticamente e dinamicamente dentro do contexto do processamento de uma requisição via link .apw, e o escopo do alias é público, isto é, ele pode ser acessado de qualquer ponto da pilha de chamadas durante o processamento da requisição. Neste post, vamos ver o alias virtual HTTPGET e o HTTPPOST

Alias Virtual HTTPGET

Através dele podemos receber parâmetros via URL do Browse. Esta é uma das formas de passar parâmetros do Browse para a aplicação AdvPL. Quando informamos uma URL para ser aberta por um Browser de Internet, ele submete uma requisição HTTP do tipo “GET” para o servidor web indicado na URL.

A sintaxe para esta passagem de parâmetros segue a especificação da montagem de uma URL, que segue o padrão http://host-ou-dominio/pasta/pagina.apw?p1=x&p2=y&p3=0&…

A primeira interrogação indica o final da identificação da página na URL e o início dos parâmetros. Cada parâmetro é composto de uma tupla chave=valor, onde cada tupla é separada pelo símbolo & (“e” comercial).

Quando vamos informar um valor na tupla, precisamos tomar cuidado para não colocar caracteres reservados diretamente como valor, senão eles podem ser interpretados  de outra forma, como por exemplo p1=C&A não vai ser interpretado desta forma … na verdade quem receber esta requisição vai entender que foi recebido um parâmetro chamado p1, com o conteúdo “C”, e um segundo parâmetro chamado “A”, sem valor. A forma correta de se passar C&A neste caso seria p1=C%26A, onde o “&” foi codificado no formato %HH — sinal percentual seguido de dois dígitos hexadecimais correspondentes ao caractere a ser enviado como valor na tabela ASCII.

Por padrão, no AdvPL ASP, o Protheus Server faz a identificação dos valores informados pela URL e cria os “campos” correspondentes dentro do alias virtual. Porém, devemos lembrar que, para efeitos da Linguagem AdvPL, um nome de campo segue as mesmas regras do nome de uma variável do AdvPL: Deve começar com uma letra, e conter apenas símbolos alfanuméricos (letras de A a Z, números de 0 a 9). Passar um parâmetro via URL sem atentar-se a este formato torna impeditivo o uso do Alias Virtual HTTPGET para buscar o valor de um parâmetro. A vantagem é que o tamanho deste identificador não está limitado a 10 posições, como é o caso das variáveis e nomes de campos de tabelas do AdvPL.

HTTPGET – Exemplo de Uso

Vamos aproveitar os programas do exemplo anterior, e apenas estender algumas funcionalidades. Por exemplo, vamos criar uma chamada de link .apw para chamar um APH, que vai montar uma tela HTML mostrando dois parâmetros recebidos pela URL : ID e NOME.

do case
case cAspPage == 'index'
  // Execura a página INDEX.APH compilada no RPO 
  // A String retornada deve retornar ao Browser
  cReturn := H_INDEX()
case cAspPage == 'getinfo'
  // Executa a pagina GetInfo.APH 
  cReturn := H_GETINFO()
otherwise
  // retorna HTML para informar 
  // a condição de página desconhecida
  cReturn := "<html><body><center><b>Página AdvPL ASP não encontrada.</b></body></html>"
Endcase

Agora, vamos criar e compilar o arquivo GETINFO.APH com o conteúdo abaixo:

<html><body>
<p>Informações por GET</p>
<p>ID = <%=HTTPGET->ID%></p>
<p>NOME = <%=HTTPGET->NOME%></p>
</body></html>

Desta forma, se nós utilizarmos no Web Browse a seguinte URL: http://localhost/getinfo.apw?ID=0&NOME=Seu+Nome , o resultado esperado na tela do browse é:

Advpl ASP - GetInfo

Detalhes e Observações

  1. Os conteúdos dos campos recebidos via alias virtual HTTPGET serão sempre recebidos como String em AdvPL, mesmo que o conteúdo seja um número — como vemos no caso do campo ID.
  2. Para uma URL, os nomes dos identificadores podem ser informados em letras maiúsculas, minúsculas ou misturadas, isto não importa para o AdvPL. Porém, se você passar dois valores com o mesmo nome de identificador, por exemplo um “id”  e um “ID”, os dois valores informados serão retornados para o AdvPL, separados por vírgula.
  3. Como vimos no nosso exemplo, ao informar o NOME da URL, foi passado o valor do “espaço em branco” no formato para URL (sinal de “+” soma). Ao recuperar o valor em AdvPL, ele já é recuperado devidamente “decodificado”. Se, por exemplo, a URL utilizada for http://localhost/getinfo.apw?ID=0&NOME=Jo%E3o , o valor de NOME recebido no AdvPL será “João
  4. Vários Browses possuem a capacidade de codificar URLs digitadas manualmente, porém normalmente eles vão codificar os caracteres acentuados e especiais (ASCII acima do código 128) usando UTF-8. Por exemplo, ao informar o nome “João” na URL, sem fazer a codificação, o Protheus vai receber o valor “João” no nome, que corresponde a representação dele usando UTF-8. Neste caso, você somente conseguiria obter o nome correto no CP1252 (Default do Protheus) caso você use a função DecodeUTF8().
  5. Não há limite de tamanho de URL segundo a especificação, porém entre os navegadores de intermet, foi convencionado um limite próximo de 2 KB. Para todos os efeitos, eu não recomendaria passagens de parâmetro por URL com mais de 512 bytes. Existem formas mais eficientes e projetadas para transferir conteúdos maiores, como veremos adiante.
  6. Embora o nome do recurso de recuperação de valores foi chamado de “Alias Virtual”, ele não possui as capacidades de um ALIAS de uma Tabela no AdvPL. Desse modo, as únicas formas de recuperação de conteúdo são: Especificando de forma literal o identificador desejado (cValor := HTTPGET->ID) ou criando uma string com este formato e usando macro-execução — por exemplo :
cIdName := 'ID'
cValor := &('HTTPGET->'+cIdName)

Caso um determinado argumento não seja informado na URL, mas seja recuperado em AdvPL, não ocorre erro de execução, porém o retorno será do tipo “U” (NIL). Caso o identificador seja informado sem valor, ele será do tipo “C” caractere, e vai conter uma string em branco (LEN=0).

Alias Virtual HTTPPOST

Quando utilizamos um formulário de dados em HTML, podemos criar campos para entrada de dados na tela do Browse (campos do tipo INPUT), e quando submetemos o formulário para uma URL com link apw no AdvPL ASP, podemos recuperar o conteúdo dos campos informados através do alias virtual HTTPPOST.

De forma similar ao HTTPGET, usamos o identificador do campo INPUT do formulário HTML para recuperar o valor informado no campo. Embora seja possível criar um formulário que passe o valor dos campos via URL (Formulário submetido com o método GET), é praxe criarmos o formulário no HTML com o método de submissão “POST”. Vamos pro exemplo que fica mais fácil.

Primeiro, precisamos de dois novos arquivos APH: Um deles vai ser o formulário HTML com os campos a serem preenchidos, e a outra página será responsável por receber os dados do formulário e mostrá-los no Browser. Para isso, primeiro acrescentamos o tratamento adequado no tratamento da URL recebida pelo Protheus Server:

case cAspPage == 'formpost'
  // Executa a pagina FormPost
  cReturn := H_FORMPOST()
case cAspPage == 'postinfo'
  // Executa a pagina PostInfo
  cReturn := H_POSTINFO()

Agora, vamos criar o arquivo FormPost.aph, que vai conter o formulário HTML com os campos para serem preenchidos.

<html><body>
<p>Formulário de POST</p>
<form action="/postinfo.apw" method="post">
First name:<br>
<input type="text" name="firstname"><br>
Last name:<br>
<input type="text" name="lastname">
<hr>
<input type="submit" value="Enviar">
</form>
</body></html>

Agora, vamos criar o arquivo PostInfo.aph, que vai mostrar os conteúdos recebidos.

<html><body>
<p>Dados Sumbetidos</p>
<p>First name: <%=HTTPPOST->FIRSTNAME%><br>
Last name: <%=HTTPPOST->LASTNAME%></p>
</body></html>

Com tudo salvo, acrescentado no projeto e devidamente compilado, vamos ao teste abrindo a URL http://localhost/formpost.apw, e preencher os campos do formulário.

Advpl ASP - Post 1

Após preencher os campos — neste exemplo eu preenchi com “nome” e “sobrenome” — e clicar no botão “Enviar”, o resultado esperado é:

Advpl ASP - Post 2

Detalhes e Observações

Como eu estou em um Browse, eu posso usar caracteres de outros idiomas, ou símbolos que não necessariamente sejam do Code Page default do Protheus — CP1252. Neste caso, qualquer caractere que não tenha representação no CP1252 será enviado ao AdvPL usando a notação decimal do caractere Unicode para HTML, no seguinte formato: &#nnnn; , onde nnnn é o número decimal do caractere Unicode. Por exemplo, usando o Google Translate, eu traduzi a palavra “teste” para russo (“тест”), e colei no formulário como o sobrenome do cidadão.

Teste - Cirilico

Em AdvPL, a string que eu recebi ao consultar o valor de HTTPPOST->LASTNAME está sendo mostrada logo acima. — Tive que tirar um print e gerar uma imagem, o blog não permitiu salvar o texto com a representação Unocode HTML — a visualização do post mostrava os caracteres já convertidos, e não os códigos. O caractere 1090 (decimal) da tabela UNICODE é a letra “t” minúscula em cirílico. — vide link http://www.codetable.net/decimal/1090 — bem como os caracteres subsequentes que também fazem parte do alfabeto cirílico.

Quando criamos o arquivo formpost.aph, colocamos que a ação (action) do formulário era “/postinfo.apw”, certo? Eu posso colocar parâmetros de URL (GET) em um formulário de POST? Sim, pode, e em AdvPL você recupera eles usando o alias virtual HTTPGET, como vimos no exemplo acima. Se trocarmos o action para “/postinfo.apw?OP=1”, ao consultar o conteúdo de HTTPGET->OP, devemos recuperar o valor “1” como Caractere.

Conclusão

Com tratamentos de GET e POST, aliado a páginas estáticas e dinâmicas, construímos desde uma aplicação WEB de exemplo, até um portal inteiro. Porém, para isso, vamos ver nos próximos posts mais alguns alias virtuais, e mais algumas funcionalidades interessantes do AdvPL ASP. Com o que já temos até aqui, dá pra fazer até uma Agenda … opa, CRUD em AdvPL ASP? Aguardem os próximos capítulos.

Agradeço a todos a audiência, e lhes desejo TERABYTES DE SUCESSO !!! 😀

Referências

 

 

3 comentários sobre “Protheus e AdvPL ASP – Parte 02

Deixe um comentário

Preencha os seus dados abaixo ou clique em um ícone para log in:

Logotipo do WordPress.com

Você está comentando utilizando sua conta WordPress.com. Sair /  Alterar )

Foto do Google

Você está comentando utilizando sua conta Google. Sair /  Alterar )

Imagem do Twitter

Você está comentando utilizando sua conta Twitter. Sair /  Alterar )

Foto do Facebook

Você está comentando utilizando sua conta Facebook. Sair /  Alterar )

Conectando a %s