Jeedom

Introduction

Ce tutoriel a pour but de vous initier au développement de plugin pour Jeedom. Il n’a pas la prétention d’être exhaustif étant donné que je suis en train d’apprendre et qu’il y a très peu de documentation sur le sujet.

Voici les informations dont je dispose :

• Les sources de Jeedom : https://github.com/jeedom/core
• Les sources du plugin d’exemple nommé Template : https://github.com/jeedom/plugin-template
• La « documentation » de ce plugin Template : https://github.com/jeedom/plugin-template/blob/master/docs/fr_FR/index.md
• Les sources du plugin OpenZWave : https://github.com/jeedom/plugin-openzwave
• La « documentation » développeur : https://jeedom.github.io/documentation/phpdoc/index.html
• Des informations sur le forum qui datent un peu : https://www.jeedom.com/forum/viewtopic.php?f=117&t=16275

A partir de là, j’ai écrit un script qui permet de générer un squelette de plugin basique. Vous pouvez l’obtenir à cette adresse : https://github.com/Sylvaner/JeedomPluginSkeletonGenerator

Bien entendu pour ce tutoriel nous allons tout faire à la main.

Connaissances nécessaires

Pour le développement d’un plugin vous aurez besoin de connaitre un minimum les technologies suivantes :

• PHP,
• HTML/CSS,
• Bootstrap (optionnel),
• Javascript

Il vous faudra également beaucoup de motivation.

Préparation de l’environnement de travail

Afin de développer dans de bonnes conditions, je vous conseille d’installer Jeedom en local sur votre machine et de ne pas faire de tests sur votre installation.

Pour cela, rien de plus simple, vous exécutez les commandes suivantes à la racine de votre serveur web (habituellement /var/www/html) :

C’est dans le répertoire plugins de cette installation que vous pourrez développer votre projet (donc /var/www/html/plugins).

Pour ce tutoriel, le nom du plugin sera Tutoriel et l’identifiant sera donc tutoriel.

Structure

La première étape est de créer un répertoire qui sera l’identifiant de votre plugin, il doit être en minuscule et sans espace. Vous pouvez utiliser des underscores ( _ ) si nécessaire.

Un plugin est composé de différents répertoires donc la structure est la suivante :

• core : Contient les fichiers internes pour le fonctionnement du plugin ;
  • ajax : Contient les fichiers répondants aux requêtes Ajax ;
  • class : Contient la classe du plugin ;
  • php : Contient des fonctions nécessaires au fonctionnement du plugin ;
• desktop : Contient les pages affichées dans l’interface ;
  • css : Feuilles de style ;
  • js : Javascript des pages ;
  • modal : Code des fenêtres ;
  • php : Code de la page ;
• docs : Documentation du plugin ;
  • fr_FR : Documentation en français ;
• plugin_info : Contient des fichiers d’informations, l’icône, des scripts, etc. ;

Il y a bien sûr plein d’autres répertoires optionnels mais leur utilisation dépassent de loin l’objet de ce tutoriel.

Fichiers

Et maintenant nous pouvons mettre quelques fichiers dans ces répertoires. Nous allons donc créer l’essentiel.

plugin_info/info.json

Ce fichier contient les informations du plugin au format JSON.

Il contient les informations suivantes au minimum :

• id : Identifiant du plugin,
• name : Nom du plugin,
• licence : Licence sous laquelle le plugin est distribuée,
• require : Version minimum de Jeedom nécessaire,
• category : Catégorie du plugin pour la classification, la liste complète peut être trouvé dans le code contenu dans le fichier core/class/plugin.class.php de Jeedom accessible à cette adresse : https://github.com/jeedom/core/blob/beta/core/class/plugin.class.php,
• hasDependency : Indique si des dépendances doivent être prises en compte,
• hasOwnDaemon : Indique si le plugin possède un service,
• maxDependancyInstallTime : Temps d’installation maximum des dépendances,
• documentation : Lien internet des documentations,
• changelog : Lien internet pour informer des changements entre les versions.

Pour notre exemple, le fichier aura cette forme :

Il existe d’autres champs pour indiquer des informations complémentaires telles que l’auteur (autor), une description (description).

plugin_info/tutoriel_icon.png

Icône du plugin, pour les dimensions je vous invite à vous calquer sur celui d’un autre plugin.

plugin_info/installation.php

Fichier appelé lors de l’installation, la mise à jour et la suppression du plugin. C’est une classe qui contient 3 méthodes pour répondre à ces différents besoins.

Comme dans la plupart des fichiers PHP de ce tutoriel, il sera nécessaire d’inclure le fichier core.inc.php de Jeedom.

core/tutoriel.class.php

Ce fichier contient le moteur du plugin. Il contient deux classes afin de ne pas simplifier la lisibilité du code.

La fonction execute de la classe tutorielCmd est appelée lorsque Jeedom exécute une commande. Les informations de cette commande sont stockées dans la variable $_options.

Premier résultat

A ce moment vous devriez avoir l’arborescence suivante :

• tutoriel
  • core
    • ajax
    • class
      • tutoriel.class.php
    • php
  • desktop
    • css
    • js
    • modal
    • php
  • docs
    • fr_FR
  • plugin_info
    • info.json
    • installation.php
    • tutoriel_icon.png

Pour générer ceci automatiquement, vous pouvez télécharger le générateur de plugin présenté dans l’introduction et répondre aux quelques questions :

Tester son plugin pour la première fois

Vous pouvez maintenant aller sur Jeedom et activer le plugin dans le menu Plugin -> Gestion des plugins :

Cliquez sur le plugin grisé (désactivé) :

Cliquez sur Activer :

Le plugin est maintenant accessible.

Il apparait dans le menu. Si vous cliquez dessus, vous aurez une splendide page vide.

Un premier bouton

Maintenant, nous entrons vraiment dans la phase de développement du plugin.

Donc dans un premier, nous allons créer le fichier desktop/php/tutoriel.php et mettre le code suivant :

Nous allons maintenant ajouter du code HTML. N’essayez pas de ne mettre que ce qui vous semble essentiel, sinon ça ne fonctionnera pas.

Comme expliqué en introduction, je ne maitrise pas du tout la création de plugin donc je vais m’inspirer de d’autres pour trouver l’information. Je vais principalement m’appuyer sur le plugin OpenZWave qui fait partie du dépôt officiel.

Ce fichier qui contient la gestion des plugins et est divisée en 3 parties :

1. Le menu latéral,
2. Les listes :
   • Les actions,
   • La liste des objets,
3. Le panneau de contrôle des objets sous forme d’onglets :
   • Le formulaire de modification d’un objet,
   • La gestion des commandes.

C’est ici une version (très) épurée et le résultat ne donne rien d’intéressant.

Nous allons ajouter un bouton permettant d’accéder à la configuration. Il devra se trouver dans la balise ayant la classe eqLogicThumbnailContainer :

Vous allez voir cet attribut style partout, une des raisons est expliquée à la fin de ce tutoriel. Je n’ai pas vu un seul plugin qui utilisait des feuilles de styles, donc tout le monde utilise l’attribut style, nous verrons plus tard s’il est possible de faire un code plus propre. Pour le moment nous nous focalisons sur le fonctionnement.

On remarque que les chaînes de caractères sont entre double crochets. Cela permettra une internationalisation du plugin par la suite.

Dans cette portion de code nous avons un bouton possédant la classe eqLogicAction ayant un attribut data-action avec la valeur gotoPluginConf.

Les icônes des boutons proviennent de la police de caractère Font Awesome dont la liste est accessible à cette adresse : https://fontawesome.com/v4.7.0/

On peut aller voir le résultat. Ça ne marchera pas en l’état, mais le bouton est bien affiché.

Charger le javascript de Jeedom

Pour que les boutons et le menu latéral fonctionne, il faut indiquer à Jeedom de charger un fichier Javascript et lui passer quelques variables.

Pour cela nous allons ajouter quelques lignes en PHP.

Au début du fichier, on obtient dans un premier temps l’identifiant du plugin avec :

Puis nous envoyons ces variables à Javascript :

Les informations sont en fait ajoutées dans des balises <script>.

Et pour finir en bas de votre page, nous insérons le fichier Javascript de Jeedom nécessaire au fonctionnement de la page.

Ce fichier sera inséré en plein milieu du code, ça ne fera qu’une balise <script> supplémentaire…

Nous avons donc le code suivant à ce stade :

Miracle, le menu latéral fonctionne et quand on clique sur la clé à molette, la fenêtre de configuration s’affiche.

Le panneau de contrôle

Maintenant nous allons ajouter le panneau de contrôle qui est affiché lorsque l’on créé un objet. Il faudra donc ajouter le code à suivre dans cette balise :

Jeedom utilise la classe eqLogic pour identifier cet élément.

La barre de bouton

Cette barre bien connue des utilisateurs s’affiche avec le code suivant. Comme précédemment, il faut se focaliser sur le fonctionnement et occulter les balises de style qui agressent la rétine.

Ici nous avons principalement du code Bootstrap avec comme précedemment la classe eqLogicAction sur les bouton et l’attribut data-action qui indique l’action à réaliser. Si vous descendez dans la page, vous verrez la barre tant attendu.

Le contenu des onglets

Les onglets étant géré par bootstrap, il y aura beaucoup de code lié à son fonctionnement.

On Remarque surtout 2 lignes intéressantes :

On voit que les attributs d’un objet possèdent la class eqLogicAttr et que l’identifiant de cet attribut est défini par data-l1key.

Ça fonctionne. Tout va bien pour le moment sauf que le panneau devrait être caché par défaut. C’est normal j’ai volontairement retiré une partie du code.

Ainsi la ligne :

Va devenir :

On remarque le “display: none” qui cache bien le contenu par défaut.

Le bouton ajouter

Nous avons tout mis en place maintenant, il nous faut la possibilité de rajouter des objets, et pour cela il nous faut LE bouton +.

On cherche dans le code du plugin mobile cette fois ci, on trouve un bout de code et on obtient :

Ce qui donne :

Petit moment d’adrénaline quand on appuie sur le bouton +, on nomme le nouvel objet et rien ne se passe.

En fait l’objet a bien été enregistré, l’exécution du javascript ne fonctionne pas mais rien dans la console. Il doit manquer quelque chose, mais quoi…

Affichage des objets

On ne peut pas les voir, mais ils sont bien là. Pour cela nous allons ajouter une zone d’affichage des objets.

Donc nous allons ajouter la ligne suivante dans après la commande sendToVarJS :

Ainsi le tableau $eqLogics contiendra tous les objets du plugin.

Pour les afficher, nous allons ajouter une zone entre la liste des commandes et le panneau de contrôle. Si on vous demande un code HTML qui ne respecte aucune bonne pratique, celui-ci devrait convenir :

Nous avons donc ici une boucle foreach sur le tableau d’objets duquel on extrait l’identifiant $eqLogic->getId() et le nom lisible $eqLogic->getHumanName(true, true). Sinon, l’icône a les mêmes propriétés que les boutons précédemment créés.

A ce moment votre devrait ressembler à ceci :

On essaie l’affichage.

Merveilleux, tout s’affiche. Mais ça ne fonctionne pas.

Je l’avais dit, il faut bien tout reprendre car sinon nous allons avoir de nombreux problèmes. Et donc là, c’est normal nous n’avons pas rempli le panneau latéral.

Donc si vous laissez le menu à gauche vide, menu que personnellement je n’utilise jamais, et bien ça ne fonctionne pas.

La panneau latéral

Alors là du coup c’est simple, la structure est tout le temps la même.

Délimitant la liste du panneau latéral.

Nous allons insérer :

• un bouton, sans balise <li> (n’essayez pas de faire autrement sous peine de problèmes),
• un champ pour filtrer,
• la liste des objets.

Ce qui nous donne le code suivant :

Magnifique maintenant tout fonctionne.

On peut ajouter, modifier et supprimer des objets.

Amélioration du code

Maintenant, nous avons le code suivant :

Il fonctionne donc ce tutoriel pourrait s’arrêter là. Mais je nous allons essayer d’améliorer le code. Nous allons donc déplacer toutes les balises styles dans une feuille de style.

Le fichier CSS

Il faudra créer un fichier tutoriel.css dans le répertoire desktop/css.Il est nécessaire de dire à Jeedom de le charger. Pour cela vous devez ajouter cette ligne au début du fichier. Cela nous fera une jolie balise de style en plein milieu de la page :

Cette commande prend 4 paramètres :

• Répertoire,
• Nom du fichier,
• Type du fichier,
• Nom du plugin.

A ce niveau, je m’étais dit « Allez HOP ! » on vire toutes les attributs de style, on colle ça dans le CSS et c’est bon.

Erreur ! Si vous faites ça, vous aurez plein de surprises car les positions des visuels sont recalculées en direct et utilisent les balises de style existante sans doute. Il n’est pas possible « facilement » de supprimer les attributs style. En fait vous ne pouvez pas à partir du moment où elles donnent des informations de dimension..

Au moins, nous allons faire une chose, supprimer la balise <center>. Elle est obsolète depuis…. 1999 (https://www.w3.org/TR/html4/present/graphics.html#edef-CENTER).

Pour cela c’est très simple, vous faites une recherche dans le code et vous supprimez <center> et </center> bien sûr. Et dans le fichier CSS, vous écrivez ceci :

Il est possible d’aller plus loin avec le CSS, mais attention, chaque modification doit être testé car si vous enlevez les informations de certaines balises, votre plugin ne fonctionnera plus du tout.

Conclusion

J’espère qu’avec ce tutoriel vous pourrez plus facilement que moi vous lancer dans le développement de plugin pour Jeedom, surtout n’hésitez pas à me contacter si vous trouvez des erreurs ou si vous voyez des améliorations à apporter à ce tutoriel.