4D Ajax Framework : travailler avec les vues DCS

4D Ajax Framework : travailler avec les vues DCS
Par Thomas FITCH, Technical Services Team Member, 4D Inc.
Note technique 4D-200704-11-FR
Version 1 - Date 1 avril 2007
Résumé
Note traduite de l'anglais par Stéphanie Tirtiat (4D S.A.S., Support Technique International)
Cette note technique couvre la création des DCS (Developer Created Selections - sélections créées par les
développeurs) et leur utilisation dans l'implémentation de vues avec le 4D Ajax Framework (4DAF) Client.
4D Notes techniques
Copyright © 1985-2009 4D SAS - Tous droits réservés
Tous les efforts ont été faits pour que le contenu de cette note technique présente le maximum de fiabilité possible.
Néanmoins, les différents éléments composant cette note technique, et le cas échéant, le code, sont fournis sans garantie d'aucune sorte.
L'auteur et 4D S.A. déclinent donc toute responsabilité quant à l'utilisation qui pourrait être faite de ces éléments, tant à l'égard de leurs
utilisateurs que des tiers.
Les informations contenues dans ce document peuvent faire l'objet de modifications sans préavis et ne sauraient en aucune manière engager 4D
SA. La fourniture du logiciel décrit dans ce document est régie par un octroi de licence dont les termes sont précisés par ailleurs dans la licence
électronique figurant sur le support du Logiciel et de la Documentation afférente. Le logiciel et sa documentation ne peuvent être utilisés, copiés
ou reproduits sur quelque support que ce soit et de quelque manière que ce soit, que conformément aux termes de cette licence.
Aucune partie de ce document ne peut être reproduite ou recopiée de quelque manière que ce soit, électronique ou mécanique, y compris par
photocopie, enregistrement, archivage ou tout autre procédé de stockage, de traitement et de récupération d'informations, pour d'autres buts que
l'usage personnel de l'acheteur, et ce exclusivement aux conditions contractuelles, sans la permission explicite de 4D SA.
4D, 4D Calc, 4D Draw, 4D Write, 4D Insider, 4ème Dimension ®, 4D Server, 4D Compiler ainsi que les logos 4e Dimension, sont des marques
enregistrées de 4D SA.
Windows,Windows NT,Win 32s et Microsoft sont des marques enregistrées de Microsoft Corporation.
Apple, Macintosh, Power Macintosh, LaserWriter, ImageWriter, QuickTime sont des marques enregistrées ou des noms commerciaux de Apple
Computer,Inc.
Mac2Win Software Copyright © 1990-2002 est un produit de Altura Software,Inc.
4D Write contient des éléments de "MacLink Plus file translation", un produit de DataViz, Inc,55 Corporate drive,Trumbull,CT,USA.
XTND Copyright 1992-2002 © 4D SA. Tous droits réservés.
XTND Technology Copyright 1989-2002 © Claris Corporation.. Tous droits réservés ACROBAT © Copyright 1987-2002, Secret Commercial
Adobe Systems Inc.Tous droits réservés. ACROBAT est une marque enregistrée d'Adobe Systems Inc.
Tous les autres noms de produits ou appellations sont des marques déposées ou des noms commerciaux appartenant à leurs propriétaires
respectifs.
1/9
4D Ajax Framework : travailler avec les vues DCS
Résumé
Cette note technique couvre la création des DCS (Developer Created Selections - sélections créées par les
développeurs) et leur utilisation dans l'implémentation de vues avec le 4D Ajax Framework (4DAF) Client.
Les informations dans cette note technique sont compatibles avec le 4D Web 2.0 Pack version 1.1. Une base
exemple est fournie. Veuillez noter que vous devez avoir une licence pour le 4D Web 2.0 Pack pour utiliser
la base exemple.
A propos des vues DCS
Les vues DCS sont des vues qui sont créées par programmation dans 4D et qui sont affichées par le 4D Ajax
Framework. Les vues DCS apparaissent dans le portail du 4D Ajax Framework Client, dans le panneau de
contrôle, de même que les vues régulières. Bien que les vues DCS soient affichées et interagissent avec les
autres vues, elles sont alimentées par les données stockées dans des tableaux qui sont eux-mêmes remplis par
une source de données choisie par le développeur. Du fait que les tableaux sont très souvent sollicités, il est
recommandé d'utiliser les vues DCS dans des applications compilées pour de meilleures performances.
Utilisation de la base exemple
Pour utiliser la base exemple fournie avec cette note technique, vous devez avoir installé le composant 4D
Ajax Framework avec 4D Insider. Le composant n'est pas pré-installé dans la base exemple.
Vous trouverez les instructions d'installation pour le composant 4D Ajax Framework sur le site web de 4D.
Le document en questions s'intitule "4D Ajax Framework - Guide d'installation" et peut être téléchargé à
cette URL :
http://www.4d.fr/support/docs/4thdimensionmanuals.html#w20p
Note :
Les préférences Web de la base exemple ont déjà été configurées. Vous n'avez donc plus besoin de les
modifier suivant ce qui est écrit dans les instructions d'installation.
Après avoir suivi la procédure d'installation, il y a quatre étapes de plus qui doivent être adaptées à cette note
technique. Chacun des quatre points d'entrée doit être édités pour y ajouter les appels aux méthodes projets
qui sont présentes dans la base exemple. Pour procéder à cette manipulation nécessaire, éditez les points
d'entrée développeur listés ci-dessous :
DAX_DevHook_DCS_ViewAdd
Sélectionnez tout (CTRL + a sur PC, COMMAND + a sur Mac) et supprimez le code et les commentaires
dans cette méthode. Insérez ensuite le code suivant :
2/9
A_DCS_ViewAdd()
DAX_DevHook_DCS_SetSelection
Sélectionnez tout (CTRL + a sur PC, COMMAND + a sur Mac) et supprimez le code et les commentaires
dans cette méthode. Insérez ensuite le code suivant :
C_TEXTE($1;$viewName_t)
$viewName_t:=$1
A_DCS_SetSelection ($viewName_t)
DAX_DevHook_DCS_RecordSave
Sélectionnez tout (CTRL + a sur PC, COMMAND + a sur Mac) et supprimez le code et les commentaires
dans cette méthode. Insérez ensuite le code suivant :
C_TEXTE($1;$view)
C_ENTIER LONG($2;$0;$record)
C_POINTEUR ($3;$4;$fieldName;$fieldValue)
$view:=$1
$record:=$2
$fieldName:=$3
$fieldValue:=$4
$record:=A_DCS_RecordSave ($view;$record;$fieldName;$fieldValue)
$0:=$record
DAX_DevHook_DCS_RecordDelete
Sélectionnez tout (CTRL + a sur PC, COMMAND + a sur Mac) et supprimez le code et les commentaires
dans cette méthode. Insérez ensuite le code suivant :
C_TEXTE($1;$viewName_t)
C_ENTIER LONG($2;$recordID_l)
C_BOOLEEN ($0;$deleteRecordAccepted_b)
$viewName_t:=$1
$recordID_l:=$2
$deleteRecordAccepted_b:=A_DCS_RecordDelete ($viewName_t;$recordID_l)
$0:=$deleteRecordAccepted_b
3/9
Après avoir effectué tout ceci, relancez la base de données.
Pour accéder au client 4D Ajax Framework depuis cette base exemple, sélectionnez "Tester le serveur Web"
du menu Exécuter dans le mode Structure ou ouvrez un navigateur Web compatible et entrez le chemin
suivant :
http://localhost:8080/
Implémentation des vues DCS
Il y a quatre méthodes d'entrée dans le 4D Ajax Framework pour permettre au développeur d'implémenter
ses vues DCS :
• DAX_DevHook_DCS_ViewAdd
• DAX_DevHook_DCS_SetSelection
• DAX_DevHook_DCS_RecordSave
• DAX_DevHook_DCS_RecordDelete
Toutes ces méthodes d'entrée doivent être implémentés dès lors que l'on utilise des vues DCS dans une
application.
Présentation des méthodes d'entrée
DAX_DevHook_DCS_ViewAdd
Cette méthode est utilisée pour créer la vue en front-end. Elle est appelée par DAX_Dev_Initialize. Toutes
les vues DCS sont créées à ce moment, même si les sélections ne contiennent pas encore de données à ce
stade.
DAX_DevHook_DCS_SetSelection
Cette méthode est exécutée pour chaque vue DCS à laquelle on accède. Le nom de la vue qui a été défini
dans la méthode DAX_DevHook_DCS_ViewAdd est passé en paramètre ici. A ce stade, la vue DCS est
alimentée par les données de la base. Les tableaux doivent d'abord être créés puis remplis avec les données
qui seront affichées dans cette vue.
Cette méthode est aussi utilisée pour rafraîchir les données dans une vue.
DAX_DevHook_DCS_RecordSave
Cette méthode est appelée chaque fois qu'un enregistrement est créé ou modifié dans une vue DCS. Elle est
utilisée pour sauvegarder les données. Un message d'erreur est retourné si les données ne peuvent pas être
stockées.
DAX_DevHook_DCS_RecordDelete
4/9
Cette méthode est appelée chaque fois qu'un enregistrement est supprimé dans une vue DCS. Elle est utilisée
pour supprimer l'enregistrement. Un message d'erreur s'affiche si l'enregistrement ne peut pas être supprimé.
Les méthodes projet de la base exemple
Ce chapitre décrit les quatre méthodes projets présentes dans la base exemple, qui sont appelées par les
méthodes d'entrées dans le but d'implémenter les vues DCS.
A_DCS_ViewAdd
Cette méthode de la base exemple est appelée par la méthode d'entrée DAX_DevHook_DCS_ViewAdd et
crée des vues DCS. Si seule cette méthode était implémentée avec accès au front-end 4D Ajax Framework,
toutes les vues DCS seraient créées pour la base de données, mais ne contiendraient aucune données, comme
le montre la copie d'écran suivant :
Aucun paramètre n'est passé dans cette méthode et il n'y a pas de valeur retournée. Pour créer des vues DCS,
il faut appeler la méthode DAX_Dev_DCS_AddCustomView pour chaque vue qui doit être ajoutée.
DAX_Dev_DCS_AddCustomView requiert sept paramètres. Voici un exemple d'appel de cette méthode :
DAX_Dev_DCS_AddCustomView(view;title;type;unique;mandatory;enter;modify)
Les paramètres sont les suivants :
- view : le nom de la vue à ajouter (texte). C'est le nom qui sera affiché aux utilisateurs sur la page Web. On
peut dire que c'est, par essence, un nom de table.
- title: c'est un pointeur vers un tableau texte qui contient le nom des colonnes de la vue. Par exemple :
"Name", "Address", "Phone Number", etc... C'est, par essence, un tableau de noms de champs.
5/9
- type: c'est un pointeur vers un tableau entier long qui contient les types de données des colonnes de la vue.
Les constantes standards 4D peuvent être utilisées pour les types, par exemple : Est un texte, Est un entier
long, etc...
- unique : pointeur vers un tableau booléen pour définir l'attribut unique de chaque colonne.
- mandatory: pointeur vers un tableau booléen pour définir l'attribut obligatoire pour chaque colonne.
- enter : pointeur vers un tableau booléen pour définir l'attribut non saisissable pour chaque colonne.
- modify : pointeur vers un tableau booléen pour définir l'attribut non modifiable pour chaque colonne.
La méthode projet A_DCS_ViewAdd crée les tableaux pour chaque vue DCS et appelle ensuite la méthode
DAX_Dev_DCS_AddCustomView pour ajouter chacune des vues.
A_DCS_SetSelection
Cette méthode est appelée par la méthode DAX_DevHook_DCS_SetSelection présente dans la base
exemple. Elle est appelée quand une vue DCS est ouverte en premier et elle remplit la vue avec les données
de la base. Quand le 4D Ajax Framework effectue cet appel, le nom de la vue (comme défini dans la
méthode DAX_DevHook_DCS_ViewAdd) est passé en paramètre. Le développeur doit décider ensuite ce
qui alimentera la vue.
Dans cette méthode, quand on se réfère à un "enregistrement", cela inclut tout ensemble unique de données
et pas forcément un enregistrement d'une table 4D. Un enregistrement veut provenir de toute source de
données du moment qu'il peut être identifié de manière unique. Les vues DCS n'ont pas besoin d'être créées à
partir de données stockées dans les tables de la base de données. Elles peuvent être créées à partir de toute
donnée à laquelle la base peut avoir accès. Ci-dessous une copie d'écran d'une vue DCS alimentée :
6/9
La vue DCS est alimentée en effectuant un appel à la méthode DAX_Dev_DCS_SetSelection. Les
paramètres passés dans cette méthode doivent être N pointeurs vers des tableaux. N, le nombre de pointeurs,
est égal au nombre de colonnes définies pour cette vue quand elle a été créée par
DAX_DevHook_DCS_ViewAdd, plus un :
Le premier paramètre est un pointeur vers un tableau entier long contenant les ID des enregistrements. Ces
ID peuvent être les numéros des enregistrements d'une table, les valeurs d'un champ identifiant ou d'un
champ clé créé avec Numéro de séquence ou une fonction similaire ; ou tout autre technique qui crée un
identifiant de type entier long.
Quelque soit la technique de création d'identifiants d'enregistrements, chaque ID doit être une valeur qui peut
trouver et charger un enregistrement précis, quelle que soit la sélection courante. L'utilisation des numéros
d'éléments d'un tableau comme identifiants d'enregistrements n'est pas recommandé.
La suite des paramètres N passés dans DAX_Dev_DCS_SetSelection sont des pointeurs vers les tableaux
utilisés pour stocker les données. Ces tableaux doivent être passés dans le même ordre que le nom des
colonnes qui ont été définies dans la méthode DAX_DevHook_DCS_ViewAdd. En d'autres termes, si le
premier élément dans les noms de colonne était "First Name", le premier tableau de données devrait être
celui qui contient les prénoms, et ainsi de suite.
Le type des tableaux doit être compatible avec les types définis pour les colonnes dans la méthode
DAX_DevHook_DCS_ViewAdd, c'est à dire que l'assignement direct entre des valeurs doit être possible. Si
le champ a été préalablement défini comme Réel, un tableau de type texte ne pourra pas être passé, mais un
tableau de type entier long le pourra. De la même manière, si un champ est défini texte ou chaîne, un tableau
de type Texte ou Chaine peut être passé indifféremment (tant que la chaîne est assez longue pour contenir les
valeurs).
Dans la base exemple, tous les tableaux sont créés et alimentés dans la méthode A_DCS_SetSelection, mais
il peut y avoir des tableaux pré-existants ou créés par n'importe quelle méthode appelée par
DAX_DevHook_DCS_SetSelection.
A_DCS_RecordSave
Dans la base exemple, cette méthode est appelée par DAX_DevHook_DCS_RecordSave. Quatre paramètres
doivent être passés et elle retourne l'identifiant d'enregistrement (ID) dans un Entier Long.
Les paramètres à passer sont les suivants :
- $1 (texte) : le nom de la vue DCS où l'enregistrement est sauvegardé, comme défini auparavant dans la
méthode DAX_DevHook_DCS_ViewAdd.
- $2 (entier long) : ID pour l'enregistrement qui est sauvegardé (ou la constante Est un nouvel enregistrement
pour les nouveaux enregistrements).
- $3 (pointeur) : un pointeur vers une variable texte contenant les noms des champs pour l'enregistrement qui
doit être sauvegardé, comme défini auparavant dans la méthode DAX_DevHook_DCS_ViewAdd. Seuls les
noms de champs dont le contenu a été modifié sont inclus.
7/9
- $4 (pointeur) : un pointeur vers un tableau texte contenant les valeurs des champs de l'enregistrement qui
est sauvegardé ; en d'autres termes, les données qui ont été saisies par l'utilisateur. Seules les valeurs dans les
champs qui ont été modifiés sont incluses.
Cette méthode analyse les tableaux entrant pour y trouver quels sont les champs qui ont été modifiés. Un flag
pour chaque champ est utilisé à renseigner, plus tard, dans la méthode, s'il existe des données pour ce champ
ou non. Une fois qu'il y a des flags indiquant quelles sont les données saisies, une décision peut être prise
pour la suite des opérations.
D'abord, la méthode permet de décider s'il y a besoin d'agir sur la table [Actors]. Dans cette méthode, pour
cette table, il est défini que les enregistrements peuvent être créés et sauvegardés sans tenir compte du fait
que le champ Sex est renseigné ou non. Il est à noté que l'utilisateur n'est pas autorisé à modifier le champ
Sex d'un acteur existant ; ce champ ne peut être assigné qu'à la création de nouveaux acteurs. De plus, toute
modification du champ First Name ou Last Name présente le dialogue de création et charge le nouvel
enregistrement de la table [Actors].
Tout ceci est effectué avant la vérification du type de manipulation d'un enregistrement dans la vue (création
d'un nouvel enregistrement ou édition d'un enregistrement existant). Maintenant, les différents cas doivent
être traités selon le type de modification apportée à un enregistrement. Soit l'enregistrement existe déjà et est
édité, soit c'est un nouvel enregistrement qui est créé. La variable $recordNumber_I contient cette
information et la méthode procède à un test pour savoir si elle doit créer le nouvel enregistrement pour la
table [M_LineItem] ou si elle doit accéder à l'enregistrement édité.
A ce stade, la méthode crée et charge l'enregistrement de la table [M_LineItem] pour que les données y
soient stockées. Une fois les données sauvegardées, le numéro d'enregistrement est stocké et retourné dans la
variable $recordNumber_I. Si la constante Aucun enregistrement courant est retournée au lieu d'un numéro
d'enregistrement valide, le client 4D Ajax Framework affiche alors le message d'erreur suivant :
A_DCS_RecordDelete
Dans la base exemple, cette méthode est appelée par DAX_DevHook_DCS_RecordDelete. Deux paramètres
doivent être passés et une valeur booléenne est retournée. La valeur reçue est Vrai si l'enregistrement a été
correctement supprimé, et retourne Faux si ce n'est pas le cas.
Les paramètres à passer dans cette méthode sont les suivants :
8/9
- $1 (texte) : le nom de la vue DCS qui doit contenir l'enregistrement à supprimer, comme défini dans la
méthode DAX_DevHook_DCS_ViewAdd.
- $2 (entier long) : l'identifiant de l'enregistrement (ID) qui doit être supprimé, comme défini dans la méthode
DAX_DevHook_DCS_SetSelection.
Dans la base exemple, les ID d'enregistrements sont les mêmes que les numéros d'enregistrements assignés
par 4D. Il est donc possible d'utiliser simplement la commande ALLER A ENREGISTREMENT() pour
trouver et supprimer de la base de données l'enregistrement concerné.
La valeur de retour, Vrai ou Faux, affecte le message d'erreur ou de confirmation retourné par 4D Ajax
Framework. Si la valeur retournée est Vrai, la vue DCS est rafraîchie en appelant la méthode
DAX_DevHook_DCS_SetSelection. L'enregistrement supprimé n'apparaît plus. Si c'est la valeur Faux qui
est retournée, l'utilisateur reçoit un message d'erreur affiché de cette façon :
Conclusion
Cette note technique vous a décrit une implémentation basique des vues DCS avec 4D Ajax Framework. Ces
vues sont créées par du code 4D, et non par le panneau de contrôle, mais elles peuvent être utilisées de la
même manière que les vues DCS créées par ce panneau de contrôle. L'avantage des vues DCS est qu'elles
peuvent contenir des données de n'importe quelle source, comme une table 4D ou une combinaison de
sources. Le développeur est libre de choisir ce qu'il veut afficher dans ses vues et alimenter ensuite les
tableaux qui construisent ces vues DCS.
9/9