ALTERVISIONS Ajouter un Widget à SugarCRM Création de l AlterEnum Lior CHAMLA 09/04/2009 Nous allons voir comment créer un contrôle personnalisé à ajouter dans les différents modules de SugarCRM.
SOMMAIRE Avant-propos... 3 Contexte... 3 Déroulement... 3 1. But du champ AlterEnum... 4 2. Créer le champ AlterEnum... 4 2.1. La «base»... 4 2.2. Aller plus loin... 4 2.3. Le champ est prêt... 7 3. Intégration du champ au Studio... 8 3.1. Spécifier la nature du champ... 8 3.2. Intégrer le type «AlterEnum» au studio... 9 3.3. Faire la relation entre le nom du type «AlterEnum» et sa spécification... 9 3.4. Rendre le champ AlterEnum dynamique pour que le studio propose des listes... 11 Page 2 sur 13
AVANT-PROPOS CONTEXTE Ce document a été rédigé en interne au sein de la société Altervisions (http://www.altervisions.com) dans le but de faciliter l intégration de nouveaux «Widgets» au sein des formulaires SugarCRM. DEROULEMENT Au moment de la rédaction de ce document, le besoin était de créer un champ de sélection multiple au sein des formulaires. Ce champ existait déjà dans SugarCRM, mais sous une forme qui ne convenait pas à une utilisation simple. Il a donc fallu y trouver une alternative. Ce tutoriel se sert de ce besoin pour expliquer comment créer un widget au sein du CRM. POURQUOI EXPLIQUER LA CREATION DU CHAMP «ALTERENUM»? Tout simplement parce qu une fois que vous pouvez créer le champ AlterEnum, vous pouvez créer tout type de champ. En effet, au sein de SugarCRM, il existe les champs «simples» (champ texte, date, prix etc.) et les champs complexes, qui prennent en compte des valeurs multiples etc. Dans un premier temps nous allons voir comment créer le type AlterEnum, quels sont les fichiers à créer ou à modifier pour y parvenir. Puis nous verrons comment intégrer ce champ au studio, de manière à pouvoir ensuite, l ajouter dans les modules souhaités, au sein de SugarCRM. Page 3 sur 13
1. BUT DU CHAMP ALTERENUM Le type AlterEnum a été imaginé pour pallier au manque de confort du «MultiSelect» proposé d origine par SugarCRM. Il s agit de remplacer un <select multiple=true> par deux balises select différentes, et de donner la possibilité à l utilisateur de passer des valeurs de l une à l autre. FIGURE 1 : VUE DU CHAMP ALTERENUM A L'OEUVRE 2. CRÉER LE CHAMP ALTERENUM Lorsque l on veut créer un contrôle personnalisé dans SugarCRM,, on doit s inspirer de include/sugarfield/fields/base/ include/sugarfield/fields/base/ qui contient tout ce qui est nécessaire à la présentation d un contrôle. Ce dossier contient : EditView.tpl DetailView.tpl ListView.tpl SearchForm.tpl 2.1. LA «BASE» Ce dossier contient aussi un fichier SugarFieldBase.php qui contient la classe de base d un contrôle. Tous les contrôles offerts par SugarCRM sont dérivés de cette «base». 2.2. ALLER PLUS LOIN Le champ AlterEnum que nous nous proposons de créer est en fait une spécialisation du champ Multienum déjà proposé par Sugar (lui-même étant une spécialisation du champ Enum, qui est une spécialisation du champ Text, lui-même dérivant la base). Nous allons créer un EditView.tpl qui nous correspond. Ensuite il faudra créer le dossier include/sugarfield/fields/alterenum/ et y placer nos fichiers. Pour notre cas, il suffit d y mettre : Page 4 sur 13
Notre propre EditView.tpl Le fichier SugarFieldAlterEnum.php FIGURE 2 : EDITVIEW.TPL Page 5 sur 13
FIGURE 3 : SUGARFIELDALTERENUM.PHP Page 6 sur 13
Les fichiers «SugarFieldNom.php», tels que SugarFieldAlterEnum.php, spécifient la manière dont le contrôle doit être représenté : Ils guident Sugar pour que celui-ci trouve le bon template à afficher. Attention : Nous n avons pas pris soin d ajouter les autres templates (DetailView, ListView etc.) car nous utiliserons ceux du Multienum. On a maintenant notre dossier include/sugarfield/fields/alterenum/ contenant deux fichiers, le template d édition et SugarFieldAlterEnum.php spécifiant quel template appeler pour chaque situation. 2.3. LE CHAMP EST PRÊT Après ces petites étapes, le champ est prêt mais n est pas encore utilisable dans le Studio. Nous allons maintenant voir comment lier ce champ au Studio pour l ajouter à certains objets. Page 7 sur 13
3. INTÉGRATION DU CHAMP AU STUDIO 3.1. SPÉCIFIER LA NATURE DU CHAMP Pour spécifier la nature du champ, il suffit de se rendre dans le dossier modules/dynamicfields/templates/fields/ modules/dynamicfields/templates/fields/ et d y créer le fichier TemplateAlterEnum.php (par convention, les fichiers de définition sont appelés «TemplateNomDuChamp.php»). Ce fichier doit contenir une classe qui étend la classe TemplateField (Définition basique d un champ, elle contient beaucoup de fonctions dont une seule nous intéresse). Notre champ (AlterEnum) est une refonte du MultiEnum de Sugar, nous n allons donc pas étendre la classe TemplateField, mais la classe TemplateMultienum,, qui étend TemplateEnum, qui étend TemplateField. FIGURE 4 : TEMPLATEALTERENUM.PHP Dans cette classe, il faut bien faire attention à redéfinir la fonction get_field_def() qui spécifie le type de champ : FIGURE 5 : GET_FIELD_DEF() DANS TEMPLATEALTERENUM.PHP Comme on le voit, on utilise la fonction de la classe parente pour obtenir une définition classique, et on ajoute certaines options, telles que dbtype qui est le type de données stockées en base de données. Page 8 sur 13
3.2. INTEGRER LE TYPE «ALTERENUM» AU STUDIO Cette opération est très simple, puisqu elle consiste à créer un fichier custom/modules/modulebuilder/language/en_us.lang.php et d y écrire : <?php $mod_strings['fieldtypes']['alterenum'] = 'AlterEnum';?> En réalité nous spécifions simplement que le studio disposera d une entrée AlterEnum lors de la création d un champ au sein d un module. 3.3. FAIRE LA RELATION ENTRE LE NOM DU TYPE «ALTERENUM» ET SA SPECIFICATION Le fichier modules/dynamicfields/fieldcases.php contient un ensemble de cas en fonction du type de champ. On doit donc «mapper qui spécifie ce champ.» le type AlterEnum avec notre TemplateAlterEnum.php Pour ce faire, on peut créer un cas générique, qui prendra en compte tout nos nouveaux champs. FIGURE 6 : UN CAS GENERIQUE POUR NOS NOUVEAUX TYPES DE CHAMP Vous pouvez maintenant ajouter le champ de type AlterEnum dans vos modules. Essayez maintenant d aller dans le studio et d ajouter un champ AlterEnum dans un module. Page 9 sur 13
Comme vous pouvez le constater, il manque certaines informations concernant le contenu du champ : FIGURE 7 : ALTERENUM DANS LE STUDIO Mais nous essayons de faire du multienum.. En d autres termes, quand vous ajoutez le champ de type AlterEnum à un module, il ne vous propose pas de listes de valeurs sur lesquelles travailler. En fait nous souhaitons arriver à ceci : FIGURE 8 : OBJECTIF DE VUE POUR LE CHAMP ALTERENUM DANS LE STUDIO Page 10 sur 13
3.4. RENDRE LE CHAMP ALTE ALTERENUM DYNAMIQUE QUE POUR QUE LE STUDIO STUD PROPOSE DES LISTES Dans le dossier modules/dynamicfields/templates/fields/forms modules/dynamicfields/templates/fields/forms/ on va créer un fichier alterenum.php et un fichier alterenum.tpl.. Ces deux fichiers ne servent qu à afficher des options supplémentaires lors de l utilisation du champ AlterEnum dans le studio. Nous reprenons le code déjà utilisé par le champ MultiEnum (qui se trouve dans multienum.php et multienum.tpl). multienum.tpl FIGURE 9 : ALTERENUM.PHP La fonction contenue dans le fichier alterenum.php est get_body(), qui permet en fait, de retrouver le corps que l on recherche (voir figure 8). Il est intégralement récupéré de multienum.php mais le type est modifié modifi en AlterEnum. FIGURE 10 : ALTERENUM.TPL Ceci est le template qui permet d afficher les dropdowns lists dans le studio (récupéré à partir de multienum.tpl). C est grâce à cela que l on peut choisir les valeurs à afficher dans le champ MultiEnum. Page 11 sur 13
Il faut maintenant expliquer au Studio que l on souhaite utiliser ces nouvelles informations, il faut donc modifier le fichier modules/dynamicfields/fieldviewer.php qui contrôle les vues affichées lorsque l on utilise certains champs. On y ajoute notre type de champ. FIGURE 11 : FIELDVIEWER.PHP On voit donc que lorsque l on va utiliser le type AlterEnum dans le studio, cela va appeler la page alterenum.php qui spécifie que l on doit afficher certaines informations, dont les valeurs à utiliser (voir figure 8). Voila, on peut maintenant utiliser le champ AlterEnum dans le studio! Page 12 sur 13
TABLE DES ILLUSTRATIONS Figure 1 : Vue du champ AlterEnum à l'oeuvre... 4 Figure 2 : EditView.tpl... 5 Figure 3 : SugarFieldAlterEnum.php... 6 Figure 4 : TemplateAlterEnum.php... 8 Figure 5 : get_field_def() dans TemplateAlterEnum.php... 8 Figure 6 : Un cas générique pour nos nouveaux types de champ... 9 Figure 7 : AlterEnum dans le studio... 10 Figure 8 : Objectif de vue pour le champ AlterEnum dans le studio... 10 Figure 9 : Alterenum.php... 11 Figure 10 : Alterenum.tpl... 11 Figure 11 : FieldViewer.php... 12 LIENS UTILES http://developers.sugarcrm.com/wordpress/2009/03/16/tip-new-tipsandtricks1-creating-ayoutube-sugar-field/ http://developers.sugarcrm.com/wordpress/2009/03/16/tip-new-tipsandtricks2-newsugarfields-in-studio/ Page 13 sur 13