En ColdFusion, on peut écrire un tag personnalisé (Custom tag) de la même manière qu'on écrit une page CFM normal. Cependant un tag personnalisé peut utiliser quelques structures prédéfinies comme la structure « THISTAG » (qui permet de gérer son mode d'exécution), et la structure « CALLER » (qui permet d'accéder aux variables de la page appelante), ainsi que d'autres particularités que je vais détailler dans ce chapitre.

Exemple: myCustomTag.cfm
<cfparam name="ATTRIBUTES.attr1" default="UNDEFINED"> <cfif isDefined("THISTAG.executionmode")> <cfif THISTAG.executionmode EQ "start"> START: <cfoutput>#ATTRIBUTES.attr1#</cfoutput><BR /> <cfelseif THISTAG.executionmode EQ "end"> END: <cfoutput>#ATTRIBUTES.attr1#</cfoutput><BR /> </cfif> </cfif>

Il y a plusieurs manières pour appeler un tag personnalisé :

a)  En utilisant le tag cfmodule :
<cfmodule     template="myCustomTag.cfm"     attr1="ABC" />
b)  En utilisant le préfix "cf_" devant le nom du tag :
<cf_myCustomTag     attr1="ABC" />
c)  En utilisant le tag CFImport :
<cfimport           prefix="customTagsPrefix"     taglib="/tags/CustomTags">
<customTagsPrefix:myCustomTag attr1="ABC" />
Dans ce chapitre, je vais me concentrer sur l'utilisation du tag cfmodule.

Un tag CFML est utilisé dans le code en utilisant une balise XML qui peut avoir :
- Un début (ouverture de la balise) ;

- Un corps (optionnel) ;

- Une fin (fermeture de la balise) (optionnel).

En considérant cette conception à trois niveaux (début, corps, et fin), l'exécution des tags personnalisés fonctionne de la sorte :

a)  Pour le début de la balise (par exemple cfmodule), l'interpréteur ColdFusion commence par "instancier" le tag personnalisé (spécifié par l'attribut « template ») et puis l'interpréteur initialisera les attributs du tag personnalisé par les valeurs spécifiées dans le code. En fait, ColdFusion crée automatiquement une structure « ATTRIBUTES » et y attachera tous les attributs spécifiés dans le début de la balise. Dans l'exemple précédent, l'interpréteur instanciera le tag « myCustomTag » et puis ajoutera à la structure « ATTRIBUTES » l'attribut « attr1 » dont la valeur sera initialisé à « ABC ».

b)  Puis l'interpréteur va effectuer un premier appel au tag « myCustomTag » (on peut écrire un code particulier qui sera exécuté en réponse à cet événement).

c)  Lorsque l'interpréteur rencontre la fin de la balise (si spécifiée dans le code), il envoie le corps de la balise au tag « myCustomTag » (on peut écrire un code particulier qui sera exécuté en réponse à cet événement).

d)  L'interpréteur met fin à l'exécution du tag « myCustomTag ».

Remarque (1) : Certains tags CFML ne sont pas considérés comme des "vrais" tags et par conséquent leurs interprétations et ainsi leurs exécutions ne suivent pas la mécanique expliquée ci-dessus pour le tag cfmodule. Cela concerne, entre autre, tous les tags des instructions de flux de commande (cfif, cfloop, cfswitch). En effet, ces instructions de flux de commande sont traduites en un code Java proche de celui qu'on peut écrire nous même avec quelques détails de typage. Voici quelques cas d'interprétation des tags par ColdFusion :
- Il y a les tags de base de CFML (c'est le cas, par exemple, des tags cfquery et cfoutput) ;

- D'autres tags CFML sont simplement traduits en un simple code Java (comme c'est le cas des tags des instructions de flux de commande) ;

- Et d'autres tags CFML sont traduits en un code Java un peu plus complexe (comme c'est le cas pour le tag cffunction qui est traduit en classe Java) ;

Remarque (2) : Pour les tags CFML où le corps n'est pas obligatoire, il est possible de ne pas fermer la balise. Par exemple, pour le tag cfmodule vous pouvez écrire <cfmodule template="…"> au lieu de <cfmodule template="…" /> (ou <cfmodule template="…"></cfmodule>). Cela évite que ColdFusion ajoute un code spécial pour gérer la fermeture de la balise et ainsi éviter un deuxième appel au tag que dans certains cas peut être inutile. Mais il est plus préférable, pour être compatible avec la syntaxe XML, de fermer tous les tags.

Notes : Suite à la deuxième remarque, il serait, peut être, pratique si le tag cfmodule définissait un attribut spécial du genre « needSecondCall » qui permettra au développeur de spécifier si oui ou non l'exécution du tag a besoin d'un deuxième appel (un sorte d'indice que ColdFusion peut utiliser à la compilation du code). Exemple <cfmodule template="…" needSecondCall="false" />.

a) La balise cfmodule définit uniquement un début :

Exemple :
<cfmodule template="myCustomTag.cfm" attr1="ABC">
Sortie HTML :
START: ABC
b) La balise cfmodule définit un début et une fin (sans le corps) :

Exemple (1) :
<cfmodule template="myCustomTag.cfm" attr1="ABC" />
Exemple (2) :
<cfmodule template="myCustomTag.cfm" attr1="ABC"> </cfmodule>
Sortie HTML :
START: ABC END: ABC
c) La balise cfmodule définit un début, une fin, et un corps :

Exemple :
<cfmodule template="myCustomTag.cfm" attr1="ABC"> ÉCRIVEZ LE CORPS DE LA BALISE ICI.<BR /> </cfmodule>
Sortie HTML :
START: ABC ÉCRIVEZ LE CORPS DE LA BALISE ICI. END: ABC

La structure prédéfinie « THISTAG » contient des variables qui permettent de contrôler et gérer l'exécution des tags personnalisés. Quand un tag est appelé, ColdFusion crée automatiquement la structure « THISTAG » et initialise les variables de cette structure avec les valeurs appropriées.

a) hasendtag

L'appel d'un tag utilise la syntaxe XML : un appel est fait par une balise XML (par exemple cfmodule) qui peut avoir une fermeture ou non.

- Exemple d'appel qui n'a pas une fermeture :
<cfmodule template="myCustomTag.cfm">
Dans ce cas, ColdFusion initialise la variable « hasendtag » à « no ».

- Exemple d'appel qui a une fermeture :
<cfmodule template="myCustomTag.cfm"></cfmodule>
<cfmodule template="myCustomTag.cfm" />
Dans ce cas, ColdFusion initialise la variable « hasendtag » à « yes ».

b) executionmode

Cette variable peut prendre trois valeurs, 'start', 'end', et 'inactive' :

• Si la balise XML n'a pas une fermeture, le tag sera exécuté une seule fois. Dans ce cas ColdFusion initialisera la variable « executionmode » à 'start'.
  
  
• Si la balise XML a une fermeture, le tag sera exécuté deux fois :
  
  • pour le premier appel ColdFusion initialise la variable « executionmode » à 'start' ;
    
    
  • et pour le deuxième appel « executionmode » sera initialisée à 'end'.
    

Il est important que le code prenne en considération les valeurs des variables « hasendtag » et « executionmode » pour éviter une exécution inattendue et/ou incorrecte. Par exemple, imaginer un tag qui insère des données dans la base de données : Si on ne fait pas de teste sur le mode d'exécution de ce tag, on risque que le tag soit appelée deux fois, et donc le traitement d'insertion des données soit exécuté deux fois !

TODO : Ajouter des détails pour la valeur « inactive ».

c) generatedcontent

Cette variable contient le corps de la balise. Le tag personnalisé peut utiliser cette variable pour lire ou modifier le contenu de cette variable. Si le corps contient un contenu dynamique (variables, expressions, ou fonctions) alors ce contenu sera évalué avant que le corps de la balise soit affecté à cette variable. Pour mieux comprendre l'utilisation de la variable « generatedcontent », prenons l'exemple du tag personnalisé « MyQueryCustomTag.cfm » :
<cfparam name="ATTRIBUTES.queryTemlate" default="default"> <cfif isDefined("THISTAG.executionmode")>     <cfif THISTAG.executionmode EQ "start">         <!--- la variable generatedcontent est vide  ---> <cfelseif THISTAG.executionmode EQ "end">         <cfquery name = "myQuery" dataSource = "myDataSource">             <cfoutput>#THISTAG.generatedcontent#</cfoutput>         </cfquery>         <cfinclude template = "#ATTRIBUTES.queryTemlate#.cfm" />         <cfset THISTAG.generatedcontent = "" />     </cfif> </cfif>
Voici l'exemple d'un appel du tag « MyQueryCustomTag.cfm » :
<cfset tableName = "users" /> <cfmodule     template="MyQueryCustomTag.cfm"     queryTemlate="#tableName#">         SELECT user_name FROM #tableName# </cfmodule>
Remarque : Il faut noter que la variable « tableName » sera évaluée avant que le contenu ne soit envoyé au tag. Dans l'exemple précédent, à l'exécution du tag « MyQueryCustomTag » la variable « generatedcontent » va avoir la valeur « SELECT user_name FROM users ».

Analysons le code du tag « MyQueryCustomTag.cfm » de l'exemple précédent :
- Au premier appel du tag personnalisé (executionmode EQ "start") la variable « generatedcontent » est vide à cause qu'elle n'a pas été encore initialisée. Donc, c'est inutile de faire quoi que ce soit à ce niveau avec cette variable.

- Au deuxième appel du tag personnalisé (executionmode EQ "end"), on exécute la requête contenue dans la variable « generatedcontent » (« SELECT user_name FROM users ») puis on appel un modèle prédéfini pour le formatage du résultat de la requête. Enfin, on initialise la variable « generatedcontent » à une chaîne vide pour que son contenu ne soit pas affiché.

d) assocattribs
Cette variable est utilisée pour les tags imbriqués. Elle permet de rendre des variables visibles entre les tags parent/enfant.