Spécification des Extensions

Cette page contient les spécifications de développement des plugins dans TXM.

Objectifs

Actuellement, il est possible d'étendre TXM selon deux cycles :

  • Cycle long - dans Eclipse : en écrivant du code Java ou C des sources de TXM, avant le déploiement sous forme de setup pour installation sur le poste client
  • Cycle court - dans un TXM en cours d'exécution : en écrivant des scripts
    • scripts Groovy (import ou autre)
    • macros TXM (scripts Groovy encapsulés)
    • scripts R

Dans le cycle long le partage se réalise par le biais de SVN puis du setup.

Dans le cycle court le partage se réalise par échanges directs.

Nous cherchons à obtenir un cycle moyen de publication ayant un niveau d'intégration équivalent à celui du cycle long et un mode de production plus organisé que celui du cycle court.

Nous cherchons également à modulariser TXM.

Méthode

S'appuyer sur le mécanisme d'extension d'Eclipse et livrer des nouvelles fonctionnalités via des features RCP organisées par catégorie.

Documentation

Tutoriels développeur Eclipse :

Solution

La mise en place des mises à jour dans TXM, nous permet de profiter aussi du mécanisme de plugins P2 d'Eclipse pour installer des extensions de TXM.

Cela présente plusieurs avantages :

  • Faciliter l'intégration de modules indépendants dans TXM
  • Décomposer TXM en plugins : fonctionnalités, imports, etc.

Hébergement

Les extensions développées par l'équipe TXM

Le code sources des extensions est dans le SVN de TXM : plugins.

Les binaires sont disponibles dans 4 repositories P2 :

Contributions

  • Pour l'instant : nous contacter pour que l'on rajoute l'extension ds notre dépôt.
  • Plus tard : comme CRAN ?

Dépendances

Entre extensions et TXM

Les dépendances sont très diverses.

Souvent, une extension déclare une dépendance à :

  • une version minimale de toolbox TXM (org.txm.toolbox)
  • une version minimale de TXM RCP (org.txm.rcpapplication)

Parfois une dépendance à :

  • une version minimale de RCP Eclipse (org.eclipse.*)

Les niveaux d'update ALPHA, BETA, etc. des extensions correspondent aux niveaux correspondants d'update ALPHA, BETA, etc. de TXM RCP (org.txm.rcpapplication).

Actuellement, les extensions ne sont pas maintenues pour plusieurs versions de TXM. Seule la dépendance à la version STABLE courante de TXM sont disponibles et maintenues.

Nous prévoyions de maintenir les extensions de toutes les versions STABLE de TXM à partir de TXM 0.7.7 STABLE.

Entre extensions

Les dépendances sont très diverses.

État des extensions publiées

De la même façon que les macros, la page publique du wiki txm-users Extensions contient à la fois :

  • la documentation ou une redirection vers la documentation de chaque extension
  • la liste des extension publiées et leur niveau de publication (Dev, Alpha, Beta et Stable)

Installation

Deux commandes dans le menu principal “Fichier” permettent l'installation d'extension :

  • Ajouter une extension : récupère la liste des extensions disponible en fonction du niveau de mise à jour et les organise par catégorie
  • Ajouter une extensions tierces : permet d'installer une extension d'un autre update site

Post-installation

La post installation d'une extension se déroulle à 2 moment lors du lancement de TXM, dans la classe ApplicationWorkbenchAdvisor dans les méthodes :

  • preloadTxmCommandExtensions() : avant l'initialisation de la Toolbox (e.g extension CQP)
  • loadTxmCommandExtensions() : après l'initialisation de la Toolbox

Ces 2 méthodes chargent tous les plugins de type “org.txm.rcp.extentionpoint.command” (implémentant la classe “TxmCommand”), c'est à dire appelle la méthode “TxmCommand.preInstall() ou TxmCommand.install()” du plugin.

Une extension peut alors créé sa propre commande qui va finaliser son installation pour par exemple :

  • modifier les préférences
  • copier des fichiers Groovy

Pour qu'une extension puisse savoir si elle doit refaire sa post-installation, il faut créer une préférence VERSION qui stocke le numéro de l'extension lors de sa post-installation, si ce numéro est différent du numéro actuel, il faut alors refaire la post-installation.

OSGI

à lire : http://www.vogella.com/tutorials/OSGi/article.html

L'extension peut définir les filtres de démarrage du plugin à l'aide des champs du fichier MANIFEST.MF (ou depuis la page 'Overview' du plugin) :

  • champ “Platform Filter” OU “Eclipse-PlatformFilter” du manifest : e.g (osgi.os=linux)
  • section “Execution Environnements” OU “Bundle-RequiredExecutionEnvironment” du manifest : JavaSE-1.6

TXM livre une JVM à la version 1.6, tous les plugins doivent donc avoir 'JavaSE-1.6' dans leur manifest

Architecture d'une extension

Version

Les extensions ont une version qui permet de distinguer ses états successifs ainsi qu'établir un réseau de dépendences entre extensions tenant compte de leur état de développement.

La gestion des version se fera de la même façon que celle des versions de TXM : un numéro de version suivi d'une date au format (YYYYMMDDHHhh) généré automatiquement par le “qualifier” de la version déclarée dans le fichier METAINF.MF

Contributions de menus

Il faut rajouter des entrées de menu dans les menus d'URI suivantes :

  • Barre d'outils : “toolbar:org.txm.rcpapplication.toolbartools”
  • Menu contextuel de la vue Corpus : “popup:org.txm.rcpapplication.views.CorporaView”
  • Menu principal : “menu:menu.tools”

Il faut indiquer quand c'est possible à TXM où les nouvelles entrées de menu doivent s'afficher en ajoutant le préfix “after” ou before dans la déclaration de la contribution de menu de l'extension (plugin.xml) :

<menuContribution
            allPopups="true"
            locationURI="toolbar:org.txm.rcpapplication.toolbarcorpus?before=org.txm.rcpapplication.toolbarcorpus.description">

Dans la mesure du possible, lors de la création de menu contextuel dans un éditeur, construire l'identifiant du menu selon :

popup:ID_DE_L_EDITEUR
Si cela n'est pas possible, (par exemple, il y a plusieurs menus) et suffixé l'identifiant de menu avec dièse (#)

Aide d'une extension

  • Dans le fichier “plugin.xml” du plugin. Il faut ajouter un entrée de menu au menu d'URI “menu:menu.help.plugins” de TXM.
  • Cette entrée appelle la commande : “org.txm.rcpapplication.commands.OpenBrowser”
  • et sont parametre “org.txm.rcpapplication.commands.commandParameter2” indique la page à ouvrir : par défaut cette page est https://groupes.renater.fr/wiki/txm-users/public/extensions#nomdelextension_-_niveau

Partager les images entre extension

Pour utiliser une image de la toolbox :

platform:/plugin/org.txm.toolbox/src/groovy/org/txm/macro/oriflamms/prepare/images/toolbar/out.png 

Pour connaître facilement les références vers les différentes images disponibles dans les plugins hôtes la vue Plugin-in Image Browser peut être utilisée sous Eclipse (Windows\Show View\Plug-in Development\Plugin-in Image Browser) qui affiche les références pouvant être utilisées ensuite dans les plugin.xml (ex. dans “icon” d'une extension, menus, etc.).

Description d'une extension

Lorsqu'on lance la commande “Ajouter une extension”, TXM ouvre une fenêtre de dialogue qui contient une liste d'extensions disponibles à l'installation. Chaque élément de la liste est constitué d'une entête, le nom de l’extension, et d'une petite zone (4-5 lignes de hauteur) qui contient la description de l'extension.

La description de l'extension affichée est stockée dans le champ “description” du fichier “feature.xml” du projet Feature de l'extension. Le contenu du champ est du code HTML qui sera rendu dans la liste des extensions disponibles.

La zone de description les informations contient les infos suivantes :

  • “What's new ?” : contient les derniers changements du plugins
  • “Content” : une description du plugin
    • auteur
    • date de release
    • résumé de ce que fait le plugin
    • licence
    • URL
public/specs_extensions.txt · Dernière modification: 2018/04/05 15:44 par matthieu.decorde@ens-lyon.fr