Les macros 4D évoluent avec la 2004

Jonathan LE

Les macros sont des outils très utiles pour utiliser et réutiliser du code. Avec les nouvelles possibilités d'organisation des fichiers de macros et une nouvelle balise <method>, 4e Dimension est plus productif que jamais. ♪

- Titre : Les macros 4D évoluent avec la 2004

- Auteur : Jonathan LE

- Parution : 1 décembre 2004

- Licence : Ce document est issu de http://www.developpez.com et reste la propriété exclusive de son auteur. La copie, modification et/ou distribution par quelque moyen que ce soit est soumise à l'obtention préalable de l'autorisation de l'auteur.

Sommaire

- I. Introduction

- II. Les fichiers inclus avec la démo

- III. Les nouveautés

- Un nouvel emplacement

- Une nouvelle balise

- IV. Les balises d’une macro

- La balise « macros »

- La balise « macro »

- Les balises simples

- Les balises doubles

- La balise text

- La balise method

- V. Créer des macros

- Emplacement des macros

- Petite macro entre amis…

- Appel d’une méthode 4D depuis une macro

- Les variables en entrée

- Les variables en sortie

- Appeler une macro pour ajouter un enregistrement

- VI. Conclusion

- VII. Base exemple

I - Introduction

Les macros sont une façon très pratique pour générer des portions de code sans à avoir à les retaper. Par exemple, vous pouvez insérer de longs commentaires d'entête à toutes vos méthodes sans saisir un seul caractère au clavier.

Avec l'ajout d'une nouvelle balise dans la version 2004, vous pouvez à présent faire appel à des méthodes 4D.

II - Les fichiers inclus avec la démo

Nous avons accompagné cette note technique d'un fichier de macros « samplemacros.xml ». Ce fichier est pleinement fonctionnel et vous avez juste à le glisser dans votre dossier 4D :

- ouvrez votre dossier 4D actif (il peut être différent selon que vous êtes en mono ou en client serveur (cf. <https://4d.developpez.com/documentation/4DDoc2004/CMF/CMF00485.HTM>)

- créez-y un dossier appelé Macros à côté de votre fichier Macros.xml d'origine.

Figure 1 : Mettez votre fichier de macros dans le dossier macros

III - Les nouveautés

Un nouvel emplacement

Avec la version 2003 vous aviez pris l'habitude d'avoir un fichier Macros.xml. Dorénavant, comme nous venons de le voir plus haut, les macros 2004 peuvent prendre place dans divers fichiers XML situés dans un dossier spécial du dossier 4D actif. Cette caractéristique va permettre aux auteurs de macros de les répartir et ainsi mieux organiser leur usage.

Une nouvelle balise

Encore une nouveauté : la balise <method> </method> qui permet de dynamiser les macros en y ajoutant des méthodes 4D :

<macro name="FirstTable">
<text>
<method>FirstTable</method>
</text>
</macro>

IV - Les balises d’une macro

La balise « macros »

La balise macros (avec un s) est la plus haute de toutes dans le fichier XML. On ne peut la trouver qu'une seule fois par fichier XML.

<macros>
<macro name="TestMacro">
<!-- Définition de la macro ici-->
</macro>
</macros>

La balise « macro »

La balise macro (sans s) débute la description d'une macro. À l'intérieur de ce tag, vous définissez ce que doit faire la macro.

Les balises suivantes s'utilisent en solitaire et ne sont pas attachées à une valeur. Notez la position du slash / : <caret/> et non <caret></caret>.

Les balises simples

<Selection/> cette balise est remplacée par la sélection

<caret/> quand la macro est appliquée, le point d'insertion se trouve à la place de « caret »

<user_4D/> cette balise est remplacée par le nom d'utilisateur de la session 4D

<user_os/> cette balise est remplacée par le nom de l'utilisateur système courant

<method_name/> cette balise est remplacée par le nom de la méthode 4D executée

<date/> cette balise est remplacée par la date système

<time/> cette balise est remplacée par l'heure système

<clipboard/> cette balise est remplacée par le contenu du presse-papiers.

Les balises doubles

<method> cette balise est remplacée par le résultat de la méthode exécutée

<text> encadre les valeurs de votre méthode.

La balise text

Tout texte contenu entre les balises text sera inséré dans la méthode. Il n'est pas possible d'imbriquer deux balises text l'une dans l'autre :

Cette forme d'écriture est impossible :

<macro name="SayHello">
<text>
<text>Hello, <user_os/></text>
</text>
</macro>

La bonne syntaxe est :

<macro name="SayHello">
<text>
Hello, <user_os/>!
</text>
</macro>

La balise method

La balise method permet à une macro d'exécuter une méthode 4D de la base de données. À l'intérieur de cette balise, vous écrivez le nom de la méthode et de ses paramètres s'ils existent.

Imaginons que nous ayons une méthode projet SuperMethode qui utilise un paramètre de type texte. La macro peut faire cet appel :

<macro name="Appel_Methode">
<text>
<method>SuperMethode("<method_name/>")</method>
</text>
</macro>

V - Créer des macros

Emplacement des macros

4D 2004 permet l'usage de plusieurs fichiers de macro. Ces fichiers XML doivent être placés dans un dossier « Macros » lui-même placé à côté du fichier de macros Macros.xml, le fichier par défaut.

Petite macro entre amis…

Nous allons nous essayer à la création d'une petite macro. Ouvrez votre éditeur de texte favori (Sur Mac BBedit est idéal) et écrivez :

<macros>
<macro name="TestMacro">
<text>
` Salut, mon nom est <user_os/>
` Et je vous donne l'heure. Il est : <time/>
` J'ai selectionné le texte <selection/>
` Et je continue de saisir ici <caret/>
</text>
</macro>
</macros>

Sauvegardez le tout sous le nom « testMacros.xml ». S'il n'existe pas déjà, créez un dossier Macros dans le dossier 4D actif. Mettez-y « testMacros.xml ». Si vous souhaitez aller plus vite, utilisez le fichier SampleMacros.xml livré avec la démo de la Note technique.

À partir de 4D, ouvrez une méthode et appelez la macro. En version 2004 un nouveau bouton d'appel des macros est accessible depuis la barre d'entête de l'éditeur de méthode. Comme dans la version précédente, vous avez toujours la possibilité de faire un clic droit sur Windows ou contrôle clic sur Mac et choisir la macro.

Figure 4 : Appeler une macro depuis la barre d'outils de l'éditeur de méthode

Et voici le résultat après application de la macro :

Figure 5 : le résultat

Appel d’une méthode 4D depuis une macro

Avec l'explication qui suit, vous serez en mesure d'appeler une méthode depuis une macro. Cela est rendu possible grâce à la balise <method>. Exemple suivant appelle la méthode FirstTable :

<macros>
<!-- macros -->
<macro name="FirstTable">
<text>
<method>FirstTable</method>
</text>
</macro>
</macros>

Jetons un œil sur la méthode FirstTable (ma première table)

1. ` La variable fait savoir à 4D quel type de substitution aura lieu

3. C_ENTIER LONG(_action)

5. ` On fixe le remplacement de blob en utilisant cette variable

6. C_BLOB(_blobReplace)

8. ` La méthode ne fait que créer du code pour créer des champs

9. C_POINTEUR($pTable)

10. $pTable:=Table(1)

12. TABLEAU TEXTE($fieldTitles;0)

13. TABLEAU ENTIER LONG($fieldNums;0)

15. LIRE TITRES CHAMPS($pTable->;$fieldTitles;$fieldNums)

17. C_ENTIER LONG($i)

18. C_TEXTE($codeLine;$tableName)

20. ` Construction du code et renseignement de la variable de sortie

21. $tableName:="["+Nom de la table($pTable)+"]"

22. Boucle ($i;1;Taille tableau($fieldTitles))

23. $codeLine:=$tableName+$fieldTitles{$i}+":="+Caractere(Retour chariot )

24. TEXTE VERS BLOB($codeLine;_blobReplace;Texte sans longueur ;*)

25. Fin de boucle

27. ` Disons à 4D que nous voulons insérer _blobReplace dans la méthode

29. _action:=2

Ouvrons une nouvelle méthode et exécutons la macro FirstTable :

Figure 7 : les macros peuvent être appelées par la saisie prédictive

La méthode génère le code qui va vous permettre d'assigner une valeur à chacun des champs de la table 1 comme ceci :

[Table 1]Field1:=
[Table 1]Field2:=
[Table 1]Field3:=

Figure 8 : le résultat de la macro

Il y a deux variables à remarquer dans la méthode FirstTable : _action et _blobReplace.

Ces variables process réservées disent à 4D que certaines actions doivent être exécutées quand la macro est appliquée. Ces variables process sont gérées par 4D et sont soit des variables d'entrée (contenant des valeurs fournies par 4D), soit des variables de sortie, que vous, développeur, devez assigner.

Les variables en entrée

Type

Nom

Description

C_TEXTE

_textSel

<--

Texte sélectionné (vide si > 32 000 caractères)

C_BLOB

_blobSel

<--

Texte sélectionné

C_ENTIER LONG

_selLen

<--

Longueur du texte sélectionné

C_TEXTE

_textMethod

<--

Texte de la méthode (vide si > 32 000 caractères)

C_BLOB

_blobMethod

<--

Texte de la méthode

C_ENTIER LONG

_methodLen

<--

Longueur du texte de la méthode

Les variables en sortie

Type

Nom

Description

C_TEXTE

_textReplace

-->

Résultat à substituer ("" par défaut)

C_BLOB

_blobReplace

-->

Résultat à substituer ("" par défaut)

C_ENTIER LONG

_action

-->

Type de substitution dans la méthode d’appel

0 = Néant

1 = Insérer _textReplace

2 = Insérer _blobReplace

3 = Remplacer la méthode par _textReplace

4 = Remplacer la méthode par _blobReplace

Appeler une macro pour ajouter un enregistrement

À présent nous ne souhaitons qu'effectuer des actions sans procéder à des remplacements.

Tout ce que la balise <method> sait faire est d'exécuter une méthode. C'est comme si elle était exécutée dans 4D lui-même, une méthode projet, méthode-objet, etc.

Ceci étant posé, la prochaine macro appellera une méthode TouchTable, créera un enregistrement selon les paramètres passés, sauvegardera et ouvrira une fenêtre affichant le résultat.

<macro name="TouchTable">
<text>
<method> TouchTable("Ajouté par <user_os/>";"<time/>") </method>
</text>
</macro>

La macro est toujours du même type si ce n'est que nous passons des paramètres de type chaîne.

Le code de la méthode Touchtable :

1. ` Méthode appelée de la macro TouchTable

3. C_TEXTE($1;$description)

4. C_TEXTE($2;$timeString)

5. C_HEURE($time)

7. $description:=$1

8. $timeString:=$2

10. $time:=Heure($timeString)

12. ` Créé un enregistrement pour la table Logs et règle certaines valeurs

13. CREER ENREGISTREMENT([Logs])

14. [Logs]Description:=$description

15. [Logs]Timestamp:=$time

16. [Logs]Id:=Numerotation automatique([Logs])

17. STOCKER ENREGISTREMENT([Logs])

19. ` Affichage du formulaire sortie de la table logs

20. TOUT SELECTIONNER([Logs])

22. ` Ouverture du formulaire sortie

23. C_ENTIER LONG($window)

24. $window:=Creer fenetre(100;100;500;500;Fenêtre standard ;"Logs";"CancelButton")

25. MODIFIER SELECTION([Logs];*)

27. FERMER FENETRE($window)

Cette fois-ci il n'a pas de variables process réservées. La méthode projet est des plus classique et peut être appelée de n'importe où. Essayez vous-même…

VI - Conclusion

Les macros sont des outils très utiles pour utiliser et réutiliser du code. Avec les nouvelles possibilités d'organisation des fichiers de macros et cette nouvelle balise <method>, 4e Dimension est plus productif qu'il ne l'a jamais été.

Pour aller plus loin, une note technique 4D-200311-32-FR, également sur les macros, a été publiée pour la version 2003.

Pour des exemples de macros, vous pouvez vous rendre dans la caverne des macros d'Ali Baba sur http://forum.4D.fr .

< https://www.developpez.net/forums/forumdisplay.php?f=151 >

VII - Base exemple

Téléchargez la base exemple :

base exemple