Empty¶

Lien des sources : https://github.com/pluginsGLPI/empty
Téléchargement : non pertinent

Ce plugin fournit… Rien. Vraiment !

Il est prévu pour être un point de départ pour l’écriture de plugins, avec des versions minimales de scripts utilitaires, et quelques conseils. Si vous recherchez plutôt les possibilités offertes pas les plugins, regardez le plugin exemple.

Créer un nouveau plugin¶

Un script utilitaire pour créer un nouveau plugin - plugin.sh est fourni. Vous devrez l’appeler avec un nom de plugin, une version et optionnellement le chemin dans lequel vous souhaitez le créer.

$ ./plugin.sh MyGreatPlugin 0.0.1

Le script nettoiera et passera en minuscules le nom que vous ave fourni, copiera les fichiers modèles dans le nouveau répertoire, et effectuera quelques remplacements.

Si vous utilisez le script sans spécifier de dossier de destination, votre répertoire mygreatplugin sera placé tout à côté de son propre dossier. Autrement, le répertoire sera créé dans le chemin spécifié :

$ ./plugin.sh MyGreatPlugin 0.0.1 /path/to/glpi/plugins/

Mise à jour d’un plugin existant¶

Il n’y a pas de méthode automatique pour mettre à jour un plugin existant, il y aurait en effet bien trop de cas de figure à gérer. Mais ne vous inquiétez pas, la procédure est assez simple ;)

L’utilisation des possibilités de empty est aussi simple que la création de quelques fichiers :

composer.json,
.travis.yml,
Robofile.php,
.gitignore.

Si vous n’avez pas encore de configuration composer ou travis, vous pouvez simplement copier celles du plugin empty. Dans le cas contraire ; ajoutez dans votre composer.json :

{
  "minimum-stability": "dev",
  "prefer-stable": true
}

Et ensuite lancez composer requires glpi-project/tools.

Dans le ficheir de configuration de travis, ajoutez juste l’appel au CS :

script:
  - vendor/bin/robo --no-interaction code:cs

Dans le fichier .gitignore, ajoutez ce qui suit :

dist/
vendor/
.gh_token
*.min.*

Quant au fichier de configuration de Robo.li, notez que celui qui est fourni par le plugin empty est quelque peu spécifique, vous devrez le modifier pour que tout fonctionne. Voir ci-dessous pour plus d’informations.

Pour finir, comme le projet tools fournit quelques fonctionnalités, vous pouvez supprimer les scripts utilitaires en doublon (les fichiers tels que release, extract_template.sh, …) qui pourraient être présents dans votre plugin.

Fonctionnalités¶

Standards de codage¶

Les règles GLPI PHPCodeSniffer sont fournis en tant que vendor/glpi-project/coding-standard/GlpiStandard/.

Pour vrifier les standards, utilisez la tâche code:cs de Robo.li :

$ ./vendor/bin/robo code:cs

Note

La commande ci dessus ignorera vendor et sera lancée dans le répertoire courant.

Si vous souhaitez adapter la liste d’ignorance ou les dossiers vérifiés; vous pouvez simplement surcharger $csignore et/ou $csfiles dans le RoboFile.php du plugin :

<?php

class RoboFile extends Glpi\Tools\RoboFile
{
   protected $csignore = ['/vendor/', '/lib/'];
   protected $csfiles  = ['./', 'setup.php.tpl']
   [...]
}

Vérifications automatiques¶

Pour des raisons pratiques, un fichier .travis.yml est également fourni, il est paramétré pour :

vérifier les standards de codage,
être lancé sur un certain nombre de configurations différentes

Vous devrez cependant activer les constructions depuis travis-ci depuis leur site web pour que les tests automatiques soient actifs.

Bien entendu, le fichier .travis.yml peut être adapté ; vous pouvez lancer des tests unitaires, créer/modifier une base de données, activer les notifications, etc. Référez-vous à la documentation Travis-CI pour plus de détails.

Minifying CSS and JS¶

Avertissement

Désactivé à partir de la 0.1.13, les bibliothèques utilisées par Robo sont anciennes et ne peuvent être remplacées.

Un script d’agrément, qui utilise Robo.li est fournit. Le fichier RoboFile.php est une classe vide qui étends Glpi\Tools\RoboFile (fournie par la dépendance glpi-project/tools) dans laquelle vous pouvez définir ce que vous voulez.

De cette manière, vous pourrez facilement tenir à jour le fichier commun sans que vos tâches spécifiques ne soient affectées.

Pour installer les bibliothèques requises, vous devrez installer composer puis lancer :

$ composer install -o

Il y a 3 cibles disponibles :

minify qui va minimifier tous les ficheirs CSS et JS (voir ci-dessous),
minify:css qui va minimifier toutes les feuilles de style CSS dans le dossier css de votre plugin, en créant une version .min.css version à côté du fichier original,
minify:js qui va minimifier tous les fichiers javascript dans le dossier js de votre plugin, en créant une version .min.js version à côté du fichier original.

Choisissez simplement une cible, et lancer comme ceci :

$ ./vendor/bin/robo minify:css

Note

Souvenez-vous que les fichiers compilés ne doivent pas être commités sur votre dépôt de sources. Leur création fait partie du travail du processus de release.

Pensez également à adapter vos scripts pour qu’ils chargent les versions minimifiées si elles sont disponibles, et l’original dans le cas contraire :)

À partir de GLPI 9.2, vous n’avez plus à vous soucier du chargement des fichier minimifiés lorsque vous utilisez les hooks add_css et add_javascript ! Vous dvez simplement appeler vos fichiers standards, et GLPI utilisera automatiquement la version minimifiée si elle existe, et si le mode DEBUG n’est pas actif.

Traductions¶

GLPI et ses plugins utilisent gettext pour l’internationalisation. Plusieurs étapes sont requises pour que cela fonctionne :

1 les chaînes à traduire doivent être extraites depuis les fichiers sources, un fichier POT ser ainsi créé ou mise à jour en conséquence, 2 les fichiers PO doivent être créés ou mis à jour depuis les fichier POT, 3 les fichiers PO doivent être traduits, 4 les fichiers ``MO doivent être compilés depuis la dernière version des PO.

Dans le dossier vendor/bin, vous trouverez un script extract_template.sh. Il va extraire les chaînes à traduire depuis le code source (voir le premier point ci-dessus).

Une fois qu’il aura été lancé, le fichier locale/mygreatplugin.pot sera créé ou mis à jour.

Pour les secondes et troisièmes étapes, vous aurez à faire un choix. Vous pouvez utiliser les outil gettext pour mettre à jour vos fichier PO et les traduire en utilisant un outil dédié, tel que poedit ; ou vous pouvez utiliser un système de traduction en ligne tel que Transifex ou Zanata. Le cœur de GLPI ainsi que de nombreux plugins sont traduits via Transifex actuellement.

Une fois que vos fichier PO auront été mis à jour, vous devrez les compiler en tant que fichiers MO. Vous pouvez lancer cela manuellement, le script de relese le fera de toutes façons ; référez-vous à la section relative à la compilation des fichiers MO.

Script de release¶

Un script de release est fournit dans vendor/bin/plugin-release. C’est un « simple » script Python ; vous devez juste avoir Python installé sur votre système (c’est le cas par défaut sur la plupart des distributions linux).

Avertissement

Notez que ce script de release n’est compatible que si vous utilisez le versionnage sémantique !

En utilisant les options par défaut, le script va tenter de retrouver le dernier tag de votre dépôt git, ajouter les dépendances tierces et créer une Release sur votre projet github.

$ ./vendor/bin/plugin-release
Do you want to build version 1.9.5? [Yes/no] y
Building glpi-order-1.9.5...
Archiving GIT tag 1.9.5
Adding vendor libraries
$ ls dist
glpi-order-1.9.5.tar.bz2  glpi-order-1.9.5.tar.bz2.asc

Pré-requis¶

Vous aurez besoin d’un interpréteur python installé ainsi que les modules suivants :

termcolor,
gitdb,
github (pour vérifier les versions existantes dans les brouillons également, et pour créer les releases github), à moins que vous ne spécifiez l’option --nogithub

Si vous voulez de l’aide sur le script, essayez de lancer ./vendor/bin/plugin-release -h.

Processus¶

Le processus de release effectuera les tâches suivantes pour vous :

vérifie que la constante de version soit identique au tag demandé ;
vérifie que la version dans le fichier XML pour le site web est la même que celle du tag demandé ;
vérifie si une release existe déjà en local ou en distant (en présumant que votre plugin soit héberge sur l’organisation github pluginsGLPI et qu’elle soit publique) ;
crée une archive des chemins qui ne sont pas exclus (.git`, tools, tests, …) ;
s’il y en a, installe les dépendances ;
s’il y en a, compile vos fichier MO ;
s’il y en a, compile vos feuilles de style CSS et vos fichiers Javascript (en utilisant Robo.li) ;
créé une archive de release avec tout cela ; et la met à disposition dans le dossier dist ;
utilise GPG pour signer l’archive ;

Note

Le processus de release standard ne travaillera pas sur vos fichiers directement, il effectuera en premier lieu une copie dans le dossier dist/src auparavant. La seule exception concerne l’option de compilation des fichiers MO.

Dans le but de vérifier si tout est OK avant de créer la vraie release ; créez votre tag et lancez ./vendor/bin/plugin-release -C avant de le pousser sur votre dépôt distant. De cette manière, vous serez en mesure de corriger les éventuels problèmes et re-créer votre tag en local (n’oubliez pas que les tags publiés ne devraient jamais être supprimés).

Compilation des fichiers MO¶

Le processus de release compilera chaque fichier PO trouvé dans le répertoire locales. Vous souhaiterez certainement que les derniers fichiers MO soient présents dans els sources, à des fins de tests. Le script de release fournit l’option --compile-mo (ou -m) pour cela.

$ ./vendor/bin/plugin-release --compile-mo

Avertissement

La commande ci-dessus travaillera directement sur vos fichier et non sur une copie, à l’inverse des autres commandes.

Pré-releases¶

Par défaut, le script de release ne travaillera que sur des tags existants. Toute pré-release devrait être dûment taguée ; mais il est possible que vous souhaitiez créer une archive sans tag dans certaines circonstances.

Pour indiquer au script de release ce qu’il doit archiver, vous devrez spécifier plusieurs paramètres :

--commit (or -c) fournissant le hash du commit,
--release (ou -r) fournissant la version (habituellement, la version à venir),
--extra (or -e) pour préciser une chaîne complémentaire (telle que alpha, beta, rc1, etc…)

Par exemple pour le plugin order :

$ ./vendor/bin/plugin-release --commit 632d515d4ac0 --release 1.9.5 --extra alpha1
$ ls dist
glpi-order-1.9.5-alpha1-20161103-632d515d4a.tar.bz2

Signature des releases¶

La signature des releases avec une clé GPG permettra aux utilisateurs de vérifier l’intégrité du téléchargement avant l’installation. Vous aurez besoin d’une clé GPG difussée publiquement ; l’option signature est active par défaut, vous pouvez la désactiver en utilisant l’option --nosign (ou -S).

Un fichier contenant la signature portant l »e même nom que l’archive avec une extension .asc sera créé dans le dossier dist.

Release GitHub¶

Le script de release créera une release GitHub sur votre dépôt, en brouillon, à moins que vous ne spécifiez l’option --nogithub (ou -g).

Note

Malheureusement, je n’ai pas été en mesure de téléverser la nouvelle archive sur cette release… Peut-être cela sera-t-il fixé dans le futur.

Pour pouvoir bénéficier de cette fonctionnalité, il faudra que le module python github soit installé ; et il vous faudra un token d’accès. Les tokens d’accès sont valides par utilisateur et donnent accès à l’ensemble de ses dépôts.

Vous devrez vous rendre sur la page des préférences de votre compte github, dans l’onglet « personnal access token ». Clic sur generate new token, fournissez la description souhaitée et assurez-vous d’avoir coché la case public_repo uniquement (il n’est pas nécessaire de cocher quoi que ce soit d’autre, vous pourrez créer plusieurs tokens au besoin).

Le token ne sera affiché qu’une fois ; enregistrez-le dans le fichier .gh_token dans le répertoire de votre plugin, et c’est tout !

Exclure des fichiers¶

Vous pouvez créer un fichier .ignore-release à la racine de votre plugin et y lister les fichiers et dossiers que vous voulez exclure explicitement de l’archive. Écrivez une expression par ligne

.+\.png
screenshots/

Certains fichiers seront automatiquement exclus :

.git*,
.gh_token
.tx/
tools/
tests/
.atoum.php
.travis.yml
.circleci/
.ignore-release
composer.lock
Robofile.php