View source for FR/Documentation/How Tos/Installation/CreerExtension

'''Comment créer une extension''' - ''Application à la création d'un thème pour la Gallery''
__NOTOC__
== Préambule ==
Une extension permet d'ajouter des fonctionnalités à {{OOo}}. Parmi les extensions les plus téléchargées, citons&nbsp;: 
*les dictionnaires d'orthographe, de grammaire, de synonymes ou de césure 
*l'import ou l'export de fichiers dans d'autres formats&nbsp;: PDF, SVG 
*l'ajout de thèmes pour la Galerie (Gallery)
Vous trouverez sur le [https://forum.openoffice.org/fr/forum/viewforum.php?f=18 Forum francophone], une liste de ces OXT recommandés par la Communauté.

Quelle que soit le type d'extension que l'on souhaite construire les étapes à suivre sont les mêmes&nbsp;: 
#rassemblement des fichiers dans un répertoire 
#configuration des fichiers de description 
#construction de l'extension 
#diffusion de l'extension
== Étapes à suivre  ==
Nous allons présenter ici la construction d'une extension pour ajouter des images dans la Gallery. Un exemple minimaliste (sans image) est disponible [[Non-code_extensions_FR#Packages_du_Gallery|ici]].

=== Préparation des images ===
Pour diffuser des images que l'on veut utiliser régulièrement dans OOo, la solution la plus simple consiste à construire une extension qui va ajouter un ou plusieurs thèmes à la Gallery contenant ces images. Ces images peuvent être suivant différents formats :
* image par points issue d'un fichier PNG, JPEG, GIF, BMP, TIFF, etc.
* image vectorielle construite avec des objets de dessin de Draw : rectangles, ellipses, segments,...
Il faut donc rassembler les images dans un thème :
* affichez la Gallery par le menu '''Outils''' > '''Gallery'''
* cliquez sur le bouton '''Nouveau thème'''
* renseignez le nom et notez l'emplacement (ce sera nécessaire pour retrouver le fichier)
* validez par '''OK'''
Vous avez maintenant un nouveau thème qui est vide. Ajoutez les images que vous souhaitez y mettre. Pour les fichiers images par points, il n'est pas conseillé d'utiliser la méthode d'ajout direct dans le thème :
* clic droit sur le nom du thème > '''Propriétés''', onglet '''Fichiers''',
* bouton '''Recherche de fichiers''' pour parcourir le disque
* bouton '''Ajouter'''
En effet, par cette méthode, seul un lien est ajouté dans le thème, et cela compliquera l'insertion dans l'extension. Il vaut donc mieux importer le fichier par le menu '''Insertion''' > '''Image''' > '''À partir d'un fichier''' dans un document ''Draw'' par exemple, puis d'ajouter l'image dans le thème comme pour une image vectorielle :
* ajustez le zoom et les ascenseurs pour visualiser l'ensemble de l'image à insérer
* cliquez de façon prolongée '''sans bouger''' sur l'image. Au bout de quelques secondes, l'image a été mise en mémoire par OOo : une légère modification de la bordure s'est opérée
* sans relâcher, faites glisser dans le thème. 
Si cette étape échoue (l'image est déplacée dans le dessin) il faut recommencer l'étape précédente : vous n'avez probablement pas attendu assez longtemps. Pour vérifier que toutes vos images sont bien dans le thème, cliquez sur chacune, et vous devriez voir un nom du type '''dd2954'''. Si un chemin apparait, c'est que l'image n'est pas réellement dans le thème, mais qu'il n'y a qu'un lien vers un fichier. Ceci compliquera grandement la construction de l'extension. Dans ce cas, il faut faire glisser l'image à partir du thème vers un document ''Draw'', puis la réinsérer dans le thème comme précédemment.

Lorsque toutes les images souhaitées ont été insérées, vous avez la possibilité de leur donner un nom :
* clic droit sur l'image dans le thème > '''Titre'''
Ce titre est purement informatif pour l'utilisateur, il n'a pas besoin d'être unique.

Rendez-vous ensuite à l'emplacement repéré lors de la création du thème et récupérez les 3 fichiers constituant chaque thème : <code>sgxxxx.sdg</code>, <code>sgxxxx.sdv</code> et <code>sgxxxx.thm</code>. <code>xxxx</code> étant le numéro du thème. Ce numéro a besoin d'être unique '''dans un même répertoire'''. Comme l'extension va créer ses propres répertoires, il n'est pas nécessaire que le numéro soit unique pour tous les thèmes d'un utilisateur.
=== Construction des fichiers de configuration ===
Une extension pour OpenOffice est constitué d'un seul fichier avec l'extension '''.OXT'''. Comme tous les fichiers au format OpenDocument, il s'agit d'un fichier compressé ZIP et renommé en OXT. Pour construire une extension, le mieux est d'en récupérer une du même type que celle que l'on veut construire. 

Par exemple, pour ajouter un thème de Gallery, vous pouvez récupérer l'OXT d'OxygenOffice depuis le [http://extensions.openoffice.org/ site des extensions]. N'installez pas directement l'extension, mais enregistrez le fichier. Dézippez le fichier dans un nouveau répertoire (au besoin changez l'extension du fichier en .ZIP). Dans ce répertoire vous retrouvez tous les fichiers de configuration de l'extension. Il faut repérer ce qui est indispensable au fonctionnement et ce qui est ajouté par l'extension. 

==== Contenu minimum d'un OXT ====
Le minimum requis pour que l'OXT fonctionne est décrit ci-après.
===== répertoire <code>Gallery</code> =====
Ce répertoire contient les fichiers des thèmes. Il faut supprimer tout le contenu et le remplacer par nos fichiers <code>sgxxxx.sdg</code>, <code>sgxxxx.sdv</code> et <code>sgxxxx.thm</code>.

===== répertoire <code>META-INF</code> =====
Ce répertoire est présent dans toutes les extensions et est nécessaire pour l'installation de l'extension. Il contient le fichier <code>manifest.xml</code> qui déclare les fichiers de l'extension. ''A priori'' il n'est pas nécessaire de le modifier, sauf de corriger éventuellement les chemins.
 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE manifest:manifest PUBLIC "-//OpenOffice.org//DTD Manifest 1.0//EN" "Manifest.dtd">
 <manifest:manifest xmlns:manifest="http://openoffice.org/2001/manifest">
    <manifest:file-entry manifest:media-type="application/vnd.sun.star.configuration-data"
                         manifest:full-path ="Paths.xcu"/>
 </manifest:manifest>
Il s'agit donc de la déclaration du fichier <code>Paths.xcu</code> comme fichier de configuration. Pour que votre extension soit compatible avec tous les systèmes d'exploitation, attention au respect des majuscules/minuscules dans les noms de fichier.

===== répertoire <code>description</code> =====
Ce répertoire n'est pas obligatoire, mais il contient les fichiers texte de description de l'extension dans différentes langues. Ce texte est utilisé dans le gestionnaire d'extensions pour décrire l'extension. Si un fichier dans la langue de l'interface n'est pas présent, c'est le fichier en anglais qui utilisé. Vous pouvez aussi ne prévoir qu'un seul fichier de description !

===== répertoire <code>licenses</code> =====
Ce répertoire n'est pas obligatoire, mais il contient les fichiers texte des licences dans différentes langues. Si vous n'avez pas prévu de faire valider une licence au moment de l'installation de l'extension, ce répertoire n'est pas nécessaire. Cependant, il est recommandé de disposer d'un fichier texte au format UTF-8 donnant la licence d'utilisation de votre OXT (par exemple en intégrant l'une des licences suivantes : CeCILL, Apache, GNU-GPL, LGPL, PDL, etc).

===== Autres répertoires =====
D'autres répertoires peuvent exister, mais ne sont pas nécessaires au fonctionnement et à l'installation de l'extension.

===== Autres fichiers =====
Il y a également des fichiers présents à la racine de l'extension :
* n'importe quel fichier de description ou de licence. En effet, il n'est pas obligatoire de mettre ces fichiers dans des répertoires dédiés. C'est plus propre, c'est tout.
* fichier <code>description.xml</code> : ce fichier est très important, et nous allons le détailler juste après
* fichier <code>Paths.xcu</code> : ce fichier déclare le rôle de l'extension et comment l'installer. Ainsi pour une extension de Gallery :
 <?xml version='1.0' encoding='UTF-8'?>
 <oor:component-data oor:package="org.openoffice.Office" oor:name="Paths" 
  xmlns:install="http://openoffice.org/2004/installation" 
  xmlns:oor="http://openoffice.org/2001/registry" 
  xmlns:xs="http://www.w3.org/2001/XMLSchema"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
 	<node oor:name="Paths">
                 <node oor:name="Gallery" oor:op="fuse"> 
 			<node oor:name="InternalPaths">
                                 <node oor:name="%origin%/gallery" oor:op="fuse"/>
 			</node>
 		</node>
 	</node>
 </oor:component-data>
Il n'y a rien à changer dedans.
* un fichier image : il s'agit d'une image de 42x42 points au format PNG qui sera affichée dans le gestionnaire d'extensions du menu Outils.

==== Fichier <code>description.xml</code> ====
C'est ce fichier qui va contenir toutes l'information que vous voulez personnaliser. Il faut prendre soin de le remplir par rapport aux aspects spécifiques de son extension : noms des fichiers (! majuscule/minuscule), utilisation ou non d'une fonctionnalité...
La page du wiki (en anglais) http://wiki.services.openoffice.org/wiki/Documentation/DevGuide/Extensions/Example décrit les différents éléments le constituant. Nous allons revoir les éléments principaux.
===== Structure =====
Le fichier démarre par un entête :
 <?xml version="1.0" encoding="UTF-8"?>
 <description xmlns="http://openoffice.org/extensions/description/2006" xmlns:d="http://openoffice.org/extensions/description/2006"
     xmlns:xlink="http://www.w3.org/1999/xlink">
et doit se terminer par une balise de fin
 </description>
Entre les deux, il y a une série d'entrées du type :
 <'''mot clé''' value="'''valeur du mot clé'''" />
ou
 <'''mot clé'''>
    <'''sous entrée du mot clé'''>
 </'''mot clé'''>
Parmi les entrées, certaines sont obligatoires d'autres optionnelles.
===== Identifiant =====
Cet identifiant doit être unique dans le monde. C'est pourquoi il est recommandé d'utiliser une chaine de caractères en minuscules, dans l'ordre inverse de domaine. Par exemple :
  fr.mon_domaine.mon_nom.mon_extension
Ainsi utilisé dans <code>description.xml</code> :
 <identifier value="fr.mon_domaine.mon_nom.mon_extension" />
===== Numéro de version =====
Si vous souhaitez bénéficier du système de mise à jour automatique des extensions, il est important de renseigner cette rubrique. De manière usuelle, il y a 3 niveaux dans une numérotation de version : majeur, mineur, micro.
 <version value="1.0.2" />
Il ne faut pas confondre ce numéro de version, géré uniquement par le développeur de l'extension et le numéro de version d'OpenOffice.

===== Dépendances =====
Il faut indiquer le numéro de version d'OpenOffice à partir de laquelle l'extension est fonctionnelle.
  <dependencies>
         <OpenOffice.org-minimal-version value="4.0" d:name="OpenOffice.org 4.0"/>
  </dependencies>

===== Systèmes d'exploitations supportés =====
Si l'extension est indépendante des systèmes d'exploitation (ce qui est le cas pour un thème de Gallery), on le précise ainsi :
  <platform value="all" /> 
Sinon, on donne une liste :
  <platform value="windows_x86,solaris_sparc" />
Dans ce cas, OpenOffice refusera l'installation de l'OXT si le sysètme n'est pas autorisé.

===== Nom affiché =====
Le nom affiché dans le gestionnaire d'extension peut être personnalisé suivant la langue paramétrée dans OpenOffice. Il est déclaré ainsi :
   <display-name>
       <name lang="en">Gallery of danger signs</name>
       <name lang="fr">Gallery des symboles de dangers</name>
       <name lang="es">Galería de símbolos de peligro</name>
       <name lang="de">Gallery von Gefahrzeichen</name>
   </display-name>

===== Image affichée =====
L'image utilisée dans le gestionnaire d'extension est déclarée ainsi :
   <icon>
 	<default xlink:href="feu42.png" />
   </icon>
Attention à la localisation du fichier si vous l'avez mis dans un sous-répertoire, attention aux majuscules/minuscules. L'image doit avoir une taille de 42x42 maximum pour ne pas être déformée.

Vous pouvez également définir une autre image pour les interfaces définies en contraste élevé (déficients visuels) :
  <icon>
    <default xlink:href="images/icon.png" />
    <high-contrast xlink:href="images/icon_hc.png" />
  </icon>

===== Description =====
Le texte de description qui sera affiché dans le gestionnaire d'extensions, doit être enregistré dans un fichier (cf. plus haut) :
   <extension-description>
     <src xlink:href="description/description_en.txt" lang="en" />
     <src xlink:href="description/description_fr.txt" lang="fr" />
     <src xlink:href="description/description_es.txt" lang="es" />
     <src xlink:href="description/description_de.txt" lang="de" />
   </extension-description>
Ces fichiers de type TXT doivent néanmoins être enregistrés au format UTF-8 pour la conservation des accents.

===== Autres informations =====
D'autres rubriques sont disponibles mais ne sont pas indispensables :
* validation d'un licence :
  <registration>
    <simple-license accept-by="admin" suppress-on-update="true" >
      <license-text xlink:href="registration/license_de-DE.txt" lang="de-DE" />
      <license-text xlink:href="registration/license_en-GB.txt" lang="en-GB" />
      <license-text xlink:href="registration/license_en-NZ.txt" lang="en-NZ" />
      <license-text xlink:href="registration/license_en-US.txt" lang="en-US" />
    </simple-license>
  </registration>

Si le champ <code>accept-by</code> a été renseigné par <code>'''admin'''</code>, alors il sera possible d'installer l'extension pour tous les utilisateurs. Si on souhaite que chaque utilisateur valide la licence, le champ doit être renseigné avec le paramètre <code>'''user'''</code>.

=== Construction de l'extension ===
* Sélectionnez tous les fichiers et répertoires constituant votre extension et faites-en un fichier ZIP
* Changez l'extension du fichier ZIP en OXT
* C'est fait ! Votre extension est prête à être diffusée.
=== Diffusion de l'extension ===
Déposez votre extension sur le site officiel de partage des extensions : http://extensions.openoffice.org/ et informez en la Communauté en postant un message sur le [https://forum.openoffice.org/fr Forum francophone].

Ainsi tout le monde pourra bénéficier de votre extension.

N'oubliez que {{OOo}} doit être intégralement redémarré (démarrage rapide compris) pour que l'extension soit définitivement prise en compte.



{{PDL1}}
[[Category:FR/Documentation/Installation]].