Apprendre à installer et utiliser les modules complémentaires ONLYOFFICE

Pour réagir au contenu de cet article, un espace de dialogue vous est proposé sur le forum. Commentez

Article lu fois.

L'auteur

ONLYOFFICE

L'article

Publié le 22 février 2021

Version PDF Version hors-ligne

ePub, Azw et Mobi

Liens sociaux

I. Introduction▲

La suite bureautique ONLYOFFICE fournit un traitement de texte, un tableur et un outil de présentation qui sont disponibles sous des formes différentes : en tant qu'applications de bureau ONLYOFFICE (dont les traits majeurs et les options d’installation sont listés dans cet article) ou en tant qu'éditeurs en ligne ONLYOFFICE Docs déployés en autohébergement (dont les fonctionnalités les plus récentes sont présentées dans cet article).

Outre les outils d’édition et coédition qui constituent un éventail fonctionnel de la suite, Ascencio System SIA fournit une collection de modules complémentaires qui étendent les fonctionnalités des éditeurs en offrant aux utilisateurs des possibilités supplémentaires telles que traduction, parole, table de symboles, ajout de vidéos YouTube, insertion des fichiers audio et vidéo dans les présentations, etc. La collection des plugins vient de s’enrichir de nouveaux outils :

Telegram : permet de communiquer avec vos coauteurs sans quitter l’interface de l’éditeur ;
HTML : sert à importer le contenu du document sous forme d’un code ;
Compteur des mots : pour savoir le nombre des mots, des caractères avec ou sans espacement, des paragraphes dans une partie d’un fichier ou d'un document entier ;
Google Translate : traduit le texte vers une langue sélectionnée ;
Typograf : aide à éliminer les fautes d’orthographe et corriger la mise en forme.

Dans cet article, nous allons apprendre à créer vos propres modules complémentaires à base des API ONLYOFFICE, les installer et les utiliser au sein des éditeurs.

II. Écrire le code d’un module complémentaire▲

Le module complémentaire pour les éditeurs ONLYOFFICE représente un dossier contenant trois fichiers au minimum :

config.json - le fichier de configuration du module complémentaire ;
index.html - le point de départ du module complémentaire ;
pluginCode.js - le code du module complémentaire.

Ce dossier peut aussi contenir les fichiers supplémentaires tels que les icônes pour les modules qui ne se lancent pas automatiquement avec le démarrage des éditeurs ou le fichier index_about.html contenant les informations légales sur le module.

Le tout premier pas est de créer un nouveau dossier en lui attribuant un nom unique pour éviter toute confusion avec d’autres modules.

Ensuite il est indispensable de créer le fichier .js qui décrit le fonctionnement de votre module complémentaire.

Tout module possède un objet window.Asc.plugin qui utilise plusieurs méthodes pour interagir avec les éditeurs ONLYOFFICE. Afin de le rendre opérationnel, spécifiez deux méthodes pour window.Asc.plugin : window.Asc.plugin.init et window.Asc.plugin.button.

Pour envoyer les données aux éditeurs, nous utilisons l’API préinstallée de ONLYOFFICE Document Builder pour window.Asc.plugin.callCommand.

Voyons la structure du code de plus près en prenant pour l’exemple le module complémentaire « Hello world! » :

Sélectionnez

1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.

(function (window, undefined) {

    window.Asc.plugin.init = function () {

        this.callCommand(function() {

            var oDocument = Api.GetDocument();

            var oParagraph = Api.CreateParagraph();

            oParagraph.AddText("Hello world!");

            oDocument.InsertContent([oParagraph]);

        }, true);

    };

})(window, undefined);

Ce code va générer un paragraphe avec le texte « Hello world! » et ensuite créer un document contenant ce texte grâce à l’API de ONLYOFFICE Document Builder.

III. Créer le fichier HTML principal du module complémentaire▲

Chaque module complémentaire fonctionne grâce à son propre élément iframe. L’éditeur se connecte au fichier index.html spécifié dans le fichier de configuration config.json.

Voyons de plus près la structure du fichier HTML d’un module complémentaire simple :

Sélectionnez

1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.

<!DOCTYPE html>

 <html>

 <head>

     <meta charset="UTF-8" />

     <title>Hello world</title>

     <script type="text/javascript" src="../pluginBase.js"></script>

     <script type="text/javascript" src="helloworld.js"></script>

 </head>

 <body>

 </body>

 </html>

Dans la section <head>...</head>, spécifiez le nom du module complémentaire et les liens vers tous les scripts et les feuilles de style nécessaires afin d’assurer le fonctionnement correct du plugin.

En outre, ajoutez le lien vers le fichier pluginBase.js qui contient la méthode de base du plugin.

La section <div>...</div> peut contenir les composants du module complémentaire dont le comportement est décrit dans le code pluginCode.js.

IV. Créer le fichier de configuration du module complémentaire▲

À cette étape, il est indispensable de créer le fichier config.json incluant les informations qui sont indispensables pour enregistrer le module complémentaire dans les éditeurs.

Indiquez les informations du plugin : le nom, l’identifiant/guid et l’adresse URL.

Sélectionnez

1.
2.
3.
4.
5.
6.
7.

{

     "name"       : "hello world",

     "guid"       : "asc.{0616AE85-5DBE-4B6B-A0A9-455C4F1503AD}",

     "baseUrl"    : "",

Le nom du module complémentaire va s’afficher dans l’onglet « Modules complémentaires » situé dans la barre de menu en haut du document.

Spécifiez les paramètres suivants du plugin :

"description" - la description de l’outil ;
"url" - le lien vers le fichier HTML principal ;
"icons" - les liens vers les icônes qui vont s’afficher dans le menu (au moins deux icônes - pour les écrans rétine et pour tous les autres écrans).

Comme le module complémentaire sert à insérer le texte dans le document, il doit être actif en mode édition seulement : marquez le paramètre "isViewer" comme false. Si vous souhaitez qu’il soit disponible aussi en mode affichage, marquez ce paramètre comme true.

Définissez les éditeurs ("EditorsSupport") dans lesquels votre module sera présent - "word" (traitement de texte) , "cell" (tableur), ou "slide" (outil de présentation).

Pour les modules non visuels qui fournissent un seul bouton pour apporter les modifications au document, marquez le paramètre "isVisual" comme false. Si le plugin que vous créez est visuel, vous avez besoin de spécifier deux paramètres de plus :

Sélectionnez

"isModal"             : true,
"isInsideMode"        : false,

Le premier est conçu pour spécifier si le plugin va s’ouvrir dans une fenêtre séparée. Si vous voulez qu’il s’ouvre dans le menu de l’éditeur, marquez le deuxième - "isInsideMode" - comme true.

Voyons de plus près la configuration du module complémentaire :

Sélectionnez

1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.
24.
25.
26.
27.
28.
29.
30.
31.

{

     "name"       : "hello world",

     "guid"       : "asc.{0616AE85-5DBE-4B6B-A0A9-455C4F1503AD}",

     "baseUrl"    : "",

     "variations" : [

         {

             "description"         : "hello world",

             "url"                 : "index.html",

             "icons"               : ["icon.png", "icon@2x.png"],


             "isViewer"            : false,

             "EditorsSupport"      : ["word"],

             "isVisual"            : false,


         }

     ]

 }

Pour plus de paramètres, consultez la documentation sur l’API ONLYOFFICE.

V. Localiser le module complémentaire▲

Ajoutez le paramètre "nameLocale" au fichier de configuration config.json file pour traduire le nom du service :

Sélectionnez

1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.
24.
25.
26.
27.
28.

{

     "name": "Hello world",

     "nameLocale": {

         "fr": "Bonjour le monde !",

         "de": "Hallo Welt"

     },
And "descriptionLocale" for plugin description:

"variations": [

         {

             "description": "Hello world",

             "descriptionLocale": {

                 "fr": "Bonjour le monde",

                 "de": "Hallo Welt"

             },

             "url": "index.html",

VI. Créer une page avec le descriptif du module complémentaire▲

Pour créer une page avec toutes les informations à propos du module complémentaire, créez un fichier HTML contenant tous les détails et modifiez le fichier de configuration du plugin.

Les informations seront affichées dans une nouvelle fenêtre séparée après un clic sur le bouton « OK ». Vous pouvez aussi définir la taille de la fenêtre en pixels.

Sélectionnez

1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.
24.
25.
26.
27.
28.
29.
30.
31.
32.
33.

{

             "description"         : "About",

             "url"                 : "index_about.html",

             "icons"               : ["icon.png", "icon@2x.png"],

             "isViewer"            : false,

             "EditorsSupport"      : ["word"],

             "isVisual"            : true,

             "isModal"             : true,

             "buttons"         : [

                 {

                     "text": "Ok",

                     "primary": true

                 }

             ],



             "size" : [392, 147]

         }

Finalement, le fichier de config.json va se composer comme suit :

Sélectionnez

1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.
24.
25.
26.
27.
28.
29.
30.
31.
32.
33.
34.
35.
36.
37.
38.
39.
40.
41.
42.
43.
44.
45.
46.
47.
48.
49.
50.
51.
52.
53.
54.
55.
56.
57.
58.
59.
60.
61.
62.
63.
64.
65.
66.
67.
68.
69.
70.
71.
72.
73.
74.
75.
76.
77.
78.
79.
80.

{

     "name": "Hello world",

     "nameLocale": {

         "fr": "Bonjour le monde !",

         "de": "Hallo Welt"

 },

     "guid"       : "asc.{0616AE85-5DBE-4B6B-A0A9-455C4F1503AD}",

     "baseUrl"    : "",

     "variations": [

         {

             "description": "Hello world",

             "descriptionLocale": {

                 "fr": "Bonjour le monde",

                 "de": "Hallo Welt"

             },

             "url": "index.html",

             "icons"               : ["icon.png", "icon@2x.png"],

             "isViewer"            : false,

             "EditorsSupport"      : ["word"],

             "isVisual"            : false,


         },

         {

             "description"         : "About",

             "url"                 : "index_about.html",

             "icons"               : ["icon.png", "icon@2x.png"],

             "isViewer"            : false,

             "EditorsSupport"      : ["word"],

             "isVisual"            : true,

             "isModal"             : true,

             "buttons"         : [

                 {

                     "text": "Ok",

                     "primary": true

                 }

             ],



             "size" : [392, 147]

         }

     ]

 }

VII. Installer les modules complémentaires à ONLYOFFICE▲

Après avoir créé le module complémentaire, vous pouvez l’ajouter manuellement à ONLYOFFICE Docs et aux applications de bureau ONLYOFFICE.

Il existe deux moyens de le faire :

VII-A. Pour les solutions autohébergées▲

Placez le dossier avec le code du module complémentaire dans le dossier de ONLYOFFICE Document Server :
Modifiez le fichier de configuration de ONLYOFFICE Document Server en y ajoutant les lignes suivantes :

pour Linux – /var/www/onlyoffice/documentserver/sdkjs-plugins/ ;
pour Windows – %ProgramFiles%\ONLYOFFICE\DocumentServer\sdkjs-plugins\.

Sélectionnez

1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.

var docEditor = new DocsAPI.DocEditor("placeholder", {
    "editorConfig": {
        "plugins": {
            "autostart": [
                "asc.{0616AE85-5DBE-4B6B-A0A9-455C4F1503AD}",
                "asc.{FFE1F462-1EA2-4391-990D-4CC84940B754}",
                ...
            ],
            "pluginsData": [
                "https://example.com/plugin1/config.json",
                "https://example.com/plugin2/config.json",
                ...
            ]
        },
        ...
    },
    ...
});

example.com est le nom du serveur sur lequel le gestionnaire des documents et le service du stockage sont installés et où les modules complémentaires sont placés. Pour en savoir plus sur les configurations, lisez la documentation sur les API de Document Server.

VII-B. Pour les applications de bureau▲

Archivez tous les fichiers et dossiers des modules complémentaires.

Modifiez l’extension du fichier : .plugin.

Passez à l’onglet « Modules complémentaires », cliquez sur « Paramètres », sélectionnez l’option « Ajouter plugin » et chargez votre fichier .plugin.