Tutoriel pour apprendre comment créer un plugin pour ONLYOFFICE DocSpace

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 créer un plugin pour ONLYOFFICE DocSpace

- Auteur : Daria Lapikhina

- Parution : 11 avril 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 des plugins ONLYOFFICE DocSpace

- III. Structure du plugin

- IV. Comment créer un plugin

- V. Planification

- V-A. Installer tous les paquets et logiciels nécessaires.

- V-B. Concevez le fonctionnement de votre plugin

- VI. Développement

- VI-A. Créer un modèle de plugin

- VI-B. Configurer le point d'entrée du plugin

- VI-C. Ajouter des icônes de plugin

- VI-D. Configurer les éléments d'interface du plugin

- VI-E. Créer des types de plugins

- VI-F. Créer le type de plugin de configuration

- VI-G. Créer le fichier de code principal du plugin

- VII. Test d’essai

- VIII. Ressources utiles

- IX. Remerciements Developpez.com

I - Introduction

ONLYOFFICE DocSpace est une plateforme cloud collaborative qui permet aux utilisateurs d'éditer et de collaborer sur des documents texte, des feuilles de calcul, des présentations et des formulaires dans des salles personnalisables. Il offre les fonctionnalités suivantes :

- créer et personnaliser des salles de collaboration ;

- créer, modifier et afficher des documents texte, des feuilles de calcul, des présentations, des formulaires à remplir, de PDF, des livres électroniques et des fichiers multimédias ;

- inviter les utilisateurs à collaborer en temps réel sur des fichiers.

L'API d'ONLYOFFICE DocSpace est utilisée pour permettre aux développeurs d'intégrer ONLYOFFICE DocSpace dans leurs propres applications web, permettant aux utilisateurs de créer et de soumettre des documents directement à partir de leurs sites web.

II - À propos des plugins ONLYOFFICE DocSpace

Les plugins sont des applications intégrées qui apportent des fonctionnalités supplémentaires à la plateforme. Voici quelques exemples de ce que vous pouvez faire avec les plugins de ONLYOFFICE DocSpace :

- connecter des services tiers, comme Draw.io, conversion de la parole en texte, etc. ;

- améliorer l'expérience utilisateur existante et la fonctionnalité des éditeurs : convertisseur de PDF.

Des exemples de code sont disponibles sur GitHub.

III - Structure du plugin

Chaque plugin DocSpace est un dossier contenant des fichiers. Il doit contenir les fichiers suivants, nécessaires au fonctionnement du plugin :

- assets — un dossier pour stocker les images du plugin. L'imbrication n'est pas prise en charge. Les formats suivants sont actuellement pris en charge : .jpg, .jpeg, .png, .svg.

- dist — un dossier pour stocker la version compilée du plugin.

- scripts — un dossier pour stocker les fichiers de script pour la construction du plugin. Le script createZip.js est ajouté à ce dossier. Le script est exécuté lors de la construction du plugin pour l'archiver automatiquement et créer le fichier config.json.

- src — un dossier pour les fichiers sources du plugin.

- src/index.ts — le point d'entrée pour la construction du plugin. Ce fichier est obligatoire. Toutes les fonctionnalités nécessaires sont ajoutées à ce fichier pour que le plugin fonctionne dans le champ d'application spécifié. Dans ce fichier, le plugin est déclaré dans la portée window.Plugins.[pluginName] DocSpace, où pluginName doit correspondre au même paramètre du fichier package.json :

window.Plugins.PDFConverter = plugin || {};

- webpack.config.js — le fichier de configuration de webpack. Ce fichier peut être édité, mais il est important que dans le paramètre de sortie, le champ fileName soit égal à plugin.js et le champ path soit égal à dist :

"output": {
"filename": "plugin.js",
"path": path.resolve(__dirname, "dist"),
}

- tsconfig — le fichier de configuration de TypeScript. Ce fichier peut être édité.

- package.json — un fichier avec les informations sur le plugin et les dépendances. Ce fichier peut être édité et les nouvelles dépendances peuvent être ajoutées.

- .prettierrc — le fichier de configuration pour le paquet npm prettier. Ce fichier peut être édité.

IV - Comment créer un plugin

ONLYOFFICE DocSpace Plugins SDK est un package npm basé sur des moteurs TypeScript qui fournit des interfaces vous permettant de créer vos propres plugins et de les intégrer dans le portail DocSpace.

Nous allons nous plonger dans le processus complet de développement d'un plugin en nous basant sur nos exemples de plugins.

V - Planification

V-A - Installer tous les paquets et logiciels nécessaires.

- ONLYOFFICE DocSpace sur site. Les versions Enterprise et Community sont disponibles.

- Paquet npm @onlyoffice/docspace-plugin-sdk

Pour l’installer, utilisez la commande suivante :

npm i -g @onlyoffice/docspace-plugin-sdk

V-B - Concevez le fonctionnement de votre plugin

Choisissez le service qui vous permet d'ajouter les fonctionnalités nécessaires à votre DocSpace.

Assurez-vous que la documentation du service est disponible, vérifiez sa licence, la disponibilité des méthodes API, etc. Pour certains services, l'utilisateur doit obtenir une clé API pour commencer à utiliser le plugin.

Réfléchissez à l'endroit où implémenter le plugin, à sa structure, à la manière dont l'utilisateur interagira avec les composants du plugin, etc. En fonction de ces informations, dressez une liste des types de plugins et des éléments requis. Pour plus d'informations, lisez les sections Types de plugins et Éléments de plugins de la documentation du SDK des plugins.

Définissez la structure du plugin. Tous les fichiers nécessaires sont décrits ici. Tout le reste peut être organisé comme vous le souhaitez. Par exemple, dans le plugin draw.io, nous avons placé le code pour chaque type de plugin dans des dossiers séparés, alors que dans le plugin Saisie vocale, ce code est placé dans le dossier src.

Choisissez un nom pour votre plugin et écrivez-en une description.

VI - Développement

VI-A - Créer un modèle de plugin

Créez un modèle de plugin et configurez ses paramètres qui seront affichés dans les paramètres du plugin DocSpace :

Pour créer un modèle de plugin, ouvrez le terminal et exécutez la commande npx suivante :

npx create-docspace-plugin

Configurez le plugin dans le terminal en spécifiant les paramètres dans la boîte de dialogue. Tous les paramètres sont décrits ici.

Par exemple, les valeurs suivantes peuvent être utilisées pour le plugin de Saisie vocale :

Nom du plugin : speech-to-text

Version du plugin : 1.0.0

Auteur du plugin : ONLYOFFICE

Logo du plugin : logo.png

Description du plugin : Saisie vocale est un logiciel de reconnaissance vocale qui vous permet de reconnaître et de traduire la parole en texte.

Licence du plugin : Apache-2.0

Page d'accueil du plugin : https://github.com/ONLYOFFICE/docspace-plugin

Sélectionner les champs d'application (Appuyer sur <space> pour sélectionner, Entrer quand c'est fini) : API, Paramètres, Menu contextuel.

Un dossier contenant le modèle de plugin sera placé à l'endroit où vous avez exécuté la commande.

Vous pouvez modifier tous les paramètres spécifiés ultérieurement dans le fichier package.json.

Il est aussi possible de créer un plugin dans n'importe quel projet en ajoutant le package npm @onlyoffice/docspace-plugin-sdk comme dépendance et en spécifiant tous les champs nécessaires dans le fichier package.json.

VI-B - Configurer le point d'entrée du plugin

Le point d'entrée du plugin index.ts sera créé automatiquement dans le dossier src lors de l'étape de création du modèle. Ce fichier est obligatoire.

Ce fichier contient toutes les méthodes de base des types de plugins que vous avez sélectionnés à l'étape précédente. Vous pouvez modifier ce fichier à tout moment.

Si vous créez vous-même un plugin, sans modèle, pour le point d'entrée du plugin, vous pouvez utiliser le code de nos exemples de plugins prêts à l'emploi. Il fonctionnera parfaitement.

VI-C - Ajouter des icônes de plugin

Créez le dossier assets dans le dossier racine du plugin et ajoutez-y toutes les icônes du plugin. Le nombre d'icônes et leur taille dépendent des types de plugins que vous mettez en œuvre. Pour le plugin Saisie vocale, nous avons besoin des icônes suivantes :

- Le type de plugin par défaut nécessite une image de logo. Il est égal au paramètre logo du fichier package.json. Le logo sera affiché dans les paramètres du plugin DocSpace. La taille de l'icône requise est de 48x48 px. Sinon, elle sera compressée à cette taille.

- Le plugin du menu contextuel utilise une icône sur le bouton Convertir en texte. La taille requise de l'icône est de 16x16 px. Sinon, elle sera compressée à cette taille.

VI-D - Configurer les éléments d'interface du plugin

Si nécessaire, définissez les éléments de l'interface utilisateur du plugin. Consultez notre Storybook pour développer l'interface utilisateur de votre plugin.

Par exemple, le plugin draw.io contient deux éléments principaux d'interface utilisateur : la fenêtre modale et l'éditeur de diagramme. Créez les fichiers pour configurer chaque élément. Pour plus de commodité, vous pouvez placer ces fichiers dans un dossier séparé.

VI-E - Créer des types de plugins

Maintenant que le plugin par défaut est prêt, vous pouvez commencer à coder d'autres types de plugins.

Chaque type de plugin possède des éléments de plugin spécifiques. Définissez l'élément du menu contextuel qui s'affichera lorsque vous ferez un clic droit sur les fichiers audio ou vidéo :

export const contextMenuItem: IContextMenuItem = {     key: "speech-to-text-context-menu-item",     label: "Convert to text",     icon: "speech-to-text-16.png",     onClick: assemblyAI.speechToText,     fileType: [FilesType.video],     withActiveItem: true, };

VI-F - Créer le type de plugin de configuration

Configurez le type de plugin des paramètres pour fournir aux utilisateurs les paramètres de l'administrateur.

Créez un conteneur dans lequel les paramètres du plugin seront placés :

1. const descriptionText: TextGroup = {

2. component: Components.text,

3. props: {

4. text: "To generate API token visit https://www.assemblyai.com",

5. color: "#A3A9AE",

6. fontSize: "12px",

7. fontWeight: 400,

8. lineHeight: "16px",

9. },

10. };

12. const descGroup: BoxGroup = {

13. component: Components.box,

14. props: { children: [descriptionText] },

15. };

17. const parentBox: IBox = {

18. displayProp: "flex",

19. flexDirection: "column",

20. // marginProp: "16px 0 0 0",

21. children: [tokenGroup, descGroup],

22. };

Dans la description des paramètres, indiquez qu'il est nécessaire de générer un jeton API pour pouvoir travailler avec le plugin.

Configurez les paramètres de l'administrateur avec l'objet ISettings :

1. const adminSettings: ISettings = {

2. settings: parentBox,

3. saveButton: userButtonComponent,

4. onLoad: async () => {

5. assemblyAI.fetchAPIToken();

7. tokenInput.value = assemblyAI.apiToken;

9. if (!assemblyAI.apiToken) return { settings: parentBox };

11. plugin.setAdminPluginSettings(adminSettings);

13. return { settings: parentBox };

14. },

15. };

Spécifiez l'événement onLoad qui définit les paramètres du plugin qui seront affichés lorsque le bloc de paramètres est chargé.

Chaque élément de réglage est déterminé dans des fichiers séparés (boutons, jetons).

VI-G - Créer le fichier de code principal du plugin

Créez un fichier dans le dossier src avec le code principal du plugin. Ce fichier est obligatoire.

Reportez-vous à la documentation d'un service tiers pour écrire ce code.

VII - Test d’essai

Pour vérifier la fonctionnalité du plugin et corriger les éventuels bogues, testez le plugin.

Créez le plugin préparé en suivant les instructions ici.

Le dossier dist sera créé dans le dossier racine du plugin et l'archive du plugin y sera placée. Cette archive est le plugin complet qui peut être téléchargé sur le portail DocSpace.

Veuillez noter que vous ne pouvez télécharger vos propres plugins que dans la version serveur de DocSpace.

Téléchargez votre plugin sur le portail DocSpace et testez minutieusement son apparence et sa fonctionnalité.

Si des bogues apparaissent, corrigez le code source de votre plugin et répétez la procédure de construction et de test.

Si vous avez des questions sur les plugins DocSpace, posez-les à nos développeurs sur le forum ONLYOFFICE (inscription requise).

Vous pouvez également demander une fonctionnalité ou rapporter un bug en postant un problème sur GitHub.

VIII - 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

IX - Remerciements Developpez.com

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