ColdFusion offre la possibilité d'écrire ses propres fonctions en utilisant le tag cffunction. L'appel de ces fonctions est fait de la même manière qu'un appel d'une fonction prédéfinie dans ColdFusion.

Exemple (créer le fichier « users.cfm », et l'éditer pour saisir le code des exemples) :

- En utilisant la syntaxe CFML :
<cffunction name="setFirstName"> <cfargument name="argFirstName" />     <cfset VARIABLES.firstName = ARGUMENTS.argFirstName /> </cffunction>
- En utilisant le tag CFScript :
<cfscript>     function setFirstName(argFirstName) {         VARIABLES.firstName = argFirstName;     } </cfscript>
Note de performance : Pour les deux syntaxes (CFML et CFScript), ColdFusion crée une classe java qui étend la classe prédéfinie de ColdFusion UDFMethod. Par la suite, pour tous les appels des fonctions, ColdFusion va utiliser la réflexion (l'introspection) et les méta-informations pour exécuter les fonctions. Par conséquent, les appels des fonctions risquent de causer des problèmes de performances, mais ColdFusion "remédie" à ce problème en instanciant les classes des fonctions une seule fois au chargement de la page (ou du CFC) et affectant les instances à des variables statiques.

Recommandations :

• Il est recommandé de scoper correctement tous les paramètres locals de la fonction avec le scope ARGUMENTS chaque fois qu'on lit ou modifie ces variables.
  
  
• Il est aussi recommandé de déclarer toutes les variables locales des fonctions en utilisant le mot clé « var » (ou en utilisant le scope « LOCAL »).
  

Ces recommandations sont importantes pour ne pas utiliser ou modifier accidentellement la valeur d'une variable d'un autre scope.

Voici un exemple pour mieux expliquer le but de ces recommandations :
<cffunction name="getChar"> <cfargument name="ascii" /> <cfif val(ARGUMENTS.ascii)> <cfset chrValue = chr(val(ARGUMENTS.ascii)) /> </cfif> <cfreturn chrValue /> </cffunction>
Remarques :

1. La variable « ascii » est scopée avec le scope ARGUMENTS (lorsqu'elle est utilisée, en lecture ou modification, dans le code de la fonction). Donc si l'appel de la fonction ne précise pas une valeur pour ce paramètre (<cfset getChar() />), alors ColdFusion va générer l'erreur suivante « VARIABLE ASCII IS UNDEFINED. ».
   
   
2. Si la variable « ascii » n'était pas scopée avec le scope ARGUMENTS (lorsqu'elle est utilisée, en lecture ou modification, dans le code de la fonction), et que l'appel de la fonction ne précise pas une valeur pour ce paramètre (<cfset getChar() />), alors ColdFusion va chercher s'il y a une variable avec le même nom définie dans un scope parent, et si trouvée, il va juste utiliser cette variable, sinon ColdFusion va générer l'erreur suivante « VARIABLE ASCII IS UNDEFINED. ». L'un ou l'autre comportement, la lecture du code ne permet pas de connaitre si c'est le comportement voulu par le développeur.
   
   
3. La variable « chrValue » n'est pas scopée, et donc il y a deux cas qui peuvent arriver :
   
   • Si la valeur de l'argument « ascii » n'est pas une valeur numérique valide, ColdFusion va sauter à l'instruction suivante « <cfreturn chrValue /> ». ColdFusion doit vérifier si cette variable a été définie à l'intérieur de la fonction ou dans l'un des scopes accessibles par le code de la fonction (exemple, le scope VARIABLES) et si oui, il va juste utiliser cette variable, sinon ColdFusion va générer l'erreur suivante « VARIABLE CHRVALUE IS UNDEFINED. ». L'un ou l'autre comportement, la lecture du code ne permet pas de connaitre si c'est le comportement voulu par le développeur.
     
     
   • Si la valeur de l'argument « ascii » est une valeur numérique valide, ColdFusion va sauter à l'instruction suivante « <cfset chrValue = chr(val(ARGUMENTS.ascii)) /> ». Et si la variable « chrValue » a été définie dans l'un des scopes accessibles par le code de la fonction (exemple, le scope VARIABLES) alors sa valeur sera écrasée. Là aussi, la lecture du code ne permet pas de connaitre si ce comportement était voulu par le développeur.
     

Notes : On verra plus tard dans ce chapitre que le tag cfargument défini un attribut required qui précise si un paramètre est requis ou pas lors de l'appel de la fonction.

On fait appel à une fonction de la même manière qu'on appel une fonction prédéfinie de ColdFusion.

Pour passer des paramètres à une fonction, on peut utiliser les deux syntaxes suivantes :

• Les valeurs des paramètres sont passées comme une liste séparées par des virgules.
  L'ordre des paramètres est important.
  <cfinclude template="users.cfm" /> <cfset setFirstName("Tarek") />
  
  
• On peut ajouter le nom du paramètre devant chaque valeur.
  Avec cette syntaxe, on est sûr que chaque paramètre va recevoir son exacte valeur.
  L'ordre des paramètres n'est pas important dans ce cas.
  <cfinclude template="users.cfm" /> <cfset setFirstName(argFirstName = "Tarek") />
  

<cffunction name = "" description = "" displayName = "" hint = "" output = "yes|no" access = "public|private|package|remote" returnType = "DATA_TYPE" returnFormat = "JSON|PLAIN|WDDX" secureJSON = "yes|no" roles = "" verifyClient = "yes|no">

1. Attributs du tag cffunction

   Attribut	Requis	Description
   name		Nom de la fonction
   description		Description de la fonction
   displayName		Nom explicite de la fonction
   hint		Information supplémentaire sur la fonction
   output		Cet attribut permet de préciser si la fonction peut générer du HTML. Voici les valeurs possibles pour cet attribut : Si la valeur spécifiée est « yes », alors le code de la fonction est interprété comme s'il a été mis à l'intérieur du tag cfoutput. Si la valeur est « no », alors le code de la fonction est interprété comme s'il a été mis à l'intérieur du tag CFSilent. Si cet attribut est omis, alors le code de la fonction est interprété comme n'importe quel code CFM, et donc il faut utiliser le tag cfoutput si on a besoin de générer une sortie HTML.

   
   

   Attribut	Requis	Description
   access		(valeur par défaut : public) L'attribut « access » définit la propriété d'accessibilité des fonctions ; autrement dit il permet de préciser si une fonction est visible à l'extérieur du CFC ou non. Voici les valeurs possibles pour cet attribut : public (valeur par défaut) : la fonction est accessible dans tout le code de l'application. private : la fonction peut être appelée par le code du CFC qui définie la fonction et les CFCs qui étendent le CFC. package : la fonction peut être appelée par le code du CFC qui définie la fonction, les CFCs qui étendent le CFC, et tous les CFCs qui sont dans le même package. la fonction peut être appelée par le code du des pages CFM qui sont dans le même package. remote : la fonction peut être appelée par le code d'une page (ou CFC) exécutée localement ou à distant, ou par le code d'un client distant (dans ce cas cette valeur est requise) à travers une URL, Flash, ou un service web. Si cet attribut est omis, la fonction est par défaut accessible dans tout le code (« public »).
   returnType	Uniquement pour les services web	(valeur par défaut : ANY) Cet attribut permet de préciser le type de la valeur retournée par la fonction. Si la valeur spécifiée pour cet attribut ne correspond pas à un des types reconnus par ColdFusion, alors ColdFusion considère que c'est un nom d'un CFC et donc à l'exécution, ColdFusion va générer une erreur si la valeur retournée ne correspond pas au nom d'un objet CFC défini dans l'un des scopes accessibles par le code de la fonction. ColdFusion génère une erreur si la valeur ne retourne aucune valeur alors que la valeur de cet attribut est « numeric ». ColdFusion ne génère pas d'erreur pour les autres types.
   returnformat		Cet attribut permet de préciser le format de données retournées par la fonction en cas d'un appel distant. Cet attribut n'aucun effet pour les appels locaux. Voici les valeurs possibles pour cet attribut : JSON : ColdFusion sérialise les données à retourner en format JSON. WDDX : ColdFusion sérialise les données à retourner en format WDDX. PLAIN : ColdFusion convertie la valeur à retourner (dont le type est un type simple ou XML) en chaîne de caractères et la renvoie sans la sérialiser. ColdFusion génère une erreur si le type de la valeur à retourner est complexe, comme un tableau ou un objet binaire. ColdFusion génère aussi une erreur si la valeur de l'attribut « returntype » est spécifiée mais n'est pas « any, boolean, date, guid, numeric, string, uuid, variablename, ou XML ». Par défaut, si cet attribut est omis, ColdFusion sérialise les valeurs (types simples ou complexes excepté XML) à retourner en format WDDX, et les retourne en format texte XML. Cette valeur peut être surchargée si la fonction est appelée, par exemple, par un tag CFHttp qui redéfinie la valeur de « returnformat » avec l'attribut CFHttpparam.
   secureJSON		Cet attribut permet de préciser s'il faut ajouter un préfixe de sécurité au début des valeurs retournées en format JSON par la fonction en réponse à un appel à distance. Par défaut, cet attribut prend : la valeur précisée pour la variable « This.secureJSON » dans le fichier « Application.cfc » ; la valeur de l'attribut secureJSON du tag cfapplication ; ou la valeur configurée dans la section « Prefix Serialized JSON » dans CFADMIN.
   roles		Cet attribut permet de préciser les droits d'exécution de la fonction. La valeur de cet attribut est une liste de « roles » (séparés par une virgule) qui donnent droit à invoquer la méthode. Si un utilisateur a un « role » qui match avec un des « roles » spécifiés dans cette attribut, alors il sera autorisé à exécuter la méthode. Par défaut, si cet attribut est omis, tous les utilisateurs peuvent exécuter la méthode.
   verifyClient		(valeur par défaut : no) Cet attribut permet de préciser si un jeton (TOKEN) de sécurité encrypté est nécessaire pour les appels distants de la fonction. Cet attribut doit être utilisé uniquement pour les appels AJAX.

   
   NOTE :

   Lorsqu'on utilise la syntaxe cfscript, il faut utiliser les métadonnées pour définir des valeurs aux attributs de la fonction. Voici un exemple d'utilisation des métadonnées :
   <cfscript> /** * @access public * @returnType string * @output false * @hint get field : firstName **/ function getFirstName() { return VARIABLES.firstName; } </cfscript>
   La syntaxe pour préciser le nom de la métadonnée ressemble au style JavaDoc. Le nom de la métadonnée doit être précéder par le caractère @ et suivi par la valeur que l'on veut attribuer.
   Si le nom de la métadonnée ne correspond pas à un nom d'un attribut valide, alors ColdFusion le considéra comme n'importe quelle métadonnée que le programmeur peut ajouter à la fonction.
2. Valeurs possibles pour l'attribut « returnType »

   Type de données	Description
   void	Ne retourne aucune valeur.
   any	La valeur retournée peut être de n'importe quel type.
   boolean	Valeur booléenne.
   numeric	Valeur numérique (entière et réel).
   string	Chaîne de caractères.
   date	Date.
   array	Tableau.
   struct	Structure.
   query	Objet requête.
   guid	La valeur retournée doit être un GUID dont le format est xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. Avec x est un caractère qui représente une valeur hexadécimale valide [0-9A-F].
   uuid	La valeur retournée doit être un UUID dont le format est xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxxxxxx. Avec x est un caractère qui représente une valeur hexadécimale valide [0-9A-F].
   component	La valeur retournée doit être un CFC.
   xml	La valeur retournée doit être un objet XML CFML ou une chaîne de caractères XML.
   binary	Valeur binaire.
   CFC_NAME	Une chaîne de caractères qui correspond à un nom de CFC.

   
   Exemple 1 : Objet requête
   
   Fichier : myQuery.cfm <cffunction name="getQuery" returnType="Query"> <cfargument name="newQuery" type="boolean" required="no" default="false" /> <cfif ARGUMENTS.newQuery OR NOT IsDefined("VARIABLES.query")> <cfreturn QueryNew("id") /> <cfelse> <cfreturn VARIABLES.query /> </cfif> </cffunction> <cfoutput> <cfdump var="#getQuery(true)#" /> <br /> <cfset VARIABLES.query = QueryNew("id,code") /> <cfdump var="#getQuery(false)#" /> </cfoutput>
   Résultat d'exécution du code : query ID -- query ID CODE -- ----
   Exemple 2 : CFC
   
   Fichier : users.cfc <cfcomponent> <cffunction name="init"> <cfset VARIABLES.fields = StructNew() /> <cfset VARIABLES.fields.firstName = "UNDEFINED" /> <cfreturn this /> </cffunction> <!--- get field : firstName ---> <cffunction name="getFirstName"> <cfreturn VARIABLES.fields.firstName /> </cffunction> <!--- set field : firstName ---> <cffunction name="setFirstName"> <cfargument name="firstName" /> <cfset VARIABLES.fields.firstName = ARGUMENTS.firstName /> </cffunction> </cfcomponent>
   Fichier : testUsers.cfm <cffunction name="getUserCFC" returnType="users"> <cfargument name="isNewUserCFC" type="boolean" required="no" default="false" /> <cfif ARGUMENTS.isNewUserCFC OR NOT IsDefined("VARIABLES.userCFC")> <cfreturn new users() /> <cfelse> <cfreturn VARIABLES.userCFC /> </cfif> </cffunction> <cfoutput> First Name : #getUserCFC(true).getFirstName()#<br /> <br /> <cfset VARIABLES.userCFC = new users() /> <cfset VARIABLES.userCFC.setFirstName("Tarek") /> First Name : #getUserCFC(false).getFirstName()#<br /> </cfoutput>
   Résultat d'exécution du code : First Name : UNDEFINED First Name : Tarek

<cfargument name = "Nom de l'argument" displayName = "" hint = "" required = "no|yes" type = "DATA_TYPE" default = "" />
Les tags cfargument doivent être placés au top du tag cffunction (avant tout autre tag).

Notes : Il faut noter qu'en ColdFusion, le tag cfargument n'est pas nécessaire pour passer des arguments à la fonction (nous verrons ci-dessous une manière pour accéder aux arguments de la fonction sans que leurs noms soient spécifiés explicitement avec le tag cfargument). Ceci-dit, il est très important de définir tous les arguments de la fonction avec le tag cfargument, cela rend le code plus lisible et facilement compréhensible par les autres développeurs, d'autant plus que le tag cfargument permet de forcer le teste sur le type des argumentes et aussi d'y définir des valeurs par défaut s'ils sont omis lors de l'appel de la fonction.

Les arguments passés à l'appel de la fonction peuvent être référés dans le code de la fonction en utilisant :

• les noms (sans préfixe) définies dans les tags cfargument (attribut « name ») ;
  
  
• les noms définies dans les tags cfargument (attribut « name ») en les préfixant par le scope ARGUMENTS (exemple ARGUMENTS.myArg1) ; je recommande d'utiliser cette syntaxe, encore une fois, pour rendre le code lisible et facilement compréhensible par les autres développeurs et aussi pour éviter d'utiliser accidentellement une autre variable ;
  
  
• le scope ARGUMENTS comme un tableau (exemple ARGUMENTS [i]); les indices du tableau commence par 1, et le premier élément du tableau correspond au premier argument, le deuxième élément correspond au deuxième argument, etc. Je recommande d'utiliser cette syntaxe uniquement si le nombre des arguments ne peut être établies statiquement.
  
  

1. Attributs du tag cfargument

   Attribut	Requis	Description
   name		Nom de l'argument.
   displayName		- Valeur par défaut : Nom de l'argument. Nom explicite de l'argument.
   hint		Information supplémentaire sur l'argument.

   
   

   Attribut	Requis	Description
   required		- Valeurs possibles : [no|yes] - Valeur par défaut : no
   type		- Valeurs possibles : Voir la liste en bas - Valeur par défaut : any Type de l'argument.
   default		Si l'argument est omis, elle sera créer et initialiser par la valeur de cet attribut.

2. Valeurs possibles pour l'attribut « type »

   Type de données	Description
   any	N'importe quel type.
   boolean	Valeur booléenne.
   numeric	Valeur numérique (entière et réel).
   string	Chaîne de caractères.
   variableName	La valeur de l'argument doit être une chaîne de caractères formatée selon les conventions de ColdFusion pour nommer des variables. Utile si on veut créer des variables avec les noms passés en argument à la fonction.
   date	Date.
   array	Tableau.
   struct	Structure.
   query	Objet requête.
   guid	L'argument doit être un GUID dont le format est xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. Avec x est un caractère qui représente une valeur hexadécimale valide [0-9A-F].
   uuid	L'argument doit être un UUID dont le format est xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxxxxxx. Avec x est un caractère qui représente une valeur hexadécimale valide [0-9A-F].
   component	L'argument doit être un CFC.
   xml	L'argument doit être un objet XML CFML ou une chaîne de caractères XML.
   binary	Valeur binaire.
   CFC_NAME	Une chaîne de caractères qui correspond à un nom de CFC.