Formulari di contatto @ L.V. Expertise X3

Funzionamento

Viene presentato il metodo da seguire per creare un 'formulario XTEND' attivando una azione 'Registra' sull'oggetto X3 AYZ partendo da un clic sul bottone della pagina HTML. I dati del formulario sono inseriti dall'utente nei campi del form HTML e sono passati nel parametro dell'azione.

Se il sito XTEND è stato creato partendo da una copia del sito ASAMPLE, le schede di parametrizzazione sono già create.

Altrimenti è possibile sia crearle che copiarle singolarmente a partire dal sito ASAMPLE con il bottone di azione X3 'Copia'.

Un formulario XTEND è costituito:

da una testata (blocco elenco):

L'oggetto(TTL)
La email dell'utente (MAICOD)
Il messaggio(CMT)
il Tipo (TYP)

da parametri (blocco riquadro) utilizzati per gestire le opzioni:

La descrizione (PARCOD)
Il valore (PARVAL)

I dati calcolati alla creazione sono il codice (FRMCOD), lo stato (STATUT) e la data di creazione (CREDAT).

In questo esempio si creerà un formulario di richiesta di contatto (TYP=CON) con le seguenti opzioni relative alla persona:

Società
Attività
CAP

Creazione

Creazione di una pagina HTML (AXTDFRMCREATE) con un formulario di inserimento.
Per l'esempio i dati del formulario saranno trasmessi in modo criptato (HTTPS)
Creazione di una interfaccia (AXTDFRM) per la chiamata del web service
Creazione di una azione Web di tipo creazione di oggetto X3 (AXTDFRMCREATE) i cui parametri in imput sono il Titolo, la email, il commento e l'elenco delle opzioni selezionate.
Questi parametri saranno 'mappati' sui parametri in imput al web service.
Creazione di un token link dinamico (ADLKCONTACTNEW) che sarà inserito nella pagina HTML (bottone 'Crea') per valorizzare i parametri con il valore dei campi del form HTML ed attivare l'azione.

Visualizzazione

Dopo l'azione di creazione, il formulario sarà visualizzato protetto nella pagina corrente affinché l'utente possa verificare il contenuto.

Questa operazione consiste nel leggere i dati restituiti dal web service (testata e parametri) e nel visualizzarli a video.

La lettura si fa mediante 'mapping' dei parametri in output del web service verso due entità XTEND (XTDFRMHEAD e XTDFRMPARAM) per creare i dati in memoria ed inserendo due token blocchi (ABLKFRMHEAD e ABLKFRMPARAM) nella pagina HTML per visualizzare i dati.

La gestione della visualizzazione (formulario di inserimento o formulario creato protetto) nella stessa pagina è assicurata da un token 'blocco condizionale' (ACNDXTDFRMHIDE).

Consultazione

I formulari creati possono essere consultati mediante la funzione X3 Formulario(GESAYZ)

Parametrizzazione X3

Questo paragrafo è un complemento della procedura di creazione di una azione utente.

Fase 1 - Creazione dell'interfaccia

1. Creare l'interfaccia 'Azione utente oggetto' AXTDFORM basata sul nome di pubblicazione dell'oggetto AYZ (AXTDAYZ)

2. generare l'accesso.

3. Generare tutti i campi dell'interfaccia
Vedere il menù 'Strumenti/Creazione token campo'

Fase 2 - Creazione delle entità

Creare le entità:

AXTDFRMHEAD con i campi della testata
XTDFRMPARAM con i campi delle opzioni PARCOD e PARVAL

Vedere il menù Strumenti\Aiuto alla compilazione.

Queste entità saranno in seguito utilizzate nel mapping di ritorno dell'azione di creazione del formulario.

In questo esempio sono state definite 2 chiavi per AYZ:

FRMCOD che corrisponde all'identificativo del formulario
FCYCOD che è il codice del sito XTEND e che è uguale al codice del sito corrente.

FCYCOD filtra i formulari in funzione del sito corrente ASAMPLE.

Occorre cancellare questa chiave se si vogliono leggere tutti i formulari del database

Fase 3 - Creazione dell'azione web

Dichiarazione dei parametri

Creare un'azione AXTDFRMCREATE di tipo 'standard' che ha come parametri il tipo, il titolo, l'email, il commento e le opzioni.

Solo i parametri del web service che dipendono dal contesto di chiamata dell'azione sono dichiarati come parametri dell'azione in inserimento.

E' il token link dinamico ad indicare come saranno valorizzati in funzione del contesto di chiamata (campo web, campo XTEND...).

Cancellazione all'inizio'
contrassegnato per cancellare le entità AXTDFRMHEAD e AXTDFRMPARAM all'inizio dell'azione (prima del risultato della chiamata del sotto-programma) per gestire correttamente la visualizzazione del risultato nella stessa pagina HTML con l'aiuto di un 'blocco condizionale' basato sulla presenza del campo FRMCOD.

Avanzamento dell'attività
Si: affinché ogni chiamata dell'azione sia registrata nel file di log

Attivo su reload
No: per non ricreare un formulario se l'utente preme F5 dopo aver creato un formulario;

Attivazione bottone
Crea: per attivare il bottone di azione Registra dell'oggetto AYZ

Mapping dei parametri in input

Si tratta di far corrispondere i campi XTEND con i parametri di chiamata del web service.

In questo caso bisogna fare solo un mapping dei parametri dell'azione TYP, TTL, CMT, MAIDCOD, PARCOD e PARVAL.

Il mapping di PARCOD e PARVAL è di tipo Multi, il che permette al server XTEND di 'mappare' più campi HTML con lo stesso nome su un parametro multi-dimensionato.

Per 'mappare' i parametri dell'azione non si indica il codice dell'entità.

I parametri del web service il cui valore proviene sempre dallo stesso contesto possono essere valorizzati direttamente nel mapping dell'azione precisandone l'entità.

Per esempio, se si dovesse passare il codice utente di login si potrebbe mapparlo direttamente con il campo AUSERCODE dell'entità ASESSION piuttosto che dichiararlo come parametro dell'azione.

Mapping dei parametri in output

Si tratta di creare due entità XTEND a partire dai dati ottenuti da X3:

AXTDFRMHEAD per memorizzare i campi delle videate elenco
AXTDFRMPARAM (Multi) per memorizzare i campi del blocco riquadro che contiene i parametri

Le entità di tipo Azione sono salvate in memoria durante tutta la durata della sessione utente.

Sono ricreate automaticamente ad ogni chiamata dell'azione.

Azione di cancellazione delle entità

Per gestire la visualizzazione mediante un 'blocco condizionale' è necessario cancellare le entità la prima volta che si visualizza la pagina (quando si clicca sul token link dinamico ADLKCONTACT nel menù di di sinistra).

Per fare ciò si crea l'azione AXTDFRMRESET che cancella le entità AXTDFRMHEAD e AXTDFRMPARAM.

Tale azione è associata al token ADLKCONTACT.

Tipo
Standard

Interfaccia
Nessuna

Fase 4 - Creazione di un link dimanico

Il link dinamico ADLKXTDFRMCREATE è il token che sarà inserito nel bottone di creazione del formulario.

Permette di definire la pagina di destinazione (Pagina corrente), di associare l'azione AXTDFRMCREATE e di valorizzare i parametri.

Parametri generali

Avanzamento dell'attività
Si: affinchè ogni clic sul link venga registrato nel file di log

Forza modo http post
No: Poiché un'azione con i parametri è associata al link dinamico, la richiesta verrà inviata automaticamente in modalità POST

Pagina corrente
Si: Il risultato (messaggio o formulario creato) è visualizzato nella pagina corrente

Azione
Codice dell'azione da attivare

Controlla campi web
Si: Per controllare i parametri Web (vedere sezione 'Azione')

Parametri dell'azione

Si tratta di dichiarare tutti i parametri dell'azione ed indicare la maniera in cui si vuole valorizzarli.

Campo TYP
Costante: Il tipo di formulario è sempre di tipo contratto (CON)

Campi TTL, MAICOD
'Campo Web Obbl': Inserimento obbligatorio tramite un campo web.

Campi CMT, PARCOD, PARVAL
'Campo web': Inserimento mediante un campo web non obbligatorio

Cost/Attrib. web
Contiene il nome del tag input (attribut name)

Il controllo dell'inserimento è attivo solo se l'opzione 'Generalità/Controlla campi web' è contrassegnata.

La richiesta sarà indirizzata verso il server XTEND solo se:

l'utente ha valorizzato tutti i campi obbligatori
i dati inseriti sono corretti per i campi di tipo data e numerico.

Il controllo è effettuato mediante la libreria JavaScript di XTEND.

Token di visualizzazione della pagina

Il token ADLKCONTACT permette di visualizzare la pagina di creazione del formulario a partire dal menù di sinistra.

Per gestire la visualizzazione mediante il 'blocco condizionale' ACNDXTDFRMHIDE, è necessario cancellare le entità formulario alla prima visualizzazione.

Questa operazione è effettuata associando l'azione AXTDFRMRESET al token ADLKCONTACT.

Questo token permette così di visualizzare la pagina in modo protetto (https) per indicare all'utente che i dati saranno criptati.

Avanzamento dell'attività
Si

Forza modalità post
Si: Per mantenere il contesto di XTEND salvato nella pagina corrente.
Il modo HTTP GET è usato solo sui link di tipo 'anchor' che devono essere compatibili coi motori di ricerca (web crawlers).

Pagina corrente
No/AXTDFRMCREATE : Pagina di destinazione

Azione
AXTDFRMRESET: Per cancellare le entità formulario

Fase 5 - Creazione dei token blocco

I token blocchi ABLKFRMHEAD e ABLKFRMPARAM sono usati per visualizzare le entità AXTDFRMHEAD e AXTDFRMPARAM che rappresentano i dati di un formulario XTEND.

Blocco di testata

Tipo
Mono record: Legge l'entità AXTDFRMHEAD e posiziona il dato in cima (top) alla sequenza del contesto di dati poi esegue i token figli

Nessun dato
Non visualizzare nulla: Se l'entità AXTDFRMHEAD non esiste, il blocco ed i token 'figli' sono ignorati

Entità
AXTDFRMHEAD : Codice dell'entità da visualizzare

Blocco parametri

Tipo
Multi record: Effettua una iterazione su tutte le entità AXTDFRMPARAM e posiziona ogni entità in cima (top) alla sequenza del contesto di dati poi esegue i token figli

Nessun dato
Non visualizzare nulla: Se l'entità AXTDFRMPARAM non esiste, il blocco ed i token 'figli' sono ignorati

Entità
AXTDFRMPARAM : Codice dell'entità da visualizzare

Riga per blocco
10: Visualizza 10 entità AXTDFRMPARAM al massimo nella pagina

Cella per riga
1: Visualizza una entità AXTDFRMPARAM per riga

Stile per riga
Nessuno: Stili da definire nel file 'my.css' per alternare il colore dello sfondo delle righe

Non è possibile definire i criteri di selezione sui blocchi che selezionano entità salvate in memoria del server XTEND, cioè di tipo sessione o Azione. Il blocco seleziona automaticamente tutte le entità.

I criteri di selezione si applicano solo alle entità di tipo 'Accesso dati'.

Fase 6 - Creazione del token blocco condizionale

Si tratta di illustrare il caso di utilizzo dei blocchi condizionali.

Il token ACNDXTDFRMHIDE è utilizzato per modificare il contenuto della pagina in funzione della presenza o meno di un formulario.

Se l'entità AXTDFRMHEAD esiste (blocco ABLKFRMHEAD non vuoto) significa che è stato creato un formulario e che bisogna visualizzarlo
Se l'entità AXTDFRMHEAD non esiste (blocco ABLKFRMHEAD vuoto) significa che bisogna visualizzare i campi di inserimento

Visualizzazione
Non contrassegnato: Indica che il contenuto del token (html e token figli) è nascosto se si verifica la condizione.

Tipo di criterio
Blocco vuoto: Indica che la condizione di vsualizza/nascondi è basata sul fatto che un blocco contenga o meno dei dati

Blocco
ABLKFRMHEAD: Codice del blocco da testare

Affinché i campi di inserimento siano visualizzati alla prima visualizzazione della pagina, anche se un formulario è stato precedentemente creato, è stata creata un'azione AXTDFRMRESET che cancella le entità formulario.

Questa azione è chiamata mediante il token link dinamico ADLKCONTACT che visualizza la pagina di creazione di un formulario a partire da un clic nel menù di sinistra.

Fase 7 - Creazione della pagina

Creare la pagina web AXTDFRMCREATE.

Pagina di défaut
Associare il file contact.html.
Il file deve essere presente sul server X3 e può essere selezionato mediante il tasto F12.

Protocollo
Https: Per indicare che bisogna criptare i dati della richiesta Http (Vedere configurazione HTTPS)

Blocco principale e blocco di sfondo
Nessuno

Accesso protetto
No: per indicare che questa pagina è in accesso libero (anonimo)

Avanzamento dell'attività
Si: affinché ogni visualizzazione della pagina sia registrata nel file di log

Fase 8 - Validazione del sito

Dopo la modifica dei parametri X3 si consiglia di validare tutto il sito per mezzo della funzione per ricostruire il dizionario del server XTEND mediante la funzione 'Validazione sito Web(AYTFCYGEN)'.

Vericare attentamente che il sito XTEND sia pubblicato, ovvero che il campo 'Pubblica sito' della scheda 'Sito web' sia contrassegnato.

Pagina HTML

Link verso la pagina

Inserimento del token 'link dinamico' ADLKCONTACT nel menù di sinistra per visualizzare la pagina e cancellare l'ultimo formulario creato.

<TD class="button"><A adx="ADLKCONTACT">Contattaci</A></TD>

Gestione della visualizzazione

Il token 'blocco condizionale' ACNDXTDFRMHIDE permette di visualizzare l'inserimento del form se non è stato trovato nessun formulario XTEND, altrimenti visualizza il contenuto del formulario.

<!adx="ACNDXTDFRMHIDE">

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


<!adx="ACNDXTDFRMHIDE">

Inserimento della testata

Creazione dei campi <input> con il token adx="NomeCampo".

Se non si specifica nessun attribut name in un tag <input> verrà generato automaticamente con il nome del token adx.
Il parametro xrc(<input adx="TokenName:xrc">) è utilizzato per rivisualizzare l'ultimo valore inserito in caso di errore di inserimento individuato dal server XTEND o dall'applicazione X3.
Permette di evitare la perdita dei dati inseriti.

<H1>Contattaci</H1>
<table>
   <tr>
      <td><b><b>Email:</b></td>
      <td>
          <input type="text" adx="MAICOD:xrc" size="50">
      </td>
   </tr>
   <tr>
      <td><b><b>Oggetto:</b></td>
      <td>
          <input type="text" adx="TTL:xrc" size="50">
      </td>
   </tr>
   <tr>
      <td><b>Messaggio:</b></td>
      <td>
          <textarea adx="CMT:xrc" rows="5" cols="75"></textarea>
      </td>
   </tr>
</table>

Inserimento delle opzioni

Creazione di coppie di campi <input> tipo Chiave/Valore che verranno 'mappati' su 2 colonne di un blocco riquadro o 2 parametri di dimensione N di un sotto-programma.

PARVAL contiene il valore inserito dall'utente
PARCOD contiene il codice che ha un valore fisso e che non è visibile ('hidden')

Il mapping delle coppie PARCOD/PARVAL con i parametri del web service è effettuato seguendo l'ordine di creazione dei campi nella pagina HTML.

<tr>
    <td><b>Società:</b></td>
    <td>
        <input type="Text"   adx="PARVAL:xrc" size="50">
        <input type="hidden" name="PARCOD" value="Società">
    </td>
</tr>
<tr>
    <td><b>Attività:</b></td>
    <td>
        <select adx="PARVAL">
            <option value="">Precisa:</option>
            <option value="Artigiano" >Artigianp</option>
        </select>
        <input type="hidden" name="PARCOD" value="Attività">
    </td>
</tr>
<tr>
    <td><b>CAP:</b></td>
    <td>
        <input type="text"   value="" adx="PARVAL:xrc" size="10">
        <input type="hidden" name="PARCOD" value="CAP">
    </td>
</tr>

Bottone di creazione

Creazione di un input di tipo "button" con l'attributo adx che contiene il codice del link dinamico.

Tutti i bottoni <input type="button"> che contengono dei tokens adx devono essere button.
Il tipo submit non deve essere utilizzato.

Un'azione utente è considerata come validata se la chiamata del web service non ha restituito nessun messaggio di errore.

I messaggi di errore sono postati in 4GL tramite il sotto programma ADDMESSERR (Call ADDMESSERR("Messaggio") From AWEB)

La visualizzazione dei messaggi X3 è effettuata mediante il token AXUSERMSG.

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

Controllo automatico dell'inserimento

Poiché i campi MAICOD e TTL sono stati definiti come campi web obbligatori, il controllo è effettuato automaticamente e non necessita di nessuna aggiunta di codice JavaScript.

I messaggi in caso di errore visualizzati sono AJSWEBFLDMANDAT (campo obbligatorio) e AJSWEBFLDBADVAL (errore di formato).

Controllo supplementare in JavaScript

E' possibile aggiungere dei controlli in JavaScript sui parametri Web aggiungendo una funzione JavaScript di nome xtdWebParamCheckValue nella pagina HTML.

Se la libreria XTEND individua la presenza di questa funzione sarà chiamata insieme nel parametro:

aWebParamOutl'objet che rappresenta il parametro

aWebParamOut .setValue(String) valorizza il parametro
aWebParamOut .getValue() restituisce il valore del parametro

aInputFieldName il codice del parametro
aInputFieldIndex l'indice se il link è posizionato in un blocco
aInputFieldValue il valore del parametro

Questa funzione restituisce true\false per validare\annullare l'inserimento.

Il messaggio AJSWEBFLDBADVAL è visualizzato in caso di errore di inserimento.

Nella pagina di esempio è stata aggiunta una funzione che controlla il formato dell'email.

La funzione xtdWebParamCheck permette di filtrare i campi da controllare.

Funziona seguendo lo stesso principio di xtdWebParamCheckValue.

Visualizzazione della testata

Il blocco ABLKFRMHEAD permette di posizionare il contesto di dati.

I campi sono visualizzati mediante un token adx posizionato in un 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>Oggetto:</b></td>
        <td adx="TTL"></td>
    </tr>
    <tr>
        <td><b>Messaggio:</b></td>
        <td><pre adx="CMT"></pre></td>
    </tr>
<!adx="ABLKFRMHEAD">
</table>

Visualizzazione delle opzioni

Il blocco ABLKFRMPARAM permette di iterare sulle opzioni del formulario e di creare tante righe <tr> quante opzioni.

Per ogni opzione, XTEND posiziona un contesto di dati, il che permette di risolvere il valore dei tokens adx PARCOD e PARVAL posizionati nei tag HTML.

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

JavaScript

L'entry point pageDoMyDlk permette di aggiungere un programma su clic utente e di annullare il processo in corso se è restituito il valore false.

In questo caso si richiede una conferma prima di indirizzare il formulario al server 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('Confermi la creazione del formulario\nConfirm creation');
    return true;
}

L'entry point xtdWebParamCheckValue fa parte del meccanismo di controllo dei valori dei 'campi web' XTEND (parametri web delle azioni XTEND).

Se la funzione xtdWebParamCheckValue è definita nella pagina HTML, sarà chiamata mediante la libreria XTEND per ogni controllo di 'campo web'.

In questo caso si controlla il valore del campo MAICOD (email) mediante la funzione 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;
}