Tutoriel pour apprendre comment ajouter un plugin en tant qu’onglet ou dans le panneau de droite dans ONLYOFFICE Docs

Daria Lapikhina

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

- Titre : Tutoriel pour apprendre comment ajouter un plugin en tant qu’onglet ou dans le panneau de droite dans ONLYOFFICE Docs

- Auteur : Daria Lapikhina

- Parution : 23 octobre 2024

- Licence : Copyright ® 2024 Daria Lapikhina . 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. À propos de la fonctionnalité d’ajout du plugin en tant qu’ onglet

- III. Activation de la fonctionnalité

- IV. Exemple de plugin en tant qu’onglet

- IV-A. Modification du fichier config.json

- IV-B. Modification du fichier code.js

- IV-B-1. Initialisation du plugin et ajout d’éléments de la barre d’outils

- IV-B-2. Gestion des événements de clic sur les éléments de la barre d’outils

- V. Comment ajouter un plugin sur le panneau de droite

- VI. Exemple de plugin en tant que panneau de droite

- VII. Ressources utiles

- VIII. Remerciements Developpez.com

I - Introduction

Les développeurs d’ONLYOFFICE introduisent un large éventail de nouvelles fonctionnalités conçues pour améliorer la polyvalence et rationaliser l’expérience utilisateur. Parmi ces améliorations figure la possibilité d’afficher les plugins dans un onglet séparé ou dans le panneau latéral.

Dans les guides précédents, nous avons déjà couvert comment créer un plugin pour ONLYOFFICE Docs. Cette fois-ci, nous allons développer ce sujet et vous expliquer comment ajouter un nouveau plugin en tant qu’onglet ou positionner le panneau des plugins à gauche ou à droite de l’éditeur dans ONLYOFFICE Docs.

II - À propos de la fonctionnalité d’ajout du plugin en tant qu’ onglet

Cette fonctionnalité vous permet de créer un onglet dédié dans la barre d’outils pour un plugin spécifique.

Cet onglet peut contenir des fonctionnalités supplémentaires pour votre plugin, le rendant facilement accessible.

III - Activation de la fonctionnalité

Pour activer l’ajout de votre plugin en tant qu’un onglet, vous devrez modifier deux fichiers :

config.json – Dans ce fichier, vous devrez vous abonner à l’événement onToolbarMenuClick en ajoutant le paramètre events à la configuration de votre plugin.

"events" : ["onToolbarMenuClick"]

code.js – Dans ce fichier, vous devrez utiliser la méthode AddToolbarMenuItem, qui permet de créer un onglet séparé et d’afficher ses éléments.

this.executeMethod("AddToolbarMenuItem", [getToolbarItems()]);

Consultez la structure du plugin dans le guide complet ONLYOFFICE Docs.

IV - Exemple de plugin en tant qu’onglet

Maintenant, il faut examiner ces changements de plus près. À des fins de démonstration, nous allons créer un nouveau plugin qui insère plusieurs objets dans un document texte, les options d’insertion étant gérées via le menu de la barre d’outils. L’exemple de plugin se trouve sur ce dépôt GitHub.

IV-A - Modification du fichier config.json

Pour enregistrer les événements qui déclenchent la création d’un onglet supplémentaire, nous ajoutons onToolbarMenuClick au paramètre events.

Voici l’intégralité du fichier config.json :

1. {

2. "name"       : "Plugin as tab",

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

4. "baseUrl"    : "",

5. "variations" : [

6. {             "description"         : "Example of displaying a plugin in a separate tab",

7. "url"                 : "index.html",

8. "icons"               : ["resources/img/icon.png", "resources/img/icon@2x.png"],

9. "isViewer"            : false,

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

11. "isVisual"            : false,

12. "isModal"             : false,

13. "isInsideMode"        : false,

14. "initDataType"        : "none",

15. "initData"            : "",

16. "isUpdateOleOnResize" : true,

17. "buttons"             : [],

18. "events"              : ["onToolbarMenuClick"]

19. }     ],     "store": {

20. "background": {

21. "light": "radial-gradient(circle, #B5BCC3 0%, #737D87 100%)",

22. "dark": "radial-gradient(circle, #B5BCC3 0%, #737D87 100%)"

23. },                 "icons": {

24. "light": "resources/store/icons",

25. "dark": "resources/store/icons"

26. },                 "categories": ["specAbilities", "work"]

27. } }

IV-B - Modification du fichier code.js

IV-B-1 - Initialisation du plugin et ajout d’éléments de la barre d’outils

Pour initialiser le plugin, nous utilisons la méthode window.Asc.plugin.init. Cette méthode est le point d’entrée du plugin et est appelée automatiquement lors du chargement du plugin.

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

2. this.executeMethod("AddToolbarMenuItem", [getToolbarItems()]);// the rest of the plugin code

3. }

executeMethod("AddToolbarMenuItem") : Cette méthode ajoute l’onglet personnalisé et ses éléments à la barre d’outils. Elle prend la configuration renvoyée par la fonction getToolbarItems :

1. function getToolbarItems() {

2. console.log()

3. let items = {

4. guid: window.Asc.plugin.info.guid,

5. tabs: [{

6. id: "tab_1",

7. text: "Insert options",

8. items: [

9. {                 id: "insertText",

10. type: "button",

11. text: "Insert text",

12. hint: "insert text into the document",

13. icons: "resources/buttons/icon_txt.png",

14. lockInViewMode: true,

15. enableToggle: false,

16. separator: false

17. },               {                 id: "insertOleObject",

18. type: "button",

19. text: "Insert OLE Object",

20. hint: "Insert an OLE object into the document",

21. icons: "resources/buttons/icon_ole.png",

22. lockInViewMode: true,

23. enableToggle: false,

24. separator: false

25. },               {                 id: "insertImage",

26. type: "button",

27. text: "Insert image",

28. hint: "Insert an image into the document",

29. icons: "resources/buttons/icon_img.png",

30. lockInViewMode: true,

31. enableToggle: false,

32. separator: false

33. }             ]           }]         };            return items;

34. }     };

Cette fonction renvoie l’objet de configuration qui définit l’onglet et ses boutons :

- guid : identifiant unique du plugin ;

- Tabs : tableau d’objets d’onglet, chacun contenant un ID, un label de texte et un tableau d’éléments ;

- items : tableau de configurations de boutons, où chaque bouton possède des propriétés telles que id, type, text, hint, icons, etc.

IV-B-2 - Gestion des événements de clic sur les éléments de la barre d’outils

Chaque bouton de la barre d’outils dans notre onglet personnalisé déclenche un événement lorsqu’il est cliqué. Nous devons gérer ces événements pour exécuter les actions correspondantes. Cela se fait à l’aide de la méthode attachToolbarMenuClickEvent.

Lorsque le bouton Insert text est cliqué, nous exécutons une commande pour insérer un nouveau paragraphe avec du texte formaté :

1. this.attachToolbarMenuClickEvent("insertText", function (data) {

2. this.callCommand(function () {

3. var oDocument = Api.GetDocument();

4. // Create a new paragraph

5. var oParagraph = Api.CreateParagraph();

6. // Add text to the paragraph

7. oParagraph.AddText("ONLYOFFICE Docs 8.1");

8. // Style the text as a title

9. oParagraph.SetBold(true);              // Make the text bold

10. oParagraph.SetFontSize(24);            // Increase the font size

11. oParagraph.SetJc("center");         // Align text to the center

12. // Insert the paragraph at the beginning of the document

13. oDocument.InsertContent([oParagraph],0);

14. });       });

Pour le bouton Insert OLE Object, un objet OLE (par exemple, une vidéo YouTube) est inséré dans le document :

1. this.attachToolbarMenuClickEvent("insertOleObject", function (data) {

2. this.callCommand(function () {

3. var oDocument = Api.GetDocument();

4. var oOleObject = Api.CreateOleObject("data:image/jpeg;base64,<Base64ImageCode>", 130 * 36000, 90 * 36000, "https://www.youtube.com/watch?v=oYlRfQ2zhaQ", "asc.{38E022EA-AD92-45FC-B22B-49DF39746DB4}");

5. var oParagraph = oDocument.GetElement(0);

6. oParagraph.AddDrawing(oOleObject);           oParagraph.SetJc("center");

7. });          });

Le bouton Insert image permet aux utilisateurs d’insérer une image :

1. this.attachToolbarMenuClickEvent("insertImage", function (data) {

2. this.callCommand(function () {

3. var oDocument = Api.GetDocument();

4. var oParagraph = oDocument.GetElement(0);

5. var oDrawing = Api.CreateImage("data:image/jpeg;base64,<Base64ImageCode>", 150 * 36000, 90 * 36000);

6. oParagraph.SetJc("center");

7. oParagraph.AddDrawing(oDrawing);            });       });

C'est ainsi que votre plugin peut désormais apparaître sous forme d'onglet.

V - Comment ajouter un plugin sur le panneau de droite

Une autre option de personnalisation intéressante vous permet de positionner le panneau des plugins à gauche ou à droite de l’éditeur.

Précédemment, le fichier config.json utilisait plusieurs paramètres pour gérer les fonctionnalités du plugin et déterminer son affichage dans l’éditeur, tels que : isInsideMode, isModal, isSystem, isVisual et menu.

system : un plugin au niveau du système qui est toujours actif et ne peut pas être désactivé.

background : un plugin d’arrière-plan qui fonctionne en continu une fois lancé. Son état (activé/désactivé) persiste entre les sessions.

window : un plugin qui fonctionne comme une fenêtre autonome lors de son lancement.

panel : un plugin qui s’ouvre dans le panneau de gauche.

panelRight : un plugin qui s’ouvre dans le panneau de droite.

unvisible : un plugin invisible au démarrage.

Examinons de plus près l’option panelRight, qui nous permet de positionner le panneau sur le côté droit de l’éditeur.

VI - Exemple de plugin en tant que panneau de droite

À titre d’exemple, nous utiliserons le plugin Zotero, qui permet de créer des bibliographies à l’aide du service Zotero. Après avoir installé le plugin avec succès, nous naviguons vers le dossier du plugin Zotero dans le répertoire sdkjs-plugins et nous modifions le fichier config.json. Nous prenons les paramètres dépréciés :

1. "isVisual": true,

2. "isModal": false,

3. "isInsideMode": true,

Et les remplaçons par :

"type": "panelRight",

Le fichier config.json modifié peut ressembler à ce qui suit :

1. {

2. "name": "Zotero",

3. "nameLocale": {

4. "ru": "Zotero",

5. "fr": "Zotero",

6. "es": "Zotero",

7. "pt-BR": "Zotero",

8. "de": "Zotero"

9. },     "guid": "asc.{BFC5D5C6-89DE-4168-9565-ABD8D1E48711}",

10. "version": "1.0.3",

11. "minVersion": "7.3.3",

12. "variations": [

13. {             "description": "Create bibliographies in the required style using Zotero service.",

14. "descriptionLocale": {

15. "ru": "Оформляйте библиографические списки в нужном стиле с помощью Zotero.",

16. "fr": "Créez des bibliographies dans le style nécessaire avec Zotero.",

17. "es": "Cree bibliografías en el estilo requerido utilizando el servicio Zotero.",

18. "pt-BR": "Crie bibliografias no estilo desejado usando o serviço Zotero.",

19. "de": "Erstellen Sie Literaturverzeichnisse im gewünschten Stil mittels Zotero."

20. },             "url": "index.html",

21. "icons": [

22. "resources/light/icon.png",

23. "resources/light/icon@2x.png"

24. ],             "icons2": [

25. {                     "style": "light",

26. "100%": {

27. "normal": "resources/light/icon.png"

28. },                     "125%": {

29. "normal": "resources/light/icon@1.25x.png"

30. },                     "150%": {

31. "normal": "resources/light/icon@1.5x.png"

32. },                     "175%": {

33. "normal": "resources/light/icon@1.75x.png"

34. },                     "200%": {

35. "normal": "resources/light/icon@2x.png"

36. }                 },                 {                     "style": "dark",

37. "100%": {

38. "normal": "resources/dark/icon.png"

39. },                     "125%": {

40. "normal": "resources/dark/icon@1.25x.png"

41. },                     "150%": {

42. "normal": "resources/dark/icon@1.5x.png"

43. },                     "175%": {

44. "normal": "resources/dark/icon@1.75x.png"

45. },                     "200%": {

46. "normal": "resources/dark/icon@2x.png"

47. }                 }             ],             "isViewer": false,

48. "EditorsSupport": [

49. "word"

50. ],             "initDataType": "text",

51. "initData": "",

52. "type": "panelRight",

53. "isUpdateOleOnResize": false,

54. "initOnSelectionChanged": false,

55. "store": {

56. "background": {

57. "light": "#2D3037",

58. "dark": "#2D3037"

59. },                 "screenshots": [

60. "resources/store/screenshots/screen_1.png",

61. "resources/store/screenshots/screen_2.png"

62. ],                 "icons": {

63. "light": "resources/store/icons",

64. "dark": "resources/store/icons"

65. },                 "categories": [

66. "specAbilities"

67. ]             }         }     ] }

Après avoir effectué toutes les modifications, votre plugin peut ressembler à ceci :

Remarque : pour positionner le panneau du plugin sur le côté gauche, modifiez l’option panelRight en panel.

Si vous voulez que votre plugin soit disponible pour d'autres utilisateurs dans ONLYOFFICE Plugin Marketplace, proposez-le pour publication en créant une demande d'extraction (pull request) de votre fork à https://github.com/ONLYOFFICE/onlyoffice.github.io. Si votre plugin fonctionne correctement, votre demande sera approuvée et le plugin apparaîtra sur la marketplace.

VII - Ressources utiles

- Comment intégrer DocSpace dans l’application à une page unique

- Comment intégrer une salle d’ONLYOFFICE DocSpace dans une application à page unique

- Code source de ONLYOFFICE DocSpace

- En savoir plus sur ONLYOFFICE DocSpace

- Les meilleurs cours et tutoriels pour apprendre ONLYOFFICE

VIII - Remerciements Developpez.com

Nous tenons à remercier Malick pour la mise au gabarit et f-leb pour la relecture orthographique.