Fonctionnement

Nous présentons la méthode à suivre pour créer un 'formulaire XTEND' en déclenchant une action 'Enregistrer' sur l'objet X3 AYZ à partir d'un clic sur un bouton de la page HTML. Les données du formulaire sont saisies par l'utilisateur dans les champs du formulaire HTML et sont passées en paramètre de l'action.

Si votre site XTEND a été créé à partir d'une copie du site ASAMPLE les fiches de paramétrages sont déjà créées.

Sinon vous pouvez soit les créer soit les copier une à une à partir du site ASAMPLE avec le bouton d'action X3 'Copie'.

Un formulaire XTEND est constitué :

  • d'une entête (bloc liste) :
      • Le sujet(TTL)
      • Le email de l'utilisateur (MAICOD))
      • Le message(CMT))
      • le Type (TYP)
  • de paramètres (bloc tableau) utilisés pour gérer les options :
      • Le libellé (PARCOD)
      • La valeur (PARVAL)

Les données calculées à la création sont le code (FRMCOD), le statut (STATUT) et la date de création (CREDAT).

Dans notre exemple nous allons créer un formulaire de demande de contact (TYP=CON) avec les options suivantes concernant la personne :

  • Société
  • Activité
  • Code postal
Création
  • Création d'une page HTML (AXTDFRMCREATE) avec un formulaire de saisie.
    Pour l'exemple les données du formulaire seront transmises en mode crypté (HTTPS)
  • Création d'une interface (AXTDFRM) pour l'appel du web service
  • Création d'une action Web de type création d'objet X3 (AXTDFRMCREATE) ayant pour paramètres en entrée le Titre, le email, le commentaire et la liste des options sélectionnées.
    Ces paramètres seront 'mappés' sur les paramètres en entrée du web service.
  • Création d'un token lien dynamique (ADLKCONTACTNEW) qui sera inséré dans la page HTML (bouton 'Créer') pour valoriser les paramètres avec la valeur des champs du formulaire HTML et déclencher l'action.
Affichage

Après l'action de création, le formulaire sera affiché en mode non saisissable dans la page courante pour que l'utilisateur puisse vérifier le contenu.

Cette opération consiste lire les données renvoyées par le web service (entête et paramètres) et à les afficher à l'écran.

La lecture se fait par 'mapping' des paramètres en sortie du web service vers deux entités XTEND (XTDFRMHEAD et XTDFRMPARAM) pour créer les données en mémoire et en insérant 2 tokens blocs (ABLKFRMHEAD et ABLKFRMPARAM) dans la page HTML pour afficher les données.

La gestion de l'affichage (formulaire de saisie ou formulaire créé non saisissable) dans la même page est assurée par un token 'bloc conditionnel' (ACNDXTDFRMHIDE).

Consultation

Les formulaire créés peuvent être consultés via la fonction X3 Formulaire(GESAYZ)

Paramétrage X3

Ce paragraphe vient en complément de la procédure de création d'une action utilisateur.

Etape 1 - Création de l'interface

1. Créer l'interface 'Action utilisateur objet' AXTDFORM basée sur le nom de publication de l'objet AYZ (AXTDAYZ)

2. générer l'accès.

3. Générer tous les champs de l'interface
    Voir le menu 'Outils/Création token champ'

Etape 2 - Création des entités

Créer les entités:

  • AXTDFRMHEAD avec les champs de l'entête
  • XTDFRMPARAM avec les champs des options PARCOD et PARVAL

Voir le menu Outils\Aide au remplissage.

Ces entités seront ensuite utilisées dans le mapping retour de l'action de création du formulaire.

Dans l'exemple nous avons défini 2 clés pour AYZ:

  • FRMCOD qui correspond à l'identifiant du formulaire
  • FCYCOD qui est le code du site XTEND et qui est égal au code du site courant.


FCYCOD filtre les formulaires en fonction du site courant ASAMPLE.

Il faut supprimer cette clé si on souhaite lire tous les formulaires de la base

Etape 3 - Création de l'action web

Déclaration des paramètres

Créer une action AXTDFRMCREATE de type 'standard' avec pour paramètres le type, le titre, le email, le commentaire et les options.

Seuls les paramètres du web services qui dépendent du contexte d'appel de l'action sont déclarés comme paramètres de l'action en saisie.

C'est le token lien dynamique qui indique comment il seront valorisés en fonction du contexte d'appel (champ web, champ XTEND...).

Suppression en début'
    coché pour supprimer les entités AXTDFRMHEAD et AXTDFRMPARAM au début de l'action (avant le résultat de l'appel du sous-programme) afin de gérer correctement l'affichage du résultat dans la même page HTML à l'aide d'un token 'bloc conditionnel' basé sur la présence du champ FRMCOD.

Suivi de l'activité
    Oui : pour que chaque appel de l'action soit enregistré dans le fichier de log

Actif sur reload
    Non : pour ne pas récréer un formulaires si l'utilisateur appuie sur F5 après avoir créé un formulaire;

Activation bouton
    Créer : pour déclencher le bouton d'action Enregistrer de l'objet AYZ

Mapping des paramètres en entrée

Il s'agit de faire correspondre les champs XTEND avec les paramètres d'appel du web service.

Dans notre cas nous devons faire uniquement un mapping des paramètres de l'action TYP, TTL, CMT,MAIDCOD, PARCOD et PARVAL.

Le mapping de PARCOD et PARVAL est de type Multi ce qui permet au serveur XTEND de 'mapper' plusieurs champs HTML de même nom sur un paramètre multi-dimensionné.

Pour 'mapper' les paramètres de l'action on ne renseigne pas le code de l'entité.

Les paramètres du web services dont la valeur provient toujours du même contexte peuvent être valorisés directement dans le mapping de l'action en précisant l'entité.

Par exemple si on devais passer le code utilisateur de login on pourrait le mapper directement avec le champ AUSERCODE de l'entité ASESSION plutôt que de le déclarer en paramètre de l'action.

Mapping des paramètres en sortie

Il s'agit de créer deux entités XTEND à partir des données renvoyées par X3 :

  • AXTDFRMHEAD pour stocker les champs des écrans liste
  • AXTDFRMPARAM (Multi) pour stocker les champs du bloc tableau qui contient les paramètres

Les entités de type Action sont stockées en mémoire pendant toute la durée de la session utilisateur.

Elles sont recréées automatiquement à chaque appel de l'action.

Action de suppression des entités

Pour gérer l'affichage via un 'bloc conditionnel' on a besoin de supprimer les entités la première fois que la page s'affiche (lorsqu'on clique sur le token lien dynamique ADLKCONTACT dans le menu gauche).

Pour cela on crée une action AXTDFRMRESET qui ne fait que supprimer les entités AXTDFRMHEAD et AXTDFRMPARAM.

Cette action est associée au token ADLKCONTACT.

Type
    Standard

Interface
    Aucune

Etape 4 - Création du lien dynamique

Le lien dynamique ADLKXTDFRMCREATE est le token qui sera inséré dans le bouton de création du formulaire.

Il permet de définir la page de destination (Page courante), d'associer l'action AXTDFRMCREATE et de valoriser les paramètres.

Paramètres généraux

Suivi de l'activité
    Oui : pour que chaque clic sur le lien soit enregistré dans le fichier de log

Forcer le mode http post
    Non : Comme une action avec paramètres est associée au lien dynamique, la requete sera envoyée automatiquement en mode POST

Page courante
    Oui : Le résultat (message ou formulaire créé) est affiché dans la page courante

Action
    Code de l'action à déclencher

Contrôler les champs web
    Oui : Pour contrôler les paramètres Web (voir section 'Action')

Paramètres de l'action

Il s'agit de déclarer tous les paramètres de l'action et d'indiquer la manière dont on souhaite les valoriser.

Champ TYP
    Constante : Le type de formulaire est toujours de type contrat (CON)

Champs TTL, MAICOD
    'Chp Web Oblig' : Saisie obligatoire par un champ web.

Champs CMT, PARCOD, PARVAL
    'Champ web' : Saisie par un champ web non obligatoire

Cste/Attrib. web
    Contient le nom du tag input (attribut name)

Le contrôle de la saisie n'est actif que si l'option 'Généralités/Contrôler champs web' est cochée.

La requête sera postée vers le serveur XTEND seulement si:

  • l'utilisateur a valorisé tous les champs obligatoires
  • les données saisies sont correctes pour les champs de type date et numérique.

Le contrôle est effectué par la bibliothèque JavaScript d'XTEND.

Token d'affichage de la page

Le token ADLKCONTACT permet d'afficher la page de création du formulaire à partir du menu gauche.

Pour gérer l'affichage via le 'bloc conditionnel' ACNDXTDFRMHIDE il est nécessaire d'effacer les entités formulaire au premier affichage.

Cette opération est effectuée en associant l'action AXTDFRMRESET au token ADLKCONTACT.

Ce token permet aussi d'afficher la page en mode sécurisé (https) pour indiquer à l'utilisateur que le données seront cryptées.

Suivi de l'activité
    Oui

Forcer le mode post
    Oui : Pour conserver le contexte de XTEND sauvegardé dans la page courante.
    Le mode HTTP GET est utilisé uniquement sur les liens de type 'ancre' qui doivent être compatibles avec les moteurs de recherches (web crawlers).

Page courante
    Non/AXTDFRMCREATE : Page de destination

Action
    AXTDFRMRESET : Pour effacer les entités formulaire

Etape 5 - Création des tokens bloc

Les tokens blocs ABLKFRMHEAD et ABLKFRMPARAM sont utilisés pour afficher les entités AXTDFRMHEAD et AXTDFRMPARAM qui représentent les données d'un formulaire XTEND.

Bloc d'entête

Type
    Mono enregistrement : Lit l'entité AXTDFRMHEAD et place la donnée au sommet (top) de la pile du contexte de données puis exécute les tokens fils

Aucune donnée
    Ne rien afficher : Si l'entité AXTDFRMHEAD n'existe pas le bloc et les tokens 'fils' sont ignorés

Entité
    AXTDFRMHEAD : Code de l'entité à afficher

Bloc paramètres

Type
    Multi enregistrements : Effectue une itération sur toutes les entités AXTDFRMPARAM et positionne chaque entité au sommet (top) de la pile du contexte de données puis exécute les tokens fils

Aucune donnée
    Ne rien afficher : Si l'entité AXTDFRMPARAM n'existe pas le bloc et les tokens 'fils' sont ignorés

Entité
    AXTDFRMPARAM : Code de l'entité à afficher

Ligne par bloc
    10 : Affiche 10 entités AXTDFRMPARAM maximum dans la page

Cellule par ligne
    1 : Affiche une entité AXTDFRMPARAM par ligne

Style par ligne
    Aucun : Styles à définir dans le fichier 'my.css' pour alterner la couleur de fond des lignes

Il n'est pas possible de définir des critères de sélection sur les blocs qui sélectionnent des entités stockées en mémoire du serveur XTEND, c'est à dire de type session ou Action. Le bloc sélectionne automatiquement toutes les entités.

Les critères de sélection s'appliquent uniquement qu'aux entités de type 'Accès données'.

Etape 6 - Création du token bloc conditionnel

Il s'agit d'illustrer le cas d'utilisation des blocs conditionnels.

Le token ACNDXTDFRMHIDE est utilisé pour modifier le contenu de la page en fonction de la présence ou non d'un formulaire.

  • Si l'entité AXTDFRMHEAD existe (bloc ABLKFRMHEAD non vide) c'est qu'un formulaire a été créé et qu'il faut l'afficher
  • Si l'entité AXTDFRMHEAD n'existe pas (bloc ABLKFRMHEAD vide) c'est qu'il faut afficher les champs de saisie

Affichage
    Non coché : Indique que le contenu du token (html et tokens fils) est masqué si la condition est vérifiée.

Type de critère
    Bloc vide : Indique que la condition d'affichage/masquage est basée sur le fait qu'un bloc contienne ou non des données

Bloc
    ABLKFRMHEAD : Code du bloc à tester

Pour que les champs de saisie soient affichés au premier affichage de la page, même si un formulaire a été crée auparavant, nous avons créé une action AXTDFRMRESET qui supprime les entités formulaire.

Cette action est appelée par le token lien dynamique ADLKCONTACT qui affiche la page de création d'un formulaire à partir d'un clic dans le menu gauche.

Etape 7 - Création de la page

Créer la page web AXTDFRMCREATE.

Page par défaut
    Associer le fichier contact.html.
    Le fichier doit être présent sur le serveur X3 et peut être sélectionné par la touche F12.

Protocole
    Https : Pour indiquer qu'il faut crypter les données de la requête Http (Voir configuration HTTPS)

Bloc principal et bloc de fond
    Aucun

Accès protégé
    Non : pour indiquer que cette page est en accès libre (anonyme)

Suivi de l'activité
    Oui : pour que chaque affichage de la page soit enregistré dans le fichier de log

Etape 8 - Validation du site

Après modification des paramètres X3 il est conseillé de valider l'intégralité du site via la fonction afin de reconstruire le dictionnaire du serveur XTEND via la fonction 'Validation site Web(AYTFCYGEN)'.

Bien vérifier que le site XTEND est publié, c'est à dire le champ 'Publié le site' de la fiche 'Site web' est coché.

Page HTML

Lien vers la page

Insertion du token 'lien dynamique' ADLKCONTACT dans le menu gauche pour afficher la page et supprimer le dernier formulaire créé.

    <TD class="button"><A adx="ADLKCONTACT">Contactez-nous</A></TD>

Gestion de l'affichage

Le token 'bloc conditionnel' ACNDXTDFRMHIDE permet d'afficher la saisie du formulaire si aucun formulaire XTEND n'a été trouvé sinon il affiche le contenu du formuaire.

<!adx="ACNDXTDFRMHIDE">
  <!-- Affichage du contenu du formulaire créé si le bloc ABLKFRMHEAD n'est pas vide-->
<!adx="ACNDXTDFRMHIDE">
<!adx="ACNDXTDFRMHIDE:xNot">
  <!-- Affichage de la saisie du formulaire si le bloc ABLKFRMHEAD est vide-->
  <!-- Paramètre xNot:Condition inverse du token 'bloc conditionnel'-->
<!adx="ACNDXTDFRMHIDE">

Saisie de l'entête

Création de champs <input> avec le token adx="NomDuChamp".

Si on ne précise pas d'attribut name dans un tag <input> il sera généré automatiquement avec le nom du token adx.
Le paramètre xrc(<input adx="TokenName:xrc">) est utilisé pour réafficher la dernière valeur saisie en cas d'erreur de saisie détectée par le serveur XTEND ou l'application X3.
Il permet d'éviter de perte des données saisies.

<H1>Nous contacter</H1>
<table>
   <tr>
      <td><b><b>Email:</b></td>
      <td>
          <input type="text" adx="MAICOD:xrc" size="50"> 
      </td>
   </tr>
   <tr> 
      <td><b><b>Sujet:</b></td>
      <td>
          <input type="text" adx="TTL:xrc" size="50"> 
      </td>
   </tr>
   <tr> 
      <td><b>Message:</b></td>
      <td>
          <textarea adx="CMT:xrc" rows="5" cols="75"></textarea>
      </td>
   </tr>
</table>

Saisie des options

Création de couples de champs <input> type Clé/Valeur qui seront 'mappés' sur 2 colonnes d'un bloc tableau ou 2 paramètres de dimension N d'un sous-programme.

  • PARVAL contient la valeur saisie par l'utilisateur
  • PARCOD contient le code qui a une valeur fiwe et qui n'est pas visible ('hidden')

Le mapping des couples PARCOD/PARVAL avec les paramètres du web service est effectué suivant l'ordre de création des champs dans la page HTML.

<tr>
    <td><b>Société:</b></td>
    <td>
        <input type="Text"   adx="PARVAL:xrc"  size="50">
        <input type="hidden" name="PARCOD" value="Société">
    </td>
</tr>
<tr>
    <td><b>Activité:</b></td>
    <td>
        <select adx="PARVAL">
            <option value="">Pr&eacute;ciser :</option>
            <option value="Artisans" >Artisans</option>
        </select>
        <input type="hidden"  name="PARCOD"  value="Activité"> 
    </td>
</tr>
<tr>
    <td><b>Code postal:</b></td>
    <td>
        <input type="text"   value="" adx="PARVAL:xrc" size="10">
        <input type="hidden"  name="PARCOD"  value="Code Postal"> 
    </td>
</tr>

Bouton de création

Création d'un input de type "button" avec l'attribut adx qui contient le code du lien dynamique.

Tous les boutons <input type="button"> qui contiennent des tokens adx doivent être de button.
Le type submit ne doit pas être utilisé.

<tr>
    <td>
        <input type="button"  class="button" adx="ADLKXTDFRMCREATE" value="Créer">
    </td>
</tr>

Une action utilisateur est considérée comme validée si l'appel du web service n'a renvoyé aucun message d'erreur.

Les messages d'erreur sont postés en L4G via le sous programme ADDMESSERR (Call ADDMESSERR("Message") From AWEB)

L'affichage des messages X3 est effectué via le token AXUSERMSG.

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

Contrôle automatique de la saisie

Comme les champs MAICOD et TTL on été définis comme champs web obligatoires, le contrôle est effectué automatiquement et ne nécessite aucun ajout de code JavaScript.

Les messages en cas d'erreur affichés sont AJSWEBFLDMANDAT (champs obligatoire) et AJSWEBFLDBADVAL (erreur de format).

Contrôle supplémentaires en JavaScript

Il est possible d'ajouter des contrôles en JavaScript sur les paramètres Web en ajoutant une fonction JavaScript de nom xtdWebParamCheckValue dans la page HTML.

Si la librairie XTEND détecte la présence de cette fonction elle sera appelée avec en paramètre:

  • aWebParamOutl'objet qui représente le paramètre
      • aWebParamOut .setValue(String) valorise le paramètre
      • aWebParamOut .getValue() renvoie la valeur du paramètre
  • aInputFieldName le code du paramètre
  • aInputFieldIndex l'index si le lien est placé dans un bloc
  • aInputFieldValue la valeur du paramètre

Cette fonction renvoie true\false pour valider\invalider la saisie.

Le message AJSWEBFLDBADVAL est affiché en cas d'erreur de saisie.

Dans la page d'exemple nous avons ajouté une fonction qui contrôle le format de email.

<script type="application/x-javascript">
// 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;
}
</script>

La fonction xtdWebParamCheck permet de filtrer les champs à controler.

Elle fonctionne suivant le même principe que xtdWebParamCheckValue.

var gNbChecked=0;
// Renvoie true si le paramètre web aInputFieldName/aInputFieldIndex doit être contrôlé
function xtdWebParamCheck(aWebParamsOut,aInputFieldName,aInputFieldIndex){
/*
    Exemple pour une liste de picking avec checkboxes (ASELECTED) pour sélectionner les lignes.
    On ne contrôle pas le champ AQUANTITY si la ligne n'est pas sélectionnée'
*/
    if (aInputFieldName=="AQUANTITY"){
        // gNbChecked est un compteur des lignes sélectionnées
        if (aInputFieldIndex==0) gNbChecked=0;
        // Ligne sélectionnée si la valeur de ASELECTED est égale à 1
        if (aWebParamsOut.getParamValue("ASELECTED",aInputFieldIndex)=="1"){
            gNbChecked++;
            return true;
        }
        return false;
    }
    return true;
}

Affichage de l'entête

Le bloc ABLKFRMHEAD permet de positionner le contexte de donnée.

Les champs sont affiché via un token adx placé dans 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>Sujet:</b></td>
        <td adx="TTL"></td>
    </tr>
    <tr> 
        <td><b>Message:</b></td>
        <td><pre adx="CMT"></pre></td>
    </tr>
<!adx="ABLKFRMHEAD">
</table>

Affichage des options

Le bloc ABLKFRMPARAM permet d'itérer sur les options du formulaire et de créer autant de ligne <tr> que d'options.

Pour chaque option, XTEND positionne un contexte de donnée ce qui permet de résoudre la valeur des tokens adx PARCOD et PARVAL placés dans les tags HTML.

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

Le JavaScript

Le point d'entrée pageDoMyDlk permet d'ajouter un traitement sur clic utilisateur et d'annuler le processus en cours si la valeur false et renvoyée.

Dans notre cas on demande une confirmation avant de poster le formulaire vers le serveur 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('Confirmer la création du formulaire\nConfirm creation');
    return true;
}              

Le point d'entrée xtdWebParamCheckValue fait partie du mécanisme de contrôle des valeurs des 'champs web' XTEND (paramètres web des actions XTEND).

Si la fonction xtdWebParamCheckValue est définie dans la page HTML, elle sera appelée par la librairie XTEND pour chaque contrôle de 'champ web'.

Dans notre cas on contrôle la valeur du champ MAICOD (email) via la fonction 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;
}