Dans cette seconde partie du tutorial (voir première partie ici) sur la création d'un widget dans Orchard, nous nous concentrerons sur la mise en place des derniers éléments nécessaires à l'affichage côté client du widget et son utilisation dans le back-end du CMS.
1 - Handler
Il est nécessaire d’ajouter un handler au module, un objet comparable aux filtres dans une application classique ASP.NET MVC. Dans notre situation, celui-ci permettra d'utiliser le repository se chargeant de gérer les instances de notre widget. Pour plus d'information sur les handlers dans Orchard, je vous invite à consulter cette page de la documentation officielle.
2 – Driver
L’affichage d’un widget nécessite un driver, un type d’objet spécifique à Orchard similaire au controller dans une application ASP.NET MVC classique. Sa fonction principale est de répondre aux différentes demandes d'affichage ou d'édition de notre widget au sein du layout actif / backend.
Pour fonctionner, notre driver a besoin de trois fonctions: une méthode Display et deux méthodes Editor.
La méthode Display génère une shape (une vue spéciale à Orchard) utilisée lors du rendu du widget avec les différentes propriétés du widget. Les méthodes Editor (GET/POST) permettent d’afficher la vue d’édition et d’enregistrer les modifications apportées aux propriétés du widget. C'est ici qu'il est possible de mettre en place une validation serveur des données saisies par l'utilisateur.
3 – Controller
Lors de la création du modèle de notre widget en partie 2, nous avons défini une propriété « ControllerUrl ». Celle-ci a pour but de permettre à l’utilisateur d’avoir le choix entre plusieurs sources de données.
Le driver étant dédié aux mécaniques internes d'Orchard, nous allons créer un simple controller contenant une méthode renvoyant un objet JSON prenant en paramètre d'appel le type de données à afficher.
Il est aussi nécessaire de créer les modèles de données liées dont voici l’implémentation.
4 – Vues et bundles
1 – Bundles
A l'instar d'une application ASP MVC, Orchard permet d’utiliser des bundles de ressources. Cependant ceux-ci s'avèrent peu pratique à utiliser, c'est pourquoi il est conseillé d'utiliser l'extension Web Essentials pour Visual Studio qui permet de générer un bundle de nos ressources. Pour l'instant notre bundle ne contient que les différentes ressources de Kendo, nous ajouterons par la suite d'autres fichiers mettant en place la grid Kendo du widget.
Pour utiliser nos ressources au sein du widget, nous créons une classe ResourceManifest implémentant l'interface IResourceManifestProvider fournie par Orchard.
L'utilisation des fonctions DefineScript et DefineStyle de l'objet ResourceManifestBuilder dans la méthode BuildManifests permettent à Orchard de trouver les fichiers adéquats respectivement dans les dossier Scripts et Styles du module lors de son utilisation.
2 - Vues
Comme vu lors de l'étape précédente, nous allons avoir besoin de deux vues : Une vue pour la création/édition du widget dans le backend et une autre vue pour l'affichage dans le site.
Notre première vue contient les différents contrôles offerts à l’utilisateur pour personnaliser son instance de widget dans l’administration du site. Pour cela, nous créons un nouveau fichier MyGridContentPartEditorView.cshtml pour lequel nous spécifions un modèle de type MyGridWidgetPart, envoyé par la méthode Editor du driver.
La propriété ControllerUrl utilise deux contrôles RadioButton afin de spécifier le paramètre qui est envoyé à la méthode GetData() de notre controller.
La seconde vue se charge du rendu côté front-end. La div principale possède des attributs HTML qui représente les différentes propriétés du widget définies par l’utilisateur dans le dashboard. Nous n’utilisons pas d’attribut ID pour notre div car il est possible d’avoir plusieurs instances d’un même widget au sein d’une page Orchard. L’utilisation d’une classe permet de s’assurer que chacun de ceux-ci posséderont leurs propres propriétés.
Notez l’ajout des bundles précédemment crée dans notre vue. Cela permet à Orchard de n’inclure ces ressources que lorsqu’une page du site contient une instance de notre widget. Dans le cas où notre page contient plusieurs instances de notre widget, alors Orchard se chargera de ne les inclure qu’une seule fois.
Maintenant que nos vues sont prêtes, il ne nous reste plus qu’à créer les modules javascripts qui initialisent la grille kendo sur la div ayant pour classe « Grid ».
3 - Côté javascript
Fichier widgetModule.js
Ce fichier javascript contient un plugin jquery avec une méthode « setup » publique. On ne nomme pas expressément l’élément HTML sur lequel nous souhaitons créer la grille Kendo, laissant cette tâche à notre widgetLoader.
Il est important de noter que le code de notre fonction passe par une boucle foreach. Comme dit précédemment, au sein d’Orchard, chacun des widgets pouvant apparaître plusieurs fois sur une même page, il est nécessaire d’utiliser une classe (grid dans notre cas, cf ci-dessus) et donc d’exécuter la méthode pour chacun des éléments l'implémentant afin de s’assurer que les propriétés d’un widget n’influent pas sur celles d'un autre.
Etant donné que nous avons défini sur l’unique div de notre widget un certain nombre de data-attributes, il est simple de les récupérer par la suite dans notre méthode.
Fichier widgetLoader.js
Le second fichier javascript se contente d’invoquer la méthode setup de notre plugin jquery sur chacun des éléments HTML ayant la classe « grid » lorsque la page a fini de charger.
5 – Ajout du widget au site
Maintenant que notre widget est prêt, il ne reste plus qu’à configurer Orchard pour l’activer et le déployer au sein d’une page.
1 – Activer la migration
Une fois connecté dans l’interface administrateur grâce au login défini pendant l’installation, il est nécessaire de commencer par activer le module « Migrations » dans la section « Modules », ce qui permettra lors de l’activation de notre module d’exécuter la migration définie en étape 4 de la première partie du tutorial.
2 – Activer le module MyWidget
Nous pouvons maintenant activer notre module qui se trouvera dans la section « Uncategorized ». L’entrée représentant notre widget indique que notre module est dépendant des modules jQuery et Widgets comme nous l’avions défini dans le manifeste du module en étape 2.
Si tout s’est bien déroulé, le visuel après activation devrait être le suivant :
3 – Ajouter une instance du widget
Pour finir, il ne nous reste plus qu’à ajouter une instance de notre widget dans une page d’Orchard (la home dans notre cas).
Pour cela, on se dirige vers la section « Widget » du dashboard, on sélectionne une zone dans laquelle le widget sera placé et on clique sur le bouton d’ajout. Dans la page suivante, on sélectionne le widget "My Grid Widget", ce qui nous amène sur la page de configuration.
Les différents contrôles de notre vue d’édition (définis pendant l’étape 8) se trouvent en bas de page comme montré sur le lien suivant. Les autres contrôles sont eux ajoutés automatiquement par Orchard pour tous les widgets.
Le rendu côté client après la création des widgets est visible dans l'image ci-dessous. Comme on peut le voir, chacun des widgets a des propriétés différentes sans nécessiter d'intervention dans le code.
6 – Conclusion
La création d’un module et plus particulièrement d’un widget peut paraître compliquée au premier abord face à la quantité d’étapes à mettre en place, cependant une fois la prise en main des concepts clefs du CRM effectuée, la création devient sensiblement plus fluide et se trouve être très similaire à celle d'une application ASP MVC.