Nouveautés Microsoft Dynamics CRM 2016: KeyPress & Auto-completion

Il y a quelques semaines, Microsoft a lancé la dernière version de Microsoft Dynamics CRM: CRM 2016. Cette version apporte plusieurs nouveautés intéressantes pour les consultants techniques CRM, notamment l'introduction des nouvelles méthodes de l'API cliente Xrm.Page. L’objectif principal de cette méthode est de simplifier et rendre plus agréable l’utilisation du CRM.

Grâce à ces nouvelles fonctions de l'API Xrm.Page nous pouvons aujourd'hui mettre en place une fonctionnalité extrêmement pratique qui est l'auto-completion, ceci de manière très simple comme vous allez le voir et sans utiliser ni code non supporté, ni ressources web html/css, ni bibliothèques externes tel que JQuery.  Nous pouvons également intercepter et réaliser des traitements sur l'évènement KeyPress ce qui nous donne la possibilité de contrôler, valider, transformer… les données entrées par l'utilisateur au fur et à mesure qu'il tape dans le champ.

Les nouvelles méthodes sont les suivantes:

• getValue,
• addOnKeyPress,
• removeOnKeyPress,
• fireOnKeyPress,
• showAutoComplete,
• hideAutoComplete

getValue: cette nouvelle méthode permet de récupérer la dernière valeur saisie dans champ après un évènement KeyPress. Elle est attachée à la collection des objets contrôles. Attention, il ne faut pas confondre cette fonction avec la fonction existante getValue attachée à la collection des attributs ! Cette dernière renvoie la dernière valeur d'un champ mais après un évènement OnChange. Pour utiliser la fonction:

 Xrm.Page.getControl("Field name").getValue()

addOnKeyPress: cette méthode permet de capturer l'évènement KeyPress (lorsque l'utilisateur appuie sur une touche de clavier) pour les champs de type « string » et « entier », et de définir les méthodes JavaScript à exécuter pour gérer cet évènement. La prise en compte de cet évènement dans le CRM nous permet de rendre sans doute l'expérience utilisateur plus interactive. En effet, à l'aide de cette fonction nous pouvons par exemple :

• Mettre en place la fonctionnalité de l'auto-completion.
• Ajouter des contrôles sur les données au fur et à mesure que l'utilisateur saisit des caractères dans le champ et ainsi afficher des messages à l'utilisateur ou corriger les données avant même qu'il termine sa saisie.
• Réaliser des conversions sur les données au fur et à mesure que l'utilisateur saisit des caractères dans le champ (Convertir en majuscules, minuscule…).
• ...

Pour utiliser cette fonction:

Xrm.Page.getControl("Field name").addOnKeyPress(OnKeyPressHandler)

removeOnKeyPress : cette méthode permet d'annuler l'abonnement d'une méthode à l'évènement KeyPress. Pour utiliser la fonction: 

Xrm.Page.getControl("field name").removeOnKeyPress(function name)

fireOnKeyPress : nous pouvons utiliser cette méthode pour déclencher à partir d'une autre fonction JS la méthode abonnée à l'évènement KeyPress  pour un champ donné. Pour utiliser cette fonction:

Xrm.Page.getControl(field name).fireOnKeyPress()

Avant de voir les autres méthodes, prenons l'exemple suivant:

L’objectif est de convertir le champ Nom de l'entité Compte au fur et à mesure que l'utilisateur inscrit des caractères dans ce champ.

Pour ce faire, nous allons utiliser les deux fonctions suivantes :

La 1ere méthode OnNameKeyPress permet de récupérer la dernière valeur entrée par l'utilisateur dans le champ "name", puis de les convertir en majuscule,

La 2eme méthode OnLoadHendler me permet d'abonner la fonction OnNameKeyPress à l'évènement KeyPress du champ "name". La fonction se lancera ainsi à chaque fois que l'utilisateur tape un caractère dans le champ "name".

Pour tester ce code dans le CRM, vous devrez créer une nouvelle ressource web et y copier le code :

Puis, attachez cette ressource au formulaire principal de l'entité compte et enregistrez la fonction OnLoadHandler sur l'évènement OnLoad:

Pour tester, créez un nouveau compte ou modifiez le nom d'un compte existant. Vous remarquerez que la conversion des caractères se fera automatiquement après la saisie d'un caractère dans le champ :

Après cet exemple, je vous propose de continuer la découverte des nouvelles méthodes:

showAutoComplete: cette méthode permet d'afficher une liste de suggestions pour les champs texte, dont l'utilisateur pourra sélectionner une valeur à affecter au champ. Le nombre de suggestions à afficher est limité à 10 maximum. Pour utiliser cette méthode:

Xrm.Page.getControl("Field name").showAutoComplete(object)

Pour fonctionner, cette méthode doit prendre un paramètre obligatoire qui doit contenir deux attributs :

Le 1er attribut se nomme "results". C’est un tableau contenant autant d'objets que vous avez de propositions. Chaque objet contient les paramètres suivants:

• Id : identifiant de la suggestion
• Icon : l'image qui devra s'afficher pour la suggestion
• Fields : libellé qui désigne le titre de la suggestion

Le 2ème attribut se nomme "commands" et permet de définir une action personnalisée qui peut être lancée par l'utilisateur à partir de la liste de suggestions via un lien qui s'affiche en bas de la liste ; cet attribut se compose des paramètres suivants:

• Id : identifiant de l'action
• Icone : l'image qui devra s'afficher pour le lien de l'action
• Label: qui désigne le titre de l'action
• Action : la déclaration de la méthode à exécuter

Donc, pour utiliser cette fonction, il suffit de construire l'objet obligatoire décrit ci-dessus, puis d’appeler la ligne suivante:

Xrm.Page.getControl("Field name").showAutoComplete(object)

hideAutoComplete : cette méthode permet de cacher la liste des suggestions pour le champ indiqué. 

Pour utiliser cette fonction:

Xrm.Page.getControl("Field name").hideAutoComplete()

Après la présentation de ces nouvelles méthodes, je vous propose le code d'exemple ci-dessous qui utilise toutes ces fonctions pour ajouter la fonctionnalité d'auto-completion sur un champ texte.

L'objectif est de mettre en place le système d'auto-completion sur le champ Pays de l'entité Compte, ce qui permettra à l'utilisateur de voir une liste de propositions lors de l'inscription de données dans ce champ.

Pour tester ce code, vous pouvez créer une nouvelle ressource web et y copier ce code, puis attacher la fonction OnLoadHandler à l'évènement OnLoad du formulaire de l'entité Compte et enregistrer et publier le formulaire.

Ensuite, vous pouvez tester en créant ou modifiant un compte existant. Lorsque vous inscrirez un caractère dans le champ Pays, la liste de suggestions va s'afficher comme ci-dessous:

Pour faire simple, dans cet exemple j'ai utilisé une liste des pays en dur.

Dans mon prochain article je montrerai comment alimenter la liste de suggestions à partir des données enregistrées au niveau d'une entité CRM.

N'hésitez pas à partager !