Apprendre à installer et utiliser les modules complémentaires ONLYOFFICE

ONLYOFFICE

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

- Titre : Apprendre à installer et utiliser les modules complémentaires ONLYOFFICE

- Auteur : ONLYOFFICE

- Parution : 22 février 2021

- Licence : Copyright ® 2020 ONLYOFFICE . Aucune reproduction, même partielle, ne peut être faite de ce site et de l'ensemble de son contenu : textes, documents, images, etc. sans l'autorisation expresse de l'auteur. Sinon vous encourez selon la loi jusqu'à trois ans de prison et jusqu'à 300 000 € de dommages et intérêts.

Sommaire

- I. Introduction

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

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

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

- V. Localiser le module complémentaire

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

- VII. Installer les modules complémentaires à ONLYOFFICE

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

- VII-B. Pour les applications de bureau

- VIII. Activer et utiliser les nouveaux modules complémentaires

- VIII-A. Telegram

- VIII-B. HTML

- VIII-C. Compteur des mots

- VIII-D. Google Translate

- VIII-E. Typograf

- IX. Supprimer les modules complémentaires

- X. Remerciements Developpez.com

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! » :

1. (function (window, undefined) {

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

5. this.callCommand(function() {

7. var oDocument = Api.GetDocument();

9. var oParagraph = Api.CreateParagraph();

11. oParagraph.AddText("Hello world!");

13. oDocument.InsertContent([oParagraph]);

15. }, true);

17. };

19. })(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 :

1. <!DOCTYPE html>

3. <html>

5. <head>

7. <meta charset="UTF-8" />

9. <title>Hello world</title>

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

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

15. </head>

17. <body>

19. </body>

21. </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.

1. {

3. "name"       : "hello world",

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

7. "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 :

"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 :

1. {

3. "name"       : "hello world",

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

7. "baseUrl"    : "",

9. "variations" : [

11. {

13. "description"         : "hello world",

15. "url"                 : "index.html",

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

20. "isViewer"            : false,

22. "EditorsSupport"      : ["word"],

24. "isVisual"            : false,

27. }

29. ]

31. }

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 :

1. {

3. "name": "Hello world",

5. "nameLocale": {

7. "fr": "Bonjour le monde !",

9. "de": "Hallo Welt"

11. },

12. And "descriptionLocale" for plugin description:

14. "variations": [

16. {

18. "description": "Hello world",

20. "descriptionLocale": {

22. "fr": "Bonjour le monde",

24. "de": "Hallo Welt"

26. },

28. "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.

1. {

3. "description"         : "About",

5. "url"                 : "index_about.html",

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

9. "isViewer"            : false,

11. "EditorsSupport"      : ["word"],

13. "isVisual"            : true,

15. "isModal"             : true,

17. "buttons"         : [

19. {

21. "text": "Ok",

23. "primary": true

25. }

27. ],

31. "size" : [392, 147]

33. }

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

1. {

3. "name": "Hello world",

5. "nameLocale": {

7. "fr": "Bonjour le monde !",

9. "de": "Hallo Welt"

11. },

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

15. "baseUrl"    : "",

17. "variations": [

19. {

21. "description": "Hello world",

23. "descriptionLocale": {

25. "fr": "Bonjour le monde",

27. "de": "Hallo Welt"

29. },

31. "url": "index.html",

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

35. "isViewer"            : false,

37. "EditorsSupport"      : ["word"],

39. "isVisual"            : false,

42. },

44. {

46. "description"         : "About",

48. "url"                 : "index_about.html",

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

52. "isViewer"            : false,

54. "EditorsSupport"      : ["word"],

56. "isVisual"            : true,

58. "isModal"             : true,

60. "buttons"         : [

62. {

64. "text": "Ok",

66. "primary": true

68. }

70. ],

74. "size" : [392, 147]

76. }

78. ]

80. }

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

1. Placez le dossier avec le code du module complémentaire dans le dossier de ONLYOFFICE Document Server :

2. 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\.

1. var docEditor = new DocsAPI.DocEditor("placeholder", {

2. "editorConfig": {

3. "plugins": {

4. "autostart": [

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

6. "asc.{FFE1F462-1EA2-4391-990D-4CC84940B754}",

7. ...

8. ],

9. "pluginsData": [

10. "https://example.com/plugin1/config.json",

11. "https://example.com/plugin2/config.json",

12. ...

13. ]

14. },

15. ...

16. },

17. ...

18. });

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.

VIII - Activer et utiliser les nouveaux modules complémentaires

VIII-A - Telegram

1. Passez à l’onglet « Modules complémentaires » et sélectionnez Telegram.

2. Connectez-vous à Telegram en utilisant le numéro de téléphone ou le code QR.

3. Vous resterez connecté par défaut. Si vous souhaitez choisir un autre compte, veuillez ne pas cocher la case « Garder ma session ouverte ».

4. La liste de vos échanges va apparaître dans le menu latéral de gauche.

Pour en savoir davantage, visitez le dépôt du plugin sur GitHub.

VIII-B - HTML

1. Passez à l’onglet « Modules complémentaires » et sélectionnez « Importer et insérer HTML ».

2. Sélectionnez le contenu nécessaire.

3. Dans le champ du module complémentaire du menu latéral de gauche, le code HTML de l’extrait sélectionné s’affichera.

4. Modifiez ce code HTML si besoin.

5. Cliquez « Insérer au document » pour ajouter ce code HTML à un emplacement actuel du curseur dans le document.

Vous pouvez aussi écrire votre propre code HTML (sans sélectionner aucun contenu) et l’insérer dans le document.

Pour en savoir davantage, visitez le dépôt du plugin sur GitHub.

VIII-C - Compteur des mots

1. Sélectionnez une partie du texte.

2. Passez à l’onglet « Modules complémentaires » et sélectionnez « Compter mots et caractères ».

Veuillez noter que ces éléments ne sont pas pris en compte :

- symboles dans les notes de fin et de pied de page ;

- numéros dans les listes numérotées ;

- numéros des pages.

Pour en savoir davantage, visitez le dépôt du plugin sur GitHub.

VIII-D - Google Translate

- Sélectionnez le texte que vous avez besoin de traduire.

- Passez à l’onglet « Modules complémentaires » et sélectionnez « Traducteur ».

- Sélectionnez la langue dans une liste déroulante.

- Le texte sera traduit vers une langue choisie.

Pour en savoir davantage, visitez le dépôt du plugin sur GitHub.

VIII-E - Typograf

- Passez à l’onglet « Modules complémentaires » et sélectionnez « Typograf ».

- Cliquez sur le bouton « Afficher les paramètres avancés ». Définissez une région parmi les 29 régions disponibles et les règles que vous souhaitez appliquer à votre texte : la ponctuation, la ponctuation en retrait, le tiret et le trait d’union, l'espace insécable, l’espacement et la fin de ligne, le HTML, la date, la devise, les nombres et les expressions mathématiques, les symboles et les signes, etc.

- Sélectionnez un extrait de texte et cliquez sur le bouton « Corriger le texte ».

Pour en savoir davantage, visitez le dépôt du plugin sur GitHub.

IX - Supprimer les modules complémentaires

Si vous ne souhaitez plus utiliser un des plugins, vous êtes en mesure de le supprimer en quelques clics :

- dans les applications de bureau : utilisez le bouton « Supprimer plugin » dans la section « Paramètres » de l’onglet « Modules complémentaires ».

- dans les installations autohébergées : effacez le dossier (ou les dossiers) du plugin ou supprimez les lignes ajoutées dans le fichier de configuration de ONLYOFFICE Document Server. Ce plugin ne sera plus disponible pour tous les utilisateurs du portail après le redémarrage de l’éditeur.

Si vous ne trouvez pas les fonctionnalités dont vous avez besoin, vous êtes dès maintenant en mesure de créer vos propres modules complémentaires, les connecter à ONLYOFFICE et partager avec la communauté des utilisateurs.

X - Remerciements Developpez.com

Nous tenons à remercier Malick pour la mise au gabarit et Claude Leloup pour la relecture orthographique.