Réalisation Plugin

Projet GenDiapo
Rédacteurs
FLAMENT Alexandre
QUAY-THEVENON Christophe
Responsable
DAVID Jean-Pierre
le 23/08/2001
Réalisation d’un Plugin
Version
II.1.0
Statut
Final
Disponibilité
Livrable
Site : http://gendiapo.sourceforge.net/
SOMMAIRE
Historique __________________________________ 4
1. Introduction ______________________________ 5
2. Plugin DTD _______________________________ 6
2.1. Présentation __________________________________6
2.2. Description ___________________________________8
2.2.1. Actions possibles __________________________________ 8
2.2.2. Détail des classes _________________________________ 10
2.2.2.1.
Classe org.gendiapo.editor.GenericGenDiapoEditor ___________ 10
2.2.2.2.
Classe org.gendiapo.editor.GenericGenDiapoEditPanel ________ 11
2.2.2.3.
Classe javax.swing.text.ViewFactory ______________________ 12
2.3. Construction & Intégration ______________________15
2.3.1. Paramètres d’un plugin DTD _________________________ 16
2.3.1.1.
Dtd-plugin ___________________________________________ 16
2.3.1.2.
Name _______________________________________________ 16
2.3.1.3.
LongName ___________________________________________ 16
2.3.1.4.
Version _____________________________________________ 16
2.3.1.5.
Author ______________________________________________ 16
2.3.1.6.
Url _________________________________________________ 17
2.3.1.7.
Dtd ________________________________________________ 17
2.3.1.8.
Editor_______________________________________________ 17
2.3.1.9.
Icon ________________________________________________ 18
2.3.2. Utilisation du squelette _____________________________ 18
3. Plugin Action _____________________________ 22
3.1. Présentation _________________________________22
3.2. Description __________________________________22
3.2.1. Actions possibles _________________________________ 22
3.2.2. Détail des classes _________________________________ 22
3.2.2.1.
Interface org.merlotxml.merlot.plugin.Action ________________ 22
3.2.2.2.
Classe org.merlotxml.util.xml.XpathUtil ____________________ 23
3.2.2.3.
Classe org.gendiapo.publisher.Publisher ___________________ 24
3.3. Construction & Intégration ______________________24
3.3.1. Paramètres d’un plugin Action _______________________ 25
3.3.1.1.
Action ______________________________________________ 25
3.3.2. Utilisation du squelette _____________________________ 26
Glossaire __________________________________ 28
Annexe ____________________________________ 29
DTD des Plugins __________________________________29
DTD du Plugin DTD ______________________________________ 29
DTD du Plugin Action_____________________________________ 30
URL utiles _______________________________________30
Ant __________________________________________________ 30
DOM
(Document Object Model) - Package org.w3c.dom ________ 30
Package javax.swing.text _________________________________ 31
Merlot Plugin development guide ___________________________ 31
Historique
Version
Date
Publication
II.0.1
16/08/2001
Version initiale
II.0.2
21/08/2001
Mise en place du squelette
Ajout de liens vers la documentation
II.1.0
23/08/2001
Correction d’après les remarques de Cécile Guilloux
Projet GenDiapo
Causes Changement
4 / 31
CLIPS / SYNERGIE3R
1. Introduction
Le but de ce document est de décrire les différents éléments à mettre en place pour
créer un plugin : ce dernier correspond à un ensemble de classes Java permettant
de mettre en place un nouveau traitement dans GenDiapo.
Son but principal est de faire évoluer l’outil auteur GenDiapo en lui ajoutant de
nouveaux traitements. En effet, l’outil auteur GenDiapo étant le plus générique
possible avec des traitements par défaut, les plugins permettront de modifier ces
derniers.
Un plugin peut être de deux types bien distincts :

Plugin DTD : ce plugin va permettre d’adapter l’outil auteur de GenDiapo à
une DTD bien précise, adaptation concernant les différents aspects visuels de
l’outil auteur

Plugin Action : ce plugin va permettre d’ajouter un traitement bien précis à
l’outil auteur
Pour ces deux types de plugins, nous donnerons une brève présentation de leurs
buts, puis des explications sur les différentes classes permettant de les construire et
enfin la manière de les intégrer dans l’outil auteur GenDiapo.
REMARQUE
Projet GenDiapo
Même si les différents types de plugin ne sont pas particulièrement
compliqués à réaliser, certaines parties (comme la modification de la vue
stylée) requièrent un niveau assez bon en Java
5 / 31
CLIPS / SYNERGIE3R
2. Plugin DTD
Les différents paragraphes suivants vont nous permettre de détailler les différents
éléments à implémenter pour vous aider à réaliser un plugin DTD.
2.1. Présentation
Ce type de plugin permet de personnaliser l’outil auteur GenDiapo pour un type de
DTD bien précis : Il permettra de configurer l’affichage des attributs, du contenu ou
des icônes associées pour chaque balise présente dans la DTD.
Les deux grandes actions possibles pour le plugin DTD sont :

Un filtrage : ce plugin propose des méthodes permettant de rendre invisible
(uniquement dans l’outil auteur) des nœuds ou des attributs

Une gestion des vues : ce plugin permet de gérer l’affichage des différents
nœuds de l’arbre XML dans l’outil auteur :
 Les attributs de chaque nœud peuvent être présents soit dans la vue stylée
soit dans le panneau des attributs
 L’affichage de chaque attribut peut être modifié dans la vue stylée ou dans
le panneau des attributs (le contenu PCData est toujours visible dans la vue
stylée)
 L’affichage des différents champs dans la vue stylée peut être également
personnalisé par ce type de plugin
Avec l’aide de l’image suivante de GenDiapo, nous allons décrire les différentes
parties configurables par un plugin DTD :
Projet GenDiapo
6 / 31
CLIPS / SYNERGIE3R
Vue stylée
Panneau des attributs
Arbre
L’outil auteur est divisé en 3 parties bien distinctes et nous allons donner les
différents éléments modifiables pour chaque partie :

L’arbre XML : dans cet arbre, le plugin permet de filtrer les nœuds affichés et
également de définir les attributs qui vont être affichés dans la vue des
attributs.

La vue stylée : cette vue affiche, pour chaque nœud de l’arbre, son contenu
avec le contenu des attributs autorisés. L’affichage des éléments dans cette
vue pourra être configurable par l’intermédiaire du plugin.

Le panneau des attributs : cette vue affiche, pour chaque nœud, l’ensemble
des attributs (sauf ceux filtrés) répartis dans un onglet. Le plugin permet de
Projet GenDiapo
7 / 31
CLIPS / SYNERGIE3R
personnaliser l’onglet (nombre de panneaux, nom des panneaux) ainsi que la
répartition des attributs dans l’onglet.
Après avoir vu toutes les configurations possibles avec le plugin DTD, nous allons
décrire les différentes interfaces et méthodes à implémenter.
2.2. Description
Tout d’abord, nous allons donner un tableau donnant la liste des différentes classes
et méthodes à implémenter en fonction du type d’actions désirées : Ensuite, pour
chacune, une brève description de son but et de ses différents paramètres sera
donnée.
2.2.1.
Projet GenDiapo
Actions possibles
8 / 31
CLIPS / SYNERGIE3R
Classe
Méthodes
(Description des méthodes)
Filtrage
Attribut
Gestion des Vues
Nœud
Vue des Attributs
Vue Stylée
Global
GenericGenDiapoEditor
Définir affichage attributs
Rendre un nœud invisible
suppressFromView
suppressTag
Editer le panel d’attributs
getEditPanel
Sauver les attributs
savePanel
Donner les vues du PCDATA
getViewFactory
Synchroniser les différentes
vues
syncView
Ajouter des éléments a menu
getMenuItems
GenericGenDiapoEditPanel
Créer onglet attributs
initOnglet
Donner référence onglet pour
l’attribut
getTab
Ajouter élément dans onglet
createTab
Edition attribut
getEditComponent
ViewFactory
Créer la représentation d’un
élément de la vue stylée
Projet GenDiapo
create
9 / 31
CLIPS / SYNERGIE3R
Nous allons détailler un peu plus longuement les différentes classes et méthodes
énoncées ci-dessus.
2.2.2.
Détail des classes
Parmi les différentes classes présentées ci-dessus, la classe GenericGenDiapoEditor
est à surcharger dans tous les cas.
Pour les autres classes, le fait de surcharger est en fonction de la configuration
désirée :
 GenericGenDiapoEditPanel si l’on souhaite changer l’aspect du panneau des
attributs

ViewFactory si l’on souhaite changer l’affichage par défaut de la vue stylée
2.2.2.1. Classe org.gendiapo.editor.GenericGenDiapoEditor
Cette classe contient l’ensemble des méthodes relatives à l’affichage des différents
éléments (arbre, vue stylée et attributs) dans l’outil auteur.
Elle implémente l’interface org.gendiapo.GenDiapoEditor de GenDiapo et étend la
classe org.merlotxml.merlot.GenericDOMEditor de Merlot.
Les différentes méthodes à implémenter ou surcharger sont les suivantes :

boolean suppressFromView (MerlotDOMNode node, String attribute)
Cette méthode renvoie vrai si l’attribut (de nom attribute) de node ne doit pas
être affiché dans la vue stylée.
Par défaut, cette méthode renvoie vrai, permettant ainsi d’avoir tous les attributs
dans les onglets.

boolean suppressTag (String nodeName)
Cette méthode renvoie vrai si le nœud de nom nodeName ne doit pas être
visible dans l’arbre XML.
Par défaut cette méthode renvoie faux, ce qui permet de pouvoir ajouter dans
l’arbre XML toutes les balises présentes dans la DTD.

JPanel getEditPanel (MerlotDOMNode node)
Cette méthode renvoie l’éditeur associé au nœud contenant les attributs du
nœud. Cet éditeur sera une instance de la classe GenericGenDiapoEditPanel et
les attributs pourront être édités de la façon désirée avec les méthodes de cette
classe.

ViewFactory getViewFactory()
Cette méthode renvoie une instance de ViewFactory (package javax.swing.text)
pour la vue stylée.
Projet GenDiapo
10 / 31
CLIPS / SYNERGIE3R

void syncView (MerlotDOMNode node, JEditorPane text)
Cette méthode synchronise le nœud node avec son contenu dans la vue stylée
text (placement du curseur et des scrolls).
Par défaut le curseur est placé sur le premier élément visible du nœud.

JMenuItem[] getMenuItems(MerlotDOMNode node)
Cette méthode permet de renvoyer un ensemble d’éléments de menus qui
seront ajoutés au pop up menu correspondant au nœud node.
Ces éléments seront ajoutés en supplément de ceux déjà présents.
2.2.2.2. Classe org.gendiapo.editor.GenericGenDiapoEditPanel
Cette classe contient les méthodes concernant l’édition des attributs dans un onglet.
La surcharge de ces méthodes permettra de créer plusieurs éléments dans l’onglet
et de répartir les attributs dans ces derniers. Par défaut, tous les attributs sont placés
dans un onglet nommé < attributs >.
Elle implémente l’interface org.gendiapo.GenDiapoEditPanel de GenDiapo et étend
la classe org.merlotxml.merlot.GenericDOMEditPanel de Merlot.
Les différentes méthodes à surcharger sont les suivantes :

JScrollPane createTab (String id)
Cette méthode renvoie un JScrollPane, de référence id, qui va être ajouté à
l’onglet des attributs.
Cette méthode est rarement surchargée.

JTabbedPane initOnglet ()
Cette méthode renvoie l’onglet qui va contenir les attributs avec les différents
JScrollPane. Par défaut, l’onglet ne contient qu’un seul JScrollPane nommé
« Attributs ».
L’exemple suivant créé deux onglets nommés « General » et « Prix » :
private static final String IDGeneral = "General";
private static final String IDPrix
= "Prix";
private static final String IDAutre
= "Autre";
public JTabbedPane initOnglet()
{
//init onglet
JTabbedPane ong = new JTabbedPane();
// ajoute deux onglets
ong.addTab("Général", createTab(IDGeneral));
ong.addTab("Prix", createTab(IDPrix));
ong.addTab("Autre", createTab(IDAutre));
return ong;
}
Projet GenDiapo
11 / 31
CLIPS / SYNERGIE3R

String getTab (DTDAttribute a)
Cette méthode renvoie une chaîne correspondant à l’identifiant du JScrollPane
dans lequel l’attribut doit être ajouté.
L’exemple suivant met :
 l’attribut « nom » dans l’onglet « General »
 l’attribut « unitee » et « pardix » dans l’onglet « Prix »
 les autres attributs dans l’onglet « Autre »
public String getTab(DTDAttribute a)
{
if (a.getName().equals("nom")) {
return IDGeneral;
} else if
(a.getName().equals("unitee")
|| (a.getName().equals("pardix")) {
return IDPrix;
}
return IDAutre;
}

JComponent getEditComponent (DTDAttribute attr)
Cette méthode renvoie le composant associé au type d’attribut donné en
paramètre.
Par exemple, si l’attribut est de type IDREF, le composant renvoyé sera un
combo box contenant les IDREF du document.

void save() throws PropertyVetoException
Cette méthode enregistre les attributs à partir des données saisies par
l’utilisateur. Si vous avez créez vos propres composants avec la méthode
getEditComponent, cette méthode doit être surchargée.
La sauvegarde proprement dite n’est pas faite dans cette méthode
public save() thows PropertyVetoException {
Hashmap attributs = new Hashmap() ;
// Lisez la valeur de vos composants
// Et Stockez les valeurs dans attributs
save(attributs)
}
2.2.2.3. Classe javax.swing.text.ViewFactory
La vue stylée utilise le package javax.swing.text de Java. Avant de commencer les
différentes explications, la visite des urls suivantes est conseillée :
 http://java.sun.com/j2se/1.3/docs/api/javax/swing/text/package-summary.html
 http://java.sun.com/j2se/1.3/docs/api/javax/swing/text/Document.html
 http://java.sun.com/j2se/1.3/docs/api/javax/swing/text/View.html
Projet GenDiapo
12 / 31
CLIPS / SYNERGIE3R
Ce package permet de stocker la vue stylée dans un document
(javax.swing.text.document) composé d’une part de son texte et d’autre part de sa
structure.
Cette dernière est organisée avec différents éléments qui, en plus de leurs
propriétés, font référence à leur point de départ et leur point de fin dans le contenu
du document.
Les différents éléments dans GenDiapo sont donc les suivants :
 Le cadre pour un nœud
 Le cadre pour un attribut
 Le cadre pour le PCData
 Le texte décomposé en
 Paragraphe
 Une ligne visuelle d’un paragraphe
Voici un exemple de la répartition de ces éléments dans la vue styléé :
Une ligne visuelle
Un paragraphe
Cadre pour le PCData
Cadre pour un nœud
Pour chacun de ces éléments, une classe View permet de donner la représentation
visuelle. La classe ViewFactory permet de créer les View à travers la méthode View
create(Element elem).
Une instance peut être donnée par la méthode getViewFactory de
GenericGenDiapoEditor.
Projet GenDiapo
13 / 31
CLIPS / SYNERGIE3R
Nous allons maintenant voir comment architecturer le plugin afin de créer nos
propres représentations visuelles d’un document.
En premier lieu, l’éditeur fournit, par défaut, une visualisation pour chaque type
d’éléments grâce à sa propre ViewFactory.
Les cas d’utilisations possibles sont donc :

Utiliser complètement l’affichage par défaut : il suffit que la méthode
getViewFactory de GenericGenDiapoEditor renvoie null.

Créer partiellement ou totalement ses propres visualisations : les actions à
effectuer sont :
 Renvoyer une instance de sa propre ViewFactory par getViewFactory de
GenericGenDiapoEditor
 Renvoyer null pour les éléments conservant l’affichage par défaut
 Renvoyer sa propre View pour les éléments affichés différemment
Nous allons détailler les View par défaut de GenDiapo : A chaque type d’éléments,
cités plus hauts, correspond une classe
Le cadre pour un nœud
Le cadre pour un attribut
Le cadre pour le PCData
Un paragraphe
Une ligne visuelle
Projet GenDiapo
org.gendiapo.editor.document.AbstractNodeView
étend BoxView
variables d’instances
protected org.w3c.dom.Node xmlNode;
protected Shape shape;
méthodes
public void paint(Graphics g, Shape a)
public void paintSelected(Graphics g, Color c)
org.gendiapo.editor.document.AbstractAttrView
étend BoxView
méthodes
protected org.w3c.dom.Node xmlNode
protected org.merlotxml.util.xml.DTDAttribute merlotDef
org.gendiapo.editor.document.AbstractPCDataView
étend BoxView
variables d’instances
org.w3c.dom.Node xmlNode;
javax.swing.text.ParagraphView
javax.swing.text.LabelView
org.gendiapo.editor.document.ConstantView
méthodes
public static Font getAttributeFont()
public static Font getNodeFont(int size)
14 / 31
CLIPS / SYNERGIE3R
De manière générale, nous avons :

protected org.w3c.dom.Node xmlNode
Représentant le nœud associé à la View

protected Shape shape
Donnant la forme de la vue, utilisée par paintSelected

protected org.merlotxml.util.xml.DTDAttribute merlotDef
Donnant l’attribut représentant la View

public void paint(Graphics g, Shape a)
Permettant de dessiner la vue

public void paintSelected(Graphics g, Color c)
Permettant de dessiner le fait que la View est sélectionnée.
L’ordre d’appel entre paint et paintSelected n’est pas déterminé.
Cette méthode doit utilisée shape pour obtenir la forme de la sélection
Les méthodes surchargées sont généralement :
 paint(Graphics g, Shape allocation)
 paintSelected(Graphics g, Color c)
 Le constructeur
La classe ConstantView permet de donner les fontes associées aux attributs et au
nœud, respectivement getAttributeFont() et getNodeFont(int size).
2.3. Construction & Intégration
Après avoir vu comment créer les différentes méthodes et classes du plugin DTD, la
dernière étape consiste en la construction du plugin sous la forme d’un jar et de son
intégration dans GenDiapo.
Pour créer ce jar, l’arborescence suivante doit être utilisée :

plugin.xml : ce fichier contient les informations sur le plugin (cf le paragraphe
sur les paramètres d’un plugin DTD

classes/ : ce répertoire contient l’ensemble des classes java compilées

dtd/ : ce répertoire contient les dtd associées au plugin

META-INF/MANIFEST.MF : Le fichier MANIFEST.MF (méta information pour
le fichier jar) est vide
Projet GenDiapo
15 / 31
CLIPS / SYNERGIE3R
L’intégration du plugin dans GenDiapo se fait en plaçant le jar dans le répertoire
[directory]/plugins, [directory] étant le répertoire ou se situe le fichier jar de
GenDiapo.
2.3.1.
Paramètres d’un plugin DTD
Voici la liste des éléments à définir dans le fichier « plugin.xml » pour pouvoir mettre
en place un plugin associée à une DTD.
2.3.1.1. Dtd-plugin
C’est l'élément supérieur dans un fichier « plugin.xml » pour un plugin DTD. Il n'a
aucun attribut et tous les éléments suivants sont des fils de cet élément sauf
indication contraire.
Quand un fichier de ressource est indiqué (le fichier de DTD, par exemple), vous
devez indiquer un chemin relatif. Le répertoire de base de ce chemin sera le
répertoire racine du plugin.
Ainsi, par exemple, l'entrée suivante :
<file>dtd/gendiapo.dtd <file>
serait trouvé dans [merlot-directory]/plugins/vxml/dtd/gendiapo.dtd pendant le
développement, et comme entrée dans [merlot-directory]/plugins/gendiapo.jar une
fois le plugin déployé.
2.3.1.2. Name
Cet élément vous permet d'indiquer un nom court pour votre plugin. Ceci apparaîtra
comme élément de menu sous l’élément de menu « Help, about plugins »
<name>GenDiapo</name>
2.3.1.3. LongName
Cet élément vous permet d'indiquer un long nom pour votre plugin.
<longname>Gendiapo XML plugin pour Merlot</longname>
2.3.1.4. Version
L'élément de version vous permet d'indiquer un numéro de version pour votre plugin.
<version>1.0 </version>
2.3.1.5. Author
Cet élément permet de décrire l'auteur du plugin.
<author>Equipe GenDiapo</author>
Projet GenDiapo
16 / 31
CLIPS / SYNERGIE3R
2.3.1.6. Url
Cet élément vous permet d'indiquer une URL où les utilisateurs peuvent en découvrir
plus au sujet de votre plugin.
REMARQUE
L’url doit obligatoirement commencer par la chaîne « http:// »
<url>http://gendiapo.free.fr</url>
2.3.1.7. Dtd
Cet élément vous permet d'indiquer la DTD associée à votre plugin. Il contient
plusieurs sous éléments.

File : Chemin du fichier réel de DTD.
<file>dtd/gendiapo.dtd</file>

Doctype : Type de document utilisé avec ce plugin. GenDiapo utilisera ceci
comme élément de racine du document XML.
<doctype>gendiapo</doctype>

publicID : Identification publique incluse dans la déclaration de doctype.
<publicID>-//GenDiapoXMLForum//GenDiapo XML1.0//EN</publicID>

systemID : Système identification inclus dans la déclaration de doctype.
<systemID>http://www.voicexml.org/dtd/vxml1.0.dtd</systemID>
2.3.1.8. Editor
Cet élément définit une classe individuelle d'éditeur et les éléments édités. Elle a
deux sous éléments.

Class :
Nom
complet
de
la
classe
d'org.merlotxml.merlot.MerlotDOMEditor.
implémentant
l'interface
<class>org.merlotxml.merlot.plugins.vxml.AudioEditor</class>
REMARQUE

Les attributs personnalisés doivent mettre en application l’interface
MerlotDOMEditor. Vous pouvez également étendre GenericDOMEditor
et/ou GenericDOMEditPanel si vous ne voulez pas appliquer toutes les
méthodes définies par cette interface.
Element : Elément pour lequel que cet éditeur sera employé. Des éléments
multiples peuvent être indiqués pour un éditeur simple.
<element>paragraph</element>
Projet GenDiapo
17 / 31
CLIPS / SYNERGIE3R
2.3.1.9. Icon
Cet élément définit une icône personnalisée devant apparaître pour un ou plusieurs
éléments.
L'attribut source indique le chemin de l’image (typiquement un GIF 32x32). L'attribut
smallSource indique le chemin de la petite version de l'image (typiquement un GIF
16x16).

Element : Elément pour lequel les images seront utilisées. Des éléments
multiples peuvent être indiqués pour une image simple.
<icon source="icons/para.gif" smallSource="icons/para_s.gif">
<element>paragraph</element>
</icon>
Ce fichier sera placé à un endroit très précis dans le répertoire du plugin et
contiendra les informations suivantes
2.3.2.
Utilisation du squelette
Pour faciliter la mise en place de ce plugin, nous vous donnons avec ce manuel un
squelette de répertoires et de classes Java (disponible sur le site cité à la première
page). Ce squelette est en fait un exemple du plugin pour une DTD simple.
Les tâches répétitives de compilation, mise sous forme de jar et intégration dans
l’éditeur, sont automatisées grâce au fichier build.xml.
Pour pouvoir utiliser ce fichier, l’utilitaire < ant > est requis (téléchargement sur
http://jakarta.apache.org/ant/). Une fois installé, les différents objectifs possibles avec
cet utilitaire sont les suivants :
Objectifs
all
install
Description
Objectifs par défaut si rien précisé (équivalent à « install »)
Crée le jar si besoin et l’intègre dans l’éditeur
install-nojar Compile si besoin le plugin et l’install sous forme non compressé dans
le répertoire plugins de GenDiapo
jar
Compile si besoin le plugin et crée le jar à partir du répertoire build
compile
Compile les classes java dans build et copie le fichier plugin.xml, ainsi
que les gif, jpg, xml et xsl
clean
Efface tous les fichiers pouvant être recrés, c’est à dire le jar et le
répertoire build.
Projet GenDiapo
18 / 31
CLIPS / SYNERGIE3R
Pour pouvoir appliquer un de ces objectifs, il faut saisir la ligne de commande
suivante : ant « nom objectif ».
Exemple : ant install
Compile le plugin, puis créer le jar, et le copie dans le répertoire de
l’éditeur. Cette commande est équivalente à < ant >
REMARQUE
Projet GenDiapo
L’intégration du plugin dans l’éditeur correspond à la copie du fichier jar
généré dans le répertoire de l’éditeur
19 / 31
CLIPS / SYNERGIE3R
L’arborescence du squelette est la suivante (le texte en italique indique les
modifications à effectuer pour créer votre propre plugin) :
raçine
build.xml
build
src
plugin.xml
dtd
META-INF
MANIFEST.MF
classes
org
merlotxml
merlot
plugins
dtd
exampledtd
ExampleDTD.java
atttributes
styledview
PluginViewFactory.java
Projet GenDiapo
20 / 31
CLIPS / SYNERGIE3R
Le détail de chaque fichier et répertoire :
build.xml
Fichier permettant la compilation et l’intégration du plugin
 Les 3 lignes concernant pluginName, gendiapo.dir, gendiapo.jar sont à modifier
build/
Répertoire contenant l’arborescence du plugin compilé, prêt à être mis sous
forme de jar. Ce répertoire est créé et géré par ant
src/
Répertoire contenant le source du plugin
src/plugin.xml
Information sur le plugin
 A modifier selon le chapitre précédent
src/dtd
DTD
 Incluez vos DTD
src/META-INF/MANIFEST.MF
Méta information (fichier vide) pour le JAR
src/classes
Source des classes pour le fichier JAR
src/classes/org/merlotxml/merlot/plugins/dtd/exampledtd/ExampleDTD.java
étend GenericGenDiapoEditor.
Classe référencée par plugin.xml
 Ajouter autant de GenericGenDiapoEditor que nécessaire
src/classes/org/merlotxml/merlot/plugins/dtd/exampledtd/attributes
Répertoire contenant les classes associées aux panneaux des attributs.
Ces classes héritent toutes de GenericGenDiapoEditPanel
 Ajouter autant de GenericGenDiapoEditPanel que nécessaire
src/classes/org/merlotxml/merlot/plugins/dtd/exampledtd/styledview
Répertoire contenant les classes associées à la vue stylée
 Créer autant de View que nécessaire dans ce répertoire. Elles seront créées par
la ou les ViewFactory
src/classes/org/merlotxml/merlot/plugins/dtd/exampledtd/styledview/PluginViewFactory.java
ViewFactory associée à ExampleDTD
 Créér autant de ViewFactory dans ce répertoire. Une ViewFactory peut être
référencée par plusieurs GenericGenDiapoEditor
Projet GenDiapo
21 / 31
CLIPS / SYNERGIE3R
3. Plugin Action
Les différentes parties ci-dessous vont vous permettre de réaliser un plugin Action
pour l’outil auteur GenDiapo.
3.1. Présentation
Le plugin Action vous permet d’ajouter des actions spécifiques à l’outil auteur
GenDiapo, actions qui pourront être effectuées sur les documents en cours d’édition.
Ces actions pourront être adaptables à tous les documents éditables avec l’outil
auteur ou seulement destinés à un type de document (à un type de DTD).
Par exemple, ce plugin pourra permettre la mise en place d’un nouveau traitement de
publication (publication PDF) pour les documents GenDiapo.
3.2. Description
Après avoir décrit les actions possibles avec ce plugin, nous donnerons une brève
description des classes et méthodes à implémenter ou surcharger.
3.2.1.
Actions possibles
Une seule action est possible pour ce plugin : son lancement.
3.2.2.
Détail des classes
3.2.2.1. Interface org.merlotxml.merlot.plugin.Action
Pour mettre en place le plugin Action, il suffit de créer une classe qui implémente
l’interface org.merlotxml.merlot.plugin.action.Action :

public void init (Node config)
Cette méthode est appelée lors du chargement du plugin. Le paramètre config
correspond à la balise config dans le fichier de configuration (cf. le paragraphe
3.3.1).
Les différentes valeurs peuvent être extraites soit en parcourant les Nodes
avec les classes de org.w3c.dom (http://java.sun.com/xml/jaxp1.0.1/docs/api/org/w3c/dom/package-summary.html ), soit par la classes
fournis par Merlot : org.merlotxml.util.xml.XPathUtil (cf. le paragraphe 3.2.2.3)

public void performAction(Document doc)
Projet GenDiapo
22 / 31
CLIPS / SYNERGIE3R
Cette méthode sera déclenchée à chaque clic sur le menu associé au plugin.
Le document est décrit pour la classe org.w3c.dom.Document
(http://java.sun.com/xml/jaxp-1.0.1/docs/api/org/w3c/dom/packagesummary.html ).
REMARQUE
D’autres outils peuvent normalement utiliser directement ce document
DOM, cependant il est conseillé de faire re-interprété votre document. En
effet, il existe apparemment des incompatibilités entre les différents
package utilisant le DOM. Pour ce faire, utiliser le code suivant :
import org.xml.sax.InputSource;
import org.w3c.dom.*;
...
StringWriter strOut = new StringWriter();
DOMLiaisonFactory.getDOMLiaison().print(doc, strOut, "", false);
new InputSource(new StringReader(strOut.toString()))
3.2.2.2. Classe org.merlotxml.util.xml.XpathUtil

public static String parseVariable( Node contextNode, String xPathString )
Trouve le premier nom de variable contenu dans xPathString.
Elle retourne null s’il n’y a aucune variable et le symbole $ n’est pas inclus.
Par exemple pour xPathString "//myelement[attribute::id=$myvariable]", la
valeur retournée est "myvariable".

public static NodeList selectNodes(Node contextNode, String str)
Retourne une liste de noeud correspondant aux critères donnés par le XPath
str relatif au nœud contextNode.
Elle retourne null si aucun nœud n’est trouvé.

public static Node selectSingleNode(Node contextNode, String str)
Retourne le premier élément de la liste renvoyée par
selectNodes(contextNode, str). Il correspond au premier nœud correspondant
au XPath relatif au nœud contextNode

public static List getValueList(Node contextNode, String xpath) throws
SAXException
Renvoie une liste de String correspondant au chemin XPath xpath relatif au
nœud contextNode

public static String getValue(Node contextNode, String str) throws
SAXException
Renvoie la valeur textuelle du premier nœud correspondant au chemin XPath
str relatif au nœud contextNode
Projet GenDiapo
23 / 31
CLIPS / SYNERGIE3R
3.2.2.3. Classe org.gendiapo.publisher.Publisher

public Publisher(String base, int steps)
Constructeur de la classe.
La chaîne de caractères base indique le chemin ou se situe les fichiers xsl.
L’entier steps indique le nombre de transformation qui vont être appliqué.
Son but est de pouvoir donner à l’utilisateur, l’état d’avancement du processus
de publication.

public void setParameter(String key, Object value)
Définit un paramètre qui sera visible dans les fichiers xsl

public Object getParameter(String key)
Lit la valeur d’un paramètre.

public boolean applyXslt(Source src, Source xsl, Result dest)
Applique un fichier xslt xsl à la source src, et stocke le résultat dans dest.
Source et Result sont des classes du package org.xml.sax

public boolean applyXslt(InputStream streamSrc, String fileXsl, OutputStream
streamDest)
Applique au flux streamSrc le fichier xslt fileXsl et stocke le résultat dans le
flux streamDest

public boolean applyXslt(InputStream streamSrc, String fileXsl, String fileDest)
Applique au flux streamSrc le fichier xslt fileXsl, et stock le résultat dans le
fichier fileDest

public boolean applyXslt(String fileSrc, String fileXsl, String fileDest)
Applique au fichier fileSrc le fichier fileXsl et stocke le résultat dans le fichier
fileDest.

public void applyXslfo(InputStream streamSrc, String document)
Transforme le xslfo donné par le flux streamSrc en fichier pdf dont le nom est
document

public
void
applyXslfo(String
fileSrc,
String
document)
throws
FileNotFoundException
Transforme le xslfo donné par le fichier fileSrc en fichier pdf dont le nom est
document
3.3. Construction & Intégration
Après avoir vu comment créer les différentes méthodes et classes du plugin Action,
la dernière étape consiste en la construction du plugin sous la forme d’un jar et de
son intégration dans GenDiapo.
Projet GenDiapo
24 / 31
CLIPS / SYNERGIE3R
L’arborescence utilisée pour créer ce type de jar est la même que celle utilisée pour
le plugin DTD :

plugin.xml

classes/

META-INF/MANIFEST.MF
L’intégration du plugin dans GenDiapo se fait en plaçant le jar dans le répertoire
[directory]/plugins, [directory] étant le répertoire ou se situe le fichier jar de GenDiapo
3.3.1.
Paramètres d’un plugin Action
Un plugin Action vous permet de personnaliser des actions à l’aide d’un fichier
« plugin.xml » qui contient les éléments suivants.
REMARQUE
Le nom, le nom long, la version, l'auteur, et les éléments de URL dans le
fichier « plugin.xml » sont identiques à ceux du plugin DTD.
3.3.1.1. Action
Cet élément indique une action simple. Un fichier « plugin.xml » peut contenir des
actions multiples.

Menu : Nom apparaissant dans le menu Plugins pour cette action.
<menu>XSL GenDiapo</menu>

Class :
Nom
complet
de
la
classe
d'org.merlotxml.merlot.plugin.action.Action.
implémentant
l'interface
<class>org.merlotxml.merlot.plugins.action.xslt.Plugin</class>

Icon : Chemin d’accès à un icône apparaissant dans le menu « Plugins » à
côté du texte indiqué dans l'élément « menu » (typiquement un GIF 16x16).

Tooltip : Message apparaissant au-dessus de l'élément de menu dans le
menu Plugins.

Config : Stockage des informations de configuration spécifiques à votre plugin.
Les balises peuvent êtres comme vous le souhaitez. La structure pourra être
lu depuis le plugin
Projet GenDiapo
25 / 31
CLIPS / SYNERGIE3R
3.3.2.
Utilisation du squelette
Pour faciliter la mise en place de ce plugin, nous vous fournissons avec ce manuel
un squelette de répertoires et de classes Java. Ce squelette est en fait un exemple
simple.
Pour mettre le plugin sous la forme d’un jar, l’utilitaire < ant > doit être utilisé : son
fonctionnement est expliqué au paragraphe au 2.3.2.
L’arborescence est la suivante (le texte en italique indique les modifications à
effectuée pour créer votre propre plugin) :
raçine
build.xml
build
src
plugin.xml
META-INF
MANIFEST.MF
classes
org
merlotxml
merlot
plugins
action
Apply.java
Projet GenDiapo
26 / 31
CLIPS / SYNERGIE3R
Le détail de chaque fichier et répertoire:
build.xml
Fichier permettant la compilation et l’intégration du plugin
 Les 3 lignes concernant pluginName, gendiapo.dir, gendiapo.jar sont à
modifier
build/
Répertoire contenant l’arborescence du plugin compilé non compressée
src/
Répertoire contenant le source du plugin
src/plugin.xml
Information sur le plugin
 A modifier selon le chapitre précédent
src/META-INF/MANIFEST.MF
Méta information (fichier vide) pour le JAR
src/classes
Source des classes pour le fichier JAR
src/classes/org/merlotxml/merlot/plugins/action/Apply.java
étend Action Classe referencé par plugin.xml
 Ajouter autant de Action que nécessaire
Projet GenDiapo
27 / 31
CLIPS / SYNERGIE3R
Glossaire
Ant
Logiciel permettant de faire les tâches répétitives sur le
code d’un projet tel que la compilation, la génération de la
documentation. L’ensemble des tâches (appelé target)
sont décrites dans un fichier « build.xml »
Arbre
Partie visuelle, à gauche de l’éditeur, représentant le
document sous forme d’arbre : Chaque nœud visuel étant
un nœud du document XML
DOM
Document Object Model, normalisé par le W3C, est une
interface permettant d’accéder (en écriture et lecture) au
contenu de document XML. L’implémentation en java se
situe dans le package org.w3c.dom
Elément
Portion du document de la vue stylée correspondant à un
nœud XML, attribut XML, PCData, paragraphe de PCData
ou ligne de paragraphe
Panneau des attributs
Partie visuelle, en bas à droite de l’éditeur, représentant
les attributs non présents dans la vue stylée pour le nœud
sélectionné
Plugin Action
Plugin permettant d’ajouter des actions spécifiques à
l’outil auteur GenDiapo, actions pouvant être effectuées
sur les documents en cours d’édition.
Ces actions pourront être adaptables à tous les
documents éditables avec l’outil auteur ou seulement
destinés à un type de document (à un type de DTD).
Plugin DTD
Plugin permettant de personnaliser l’outil auteur
GenDiapo pour un type de DTD bien précis.
Deux types de fonctionnalités offertes : filtrage et
modification d’affichage
View
Classe Java dont le but est la représentation d’ un
élément à l’utilisateur
Vue stylée
Partie visuelle, en haut à droite de l’éditeur, représentant
le document XML avec des éléments
Projet GenDiapo
28 / 31
CLIPS / SYNERGIE3R
Annexe
DTD des Plugins
Nous allons donner la DTD associée à chaque fichier « plugin.xml » en fonction du
type de plugin.
DTD du Plugin DTD
<!ELEMENT dtd-plugin (name, longName?, version?, author?, url?, (dtd | editor | icon)*>
<!ELEMENT name (#PCDATA)>
<!ELEMENT longName (#PCDATA)>
<!ELEMENT version (#PCDATA)>
<!ELEMENT author (#PCDATA)>
<!ELEMENT url (#PCDATA)>
<!ELEMENT dtd (file, doctype, publicID, systemID)>
<!ELEMENT file (#PCDATA)>
<!ELEMENT doctype (#PCDATA)>
<!ELEMENT publicID (#PCDATA)>
<!ELEMENT systemID (#PCDATA)>
<!ELEMENT editor (class, element*)>
<!ELEMENT class (#PCDATA)>
<!ELEMENT element (#PCDATA)>
<!ELEMENT icon (element*)>
<!ATTLIST icon source CDATA #REQUIRED
smallSource CDATA #REQUIRED>
Projet GenDiapo
29 / 31
CLIPS / SYNERGIE3R
DTD du Plugin Action
<!ELEMENT action-plugin (name, longName?, version?, author?, url?, action*)>
<!ELEMENT name (#PCDATA)>
<!ELEMENT longName (#PCDATA)>
<!ELEMENT version (#PCDATA)>
<!ELEMENT author (#PCDATA)>
<!ELEMENT url (#PCDATA)>
<!ELEMENT action (menu, class, icon?, tooltip?, config?)>
<!ELEMENT menu (#PCDATA)>
<!ELEMENT class (#PCDATA)>
<!ELEMENT icon (#PCDATA)>
<!ELEMENT tooltip (#PCDATA)>
<!ELEMENT config (configitem*)>
<!ELEMENT configitem (#PCDATA)>
<!ATTLIST configitem name CDATA #REQUIRED>
URL utiles
Ant

http://jakarta.apache.org/ant/
DOM
(Document Object Model) - Package
org.w3c.dom


http://java.sun.com/xml/jaxp-1.0.1/docs/api/org/w3c/dom/packagesummary.html
http://www.w3.org/DOM/
Projet GenDiapo
30 / 31
CLIPS / SYNERGIE3R
Package javax.swing.text



http://java.sun.com/j2se/1.3/docs/api/javax/swing/text/package-summary.html
http://java.sun.com/j2se/1.3/docs/api/javax/swing/text/Document.html
http://java.sun.com/j2se/1.3/docs/api/javax/swing/text/View.html
Merlot Plugin development guide

http://www.merlotxml.org/docs/plugins/plugin-dev-guide.html
Projet GenDiapo
31 / 31
CLIPS / SYNERGIE3R