Formulários de contacto @ L.V. Expertise X3

Funcionamento

Nós apresentamos o método a seguir para criar um "formulário XTEND" em desencadeando uma ação "Registar" sobre o objecto X3 AYZ a partir de um clique sobre um botão da página HTML. Os dados do formulário são registadas por utilizador nos campos do formulário HTML e são passados em parâmetro da ação.

Se vosso estabelecimento XTEND foi criado a partir de uma cópia do estabelecimento ASAMPLE as fichas de parametrização estão já criadas.

Senão pode seja os criar seja os copiar um a um a partir do estabelecimento ASAMPLE com o botão de ação X3 "Cópia".

Um formulário XTEND está constituido :

de um cabeçalho (bloco lista) :

O sujeito (TTL)
O email de utilizador (MAICOD))
A memsagem (CMT)
o Tipo (TYP)

de parâmetros (bloco quadro) utilizados para gerir as opções :

O literal (PARCOD)
O valor (PARVAL)

Os dados calculados à criação são o código (FRMCOD), o estatuto (STATUT) e a data de criação (CREDAT).

No nosso exemplo nós vamos criar um formulário de pedido de contacto (TYP=CON) com as opções seguintes afectando a pessoa :

Sociedade
Atividade
Código postal

Criação

Criaação de uma página HTML (AXTDFRMCREATE) com um formulário de registo.
Para exempo dos dados do formulário serão transmitidas em modo criptado (HTTPS)
Criação de uma interface (AXTDFRM) para chamada do web service
Criação de uma ação Web de tipo criação de objeta X3 (AXTDFRMCREATE) tendo por parâmetros em entrada o Título, o email, o comentário e a lista das opções selecionadas.
Estes parãmetros serão "mapeados" sobre os parãmetros em entrada do web service.
Criação de um token ligação dinâmica (ADLKCONTACTNEW) que será inserida na página HTML (botão "Criar") para valorizar os parâmetros com o valor dos campos do formulário HTML e desencadear a ação.

Afixação

Após a ação de criação, o formulário será afixado em modo não registável na página corrente para que o utilizador possa verificar o conteúdo.

Esta operação consiste ler os dados reenviados pelo web service (entidade e parâmetros) e a os afixar ao ecrã.

A leitura se faz por "mapping" dos parâemtros em saída do web service versus duas entidades XTEND (XTDFRMHEAD e XTDFRMPARAM) para criar os dados em memória e inserindo 2 tokens blocos (ABLKFRMHEAD e ABLKFRMPARAM) na página HTML para afixar os dados.

A gestão de afixaação (formulário de registo ou formulário criado não registável) na mesma página está assegurada por um token "bloco condicional" (ACNDXTDFRMHIDE)

Consulta :

Os formulários criados podem ser consultados via a função X3 Formulário (GESAYZ)

Parametrização X3

Este parágrafo vem em complemento do procedimento de criação de uma ação utilizador.

Etapa 1 - Criação de interface

1. Criar a interface "Ação utilizador objeto" AXTDFORM baseado sobre o nome de publicação de objeto AYZ (AXTDAYZ)

2. gerar o acesso

3. Gerar todos os campos de interface
Ver o menu "Utilitários/Criação token campo"

Etapa 2 - Criações das entidades

Criar as entidades :

AXTDFRMHEAD com os campos de cabeçalho
XTDFRMPARAM com os campos das opções PARCOD e PARVAL

Ver o menu Utilitários\Ajuda no preenchimento.

Estas entidades serão em seguida utilizados no mapping retorno de ação de criação do formulário.

No exemplo n´s temos definido 2 chaves para AYZ

FRMCOD que correspondem ao identificante do formulário
FCYCOD que é o código de estabelecimento XTEND e que é igual ao código do estabelecimento corrente.

FCYCOD filtra os formulários em função do estabelecimento corrrente ASAMPLE.

Falta supimir esta chave se deseja ler todos os formulários da base.

Etapa 3- Criação da ação web

Declaração dos parãmetros

Criar uma ação AXTDFRMCREATE de tipo "standard" com para parametrizadas o tipo, o título, o email, o cometário e as opções.

Apenas os parãmetros do web services que dependem do contexto de chamada da ação são declaradas como parãmetros de ação em registo.

É o token ligação dinâmica que indica como serão valorizadas em função do contexto de chamada (campo web, campo XTEND...)

Supressão em início
assinalada para suprimir as entidades AXTDFRMHEAD e AXTDFRMPARAM ao início de ação (antes o resultado de chamada do sub-programa) afim de gerar correctamente a afixação do resultado na mesma página HTML com ajuda de um token "bloco condicional" baseado sobre a presença do campo FRMCOD.

Seguimento de atividade
Sim : para que cada chamada de ação seja registada no ficheiro de log

Ativo sobre reload
Não : para não recriar um formulário se o utilizador apoia sobre F5 após ter criado um formulário;

Ativação botão
Criar : para desencadear o botõa de ação Registar de objeto AYZ

Mapping dos parâmetros em entrada

Trata-se de fazer corresponder os campos XTEND com os parâmetros de chamada do web service.

No nosso caso devemos fazer unicamente um mapping dos parâemtros de ação TYP, TTL, CMT,MAIDCOD, PARCOD e PARVAL.

O mapping de PARCOD e PARVAL é de tipo Multi o que permite ao servidor XTEND de "mapear" vários campos HTML de mesmo nome sobre um parãmetro multi-dimensionado.

Para "maperar" os parãmetros de ação não se regista o código da entidade.

Os parâmetros do web services cujo valor provém sempre do mesmo contexto podem ser valorizados directamnte no mapping de ação em indicando a entidade.

Por exemplo se deve passar o código de utilizador de login podrer-se-á mapear directamemte com o campo AUSERCODE da entidade ASESSION mais cedo de declarar em parâmetro de ação.

Mapping dos parâmetros em saída

Trata-se de criar duas entidades XTEND a partir dos dados reenviados por X3

AXTDFRMHEAD para guardar os campos dos ecrãs lista
AXTDFRMPARAM (Multi) para guardar os campos do bloco quadro que contém os parâmetros

As entidades de tipo Ação são guardadas em memória durente toda a duração da sessão utilizador.

Elas são recriadas automaticamente a cada chamada de ação

Ação de supressão das entidades

Para gerar a afixação via um "bloco condicional" tem necessidade de suprimir as entidades a primeira vez que a página se afixa (quando um clique sobre o token ligação dinâmica ADLKCONTACT no menu esquerdo)

Para tal se cria uma ação AXTDFRMRESET que não faz que suprimir as entidades AXTDFRMHEAD e AXTDFRMPARAM.

Esta ação está associada ao token ADLKCONTACT.

Tipo
Standard

Interface
Nenhum

Etapa 4- Criação da ligação dinâmica

A ligação dinâmica ADLKXTDFRMCREATE é o token que será inserido no botão de criação do formulário.

Permite definir a página de destino (Página corrrente), de associar a ação AXTDFRMCREATE e de valorizar os parâmetros

Parâmetros gerais

Seguimento de atividade
Sim : para que cada clique sobre a ligação registada no ficheiro de log

Forçar o modo http posto
Não : Como uma ação com parâmetros está associada à ligação dinâmica, o pedido será enviado automaticamnte em modo POST

Página corrente
Sim : O resultado (mensagem ou formulário criado) está afixado na página corrente

Ação
Código de ação a desencadear

Controlar os campos web
Sim : Para controlar os parâmetros Web (ver secção "Ação")

Parâmetros da ação.

Transação de declarar todos os parâmetros de ação e de indicar a maneira cujo se deseja os valorizar.

Campo TYP
Constante : O tipo de formulário é sempre de tipo contrato (CON)

Campos TTL, MAICOD
'Chp Web Oblig' : Registo obrigatório por um campo web.

Campos CMT, PARCOD, PARVAL
"Campo web" : Registo por um campo web não obrigatório.

Cste/Attrib. web
Contém o nome do tag input (atribuido ao nome)

O controlo de registo não está ativo que se a opção "Generalidades/Controlar campos web" está assinalado.

O pedido será colocado versus o servidor XTEND apenas se :

utilizador valorizou todos os campos obrigatórios
os dados registados são correctos para os campos de tipo data e numérica.

O controlo está efectuado pela biblioteca JavaScript d'XTEND.

Token de afixação da página

O token ADLKCONTACT permite afixar a página de criação do formulário a partir de um menu esquerdo.

Para gerar a afixação via o "bloco condicional" ACNDXTDFRMHIDE é necessário de apagar as entidades formulário à primeira afixação.

Esta operação é efetuada em associando a ação AXTDFRMRESET ao token ADLKCONTACT.

Este token permite também de afixar a página em modo segurança (https) para indicar ao utilizador que os dados serão encriptados.

Seguimento de atividade
Sim :

Forçar o modo posto
Sim : Para conservar o contexto de XTEND salavaguarda na página corrente.
O modo HTTP GET está utilizado unicamente sobre as ligações de tipo "âncora" que devem ser compatíveis com os motores de pesquisas (web crawlers).

Página corrente
Non/AXTDFRMCREATE : Página de destino

Ação
AXTDFRMRESET : Para apagar as entidades formulário

Etapa 5 - Criação dos tokens bloco

Os token blocos ABLKFRMHEAD et ABLKFRMPARAM são utilizados para afixar as entidades AXTDFRMHEAD e AXTDFRMPARAM que representam os dados de um fromulário XTEND.

Bloco de entidade

Tipo
Mono registo : Lê a entidade AXTDFRMHEAD e coloca o dado ao extremo (top) da pilha do contexto de dados depois executa os tokens filhos.

Nenhum dado
Nada a afixar : Se entidade AXTDFRMHEAD não existe o bloco e os tokens "filhos" são ignorados

Entidade
AXTDFRMHEAD : Código de entidade a afixar

Bloco parâmetros

Tipo
Multi-registos : Efetua uma iteração sobre todas as entidades AXTDFRMPARAM e posiciona cada entidade ao extremo (topo) da pilha do contexto de dados depois executa os tokens filhos

Nenhum dado
Nada a afixar : Se a entidade AXTDFRMPARAM não existe bloco e os tokens "filhos" são ignorados

Entidade
AXTDFRMPARAM : Código de entidade a afixar

Linha por bloco
10 : Afixa 10 entidades AXTDFRMPARAM máximo na página.

Célula por linha
1 : Afixa uma entidade AXTDFRMPARAM por linha

Estilo por linha
Nenhum : Estilos a definir no ficheiro "my.css" para alternar a cor de fundo das linhas

Não é possível de definir os critérios de seleção sobre os blocos que selecionam as entidades guardadas em memória do servidor XTEND, quer dizer de tipo sessão ou Ação. O bloco seleciona automaticamente todas as entidades.

Os critérios de seleção se aplicam unicamnte que às entidade de tipo "Acesso dados"

Etapa 6 - Criação do token bloco condicional

Trata-se ilustrar o caso de utilização dos blocos condicionais.

O token ACNDXTDFRMHIDE está utilizada para modificar o conteúdo da página da presença ou não de um formulário

Se a entidade AXTDFRMHEAD existe (bloco ABLKFRMHEAD não vazio) é este um formulário foi criado e que falta afixar
Se a entidade AXTDFRMHEAD não existe (bloco ABLKFRMHEAD vazio) o que falta afixar os campos de registo.

Afixação
Não assinalada : Indica que o conteúdo do token (html e tokens filhos) está mascarado se a condição está verificada.

Tipo de critério
Bloco vazio : Indica que a condição de afixação/máscara está baseada sobre o facto que um bloco contém ou não os dados

Bloc
ABLKFRMHEAD : Código do bloco a testar

Para que os campos de registo sejam afixados à primeira afixação da página, mesmo se um formulário foi criado anteriormente, nós temos criado uma ação AXTDFRMRESET que suprime as entidades formulário.

Esta ação está chamada pelo token ligação dinâmica ADLKCONTACT que afixa a página de criação de um formulário a partir de um clique no menu esquerdo.

Etapa 7 - Criação da página

Criar a página web AXTDFRMCREATE.

Página por defeito
Associar o ficheiro contact.html.
O ficheiro deve estar presente sobre o servidor X3 e pode ser selecionado pela tecla F12.

Protocole
Https : Para indicar que falta encriptar os dados do pedido Http (Ver configuração HTTPS)

Bloco principal e bloco de fundo
Nenhum

Acesso protegido
Não: para indicar que esta página está em acesso livre (anónimo)

Seguimento de atividade
Sim : para que cada afixação da página seja registada no ficheiro de log

Etapa 8 - Validação do estabelecimento

Após modificação dos parâmetros X3 é aconselhado de validar a integralidade do estabelecimento via a função afim de reconstruir o dicionário do servidor XTEND via a função 'Validação estabelecimento Web(AYTFCYGEN)".

Bem verificar que o estabelecimento XTEND está publicado, quer dizer o campo "Publicado o estabelecimento" da ficha "Estabelecimento web" está assinalado.

Página HTML

Ligação versus a página

Inserção do token "ligação dinâmica" ADLKCONTACT no menu esquerdo para afixar a página e suprimir o último formulário criado.

<TD class="botão"><A adx="ADLKCONTACT">Contacte-nos</A></TD>

Gestão da afixação

O token "bloco condicional" ACNDXTDFRMHIDE permite afixar o registo de formulário se nenhum formulário XTEND não foi encontrado senãoafixa o conteúdo do formulário.

<!adx="ACNDXTDFRMHIDE">

<!adx="ACNDXTDFRMHIDE">
<!adx="ACNDXTDFRMHIDE:xNot">


<!adx="ACNDXTDFRMHIDE">

Registo de cabeçalho

Criaação de campos <input> com o token adx="NomDuChamp".

Se não se indica o atributo nome num tag <input> será gerado automaticamente com o nome do token adx.
O parâmetro xrc(<input adx="TokenName:xrc">) está utilizada para reafixar o último valor registado em caso de erro de registo detectado pelo servidor XTEND ou a aplicação X3.
Permite de evitar de perda dos dados registados

<H1>Nos contactar</H1>
<tabela>
   <tr>
      <td><b><b>Email:</b></td>
      <td>
          <input type="texto" adx="MAICOD:xrc" size="50">
      </td>
   </tr>
   <tr>
      <td><b><b>Sujet:</b></td>
      <td>
          <input type="texto" adx="TTL:xrc" size="50">
      </td>
   </tr>
   <tr>
      <td><b>Mensagem:</b></td>
      <td>
          <textarea adx="CMT:xrc" rows="5" cols="75"></textarea>
      </td>
   </tr>
</table>

Registo das opções

Criação de conjuntos de campos <input> tipo Chave/Valor que serão "mapeados" sobre 2 colunas de um bloco quadro ou dois parâmetros de dimensão N de um sub-programa.

PARVAL contém o valor registo por utilizador
PARCOD contém o código que tem um valor cinco e que não está visivel ("hidden")

O mapping dos conjuntos PARCOD/PARVAL com os parãmetros do web service é efetuado seguinte a ordem de criaação dos campos na página HTML.

<tr>
    <td><b>Sociedade:</b></td>
    <td>
        <input type="Text"   adx="PARVAL:xrc" size="50">
        <input type=escondido" name="PARCOD" value="Sociedade">
    </td>
</tr>
<tr>
    <td><b>Actividade:</b></td>
    <td>
        <select adx="PARVAL">
            <option value="">Préciser :</option>
            <option value="Artesanos" >Artisans</option>
        </select>
        <input type="hidden" name="PARCOD" value="Actividade">
    </td>
</tr>
<tr>
    <td><b>Código postal:</b></td>
    <td>
        <input type="text"   value="" adx="PARVAL:xrc" size="10">
        <input type="hidden" name="PARCOD" value="Código Postal">
    </td>
</tr>

Botão de criação

Criação de um input de tipo "botão" com o atributo adx que contém o código da ligação dinâmica

Todos os botões <input type="botão"> que contém os tokens adx devem ser de botão.
O tipo submite não deve ser utilizado.

Uma ação utilizador é considerada como validad se A chamada do web service não renvia nenhuma mesagem de erro.

As mensagens de erro são colocadas em L4G via o sub-programa ADDMESSERR (Call ADDMESSERR("Mensagem") From AWEB)

A afixaação das mesagens X3 e´efetuada via o token AXUSERMSG.

Ex : <span id="userMsg" class="userMsg" adx="aMsgUser"></span>

Controlo automático do registo

Como os campo MAICOD e TTL foram definidos como campos web obrigatórios, o controlo é efetuado automaticamnte e não necessita nenhum acréscimo de código JavaScript.

As mensagens em caso de erro afixadas são AJSWEBFLDMANDAT (campos obrigatório) e AJSWEBFLDBADVAL (erro de formato).

Controlo suplementar em JavaScript

É posssível de acrescentar os controlos em JavaScript sobre os parâmetros Web em acrescentando uma função JavaScript de nome xtdWebParamCheckValue na página HTML.

Se a livraria XTEND deteta a presença desta função ela será chamada com parâmetro.

aWebParamOutl'objet que representa o parâmetro

aWebParamOut .setValue(String) valoriza o parâmetro
aWebParamOut .getValue() reenvia o valor do parâmetro

aInputFieldName o código do parãmetro
aInputFieldIndex l'index se aligação está colocada num bloco.
aInputFieldValue o valor do parâmetro

Esta função reenvia verdade\falso para validar\invalidar o registo

A mensagem AJSWEBFLDBADVAL está afixada em caso de erro de registo.

Na página de exemplo nós temos acrescentado uma função que controla o formato de email.

A função xtdWebParamCheck permite de fultrar os campos a controlar.

Ela funciona segundo o mesmo principio que xtdWebParamCheckValue.

Registo de cabeçalho

O bloco ABLKFRMHEAD permite posicionar o contexto de dados.

Os campos são afixados via um token adx colocado num tag HTML

<table width="90%" border="0" cellspacing="2" cellpadding="4">
<!adx="ABLKFRMHEAD">
    <tr>
        <td><b>Email:</b></td>
        <td adx="MAICOD"></td>
    </tr>
    <tr>
        <td><b>Sujet:</b></td>
        <td adx="TTL"></td>
    </tr>
    <tr>
        <td><b>Message:</b></td>
        <td><pre adx="CMT"></pre></td>
    </tr>
<!adx="ABLKFRMHEAD">
</table>

Afixação das opções

o bloco ABLKFRMPARAM permite de iterar sobre as opções do formulário e de criar tantas linhas <tr> que de opções.

Para cada opção, XTEND posiciona um contexto de dados o que permite de resolver o valor dos tokens adx PARCOD e PARVAL colocados nas tags HTML.

<!adx="ABLKFRMPARAM">
    <tr>
        <td><b adx="PARCOD"></b></td>
        <td adx="PARVAL"></td>
    </tr>
<!adx="ABLKFRMPARAM">

O

O ponto de entrada pageDoMyDlk permite acrescentar uma tratamento sobre clique utilizador e de anular o processo em curso se o valor falso está reenviado.

No nosso caso pede-se uma confirmação antes de colocar o formulário versus o servidor XTEND.

//Asks user to confirm creation of a new form if user clicks on ADLKCONTACTNEW dynamic link
function pageDoMyDlk(aDomOut)
{
    if (aDomOut.isDlk("ADLKCONTACTNEW"))
        return confirm('Confirmar a criação do formulário\nConfirm criação');
    devolve verdade;
}

O ponto de entrada xtdWebParamCheckValue faz parte do mecanismo de controlo dos valores dos "campos web" XTEND (parâmetros web das ações XTEND).

Se a função xtdWebParamCheckValue está definido na página HTML, ela será chamada pela livraria XTEND para cada controlo de "campo web".

No nosso caso controla-se o valor do campos MAICOD (email) via a função XTEND xtdCheckEmail.

//This function is used to customized control on web parameters values
function xtdWebParamCheckValue(aWebParamOut,aInputFieldName,aInputFieldIndex,aInputFieldValue){
    // Check input email value
    if (aInputFieldName=="MAICOD"){
        var wEmail=xtdCheckEmail(aInputFieldValue);
        if (wEmail && wEmail!=aInputFieldValue)
            aWebParamOut.setValue(aInputFieldIndex,wEmail);
        return wEmail!=null;
    }
    return true;
}