Débogage des plugins ONLYOFFICE : guide pratique

Le développement et le débogage des plugins ONLYOFFICE peuvent s’avérer difficiles, mais avec les bons outils et les bonnes techniques, le processus peut être considérablement simplifié. Ce guide vous explique les étapes à suivre pour déboguer efficacement les plugins dans différents environnements.

À propos des plugins ONLYOFFICE

ONLYOFFICE vous permet d’étendre les fonctionnalités de ses éditeurs grâce à des plugins. Ces plugins sont des pages HTML intégrées à l’éditeur et qui utilisent une API pour interagir avec lui. Il est essentiel de comprendre la structure des plugins et les méthodes de débogage pour réussir leur développement.

Structure du plugin

Un plugin ONLYOFFICE type comprend les fichiers suivants :

• config.json : Fichier de configuration qui définit les informations de base concernant le plugin.
• index.html: La page HTML principale du plugin.
• scripts: Un répertoire contenant les fichiers JavaScript nécessaires au fonctionnement du plugin.

Une structure détaillée et des exemples sont disponibles ici.

Débogage des plugins dans les éditeurs web

Pour déboguer les plugins dans la version web de l’éditeur ONLYOFFICE, procédez comme suit :

• Ajoutez la commande du débogueur à votre script.

(function (window, undefined) {
    window.Asc.plugin.init = function () {
        this.callCommand(function () {
            debugger;
            let oDocument = Api.GetDocument();
            let oParagraph = Api.CreateParagraph();
            oParagraph.AddText("Hello from the plugin!");
            oDocument.InsertContent([oParagraph]);
        }, true);
    };
})(window, undefined);

• Appuyez sur F12 pour ouvrir la console dans votre navigateur.
• Dans l’éditeur ONLYOFFICE, accédez à l’onglet Modules complémentaires et exécutez votre plugin.

Remarque : la commande du débogueur ne fonctionnera que si les outils de développement sont ouverts ; sinon, elle sera ignorée. Vous pouvez en savoir plus à ce sujet sur cette page.

Débogage des plugins dans les éditeurs de bureau

Pour déboguer les plugins dans la version bureau de l’éditeur ONLYOFFICE, procédez comme suit :

• Exécutez l’éditeur avec l’indicateur –ascdesktop-support-debug-info.

• Ce drapeau active l’affichage d’informations supplémentaires utiles pour le débogage.
• Comme pour les éditeurs Web, insérez le débogueur à l’endroit souhaité dans votre code.

(function (window, undefined) {
    window.Asc.plugin.init = function () {
        this.callCommand(function () {
            debugger;
            let oDocument = Api.GetDocument();
            let oParagraph = Api.CreateParagraph();
            oParagraph.AddText("Hello from the plugin!");
            oDocument.InsertContent([oParagraph]);
        }, true);
    };
})(window, undefined);

• Appuyez sur F1 pour ouvrir la console et exécuter le plugin.

Après avoir démarré l’éditeur avec l’indicateur spécifié, ouvrez le plugin et suivez l’exécution du code.

Des instructions détaillées pour différents systèmes d’exploitation sont disponibles ici.

Gestion des champs d’application

Lors du développement d’un plugin ONLYOFFICE, il est important de comprendre comment transférer des données entre l’interface utilisateur de votre plugin (la page HTML) et l’environnement d’exécution de l’éditeur où les commandes de l’API Document Builder sont exécutées. Il s’agit de contextes ou de champs d’application différents.

Une source courante de bogues est la mauvaise gestion des données entre ces champs d’application. ONLYOFFICE fournit l’objet Asc.scope pour faciliter cette tâche. Vous pouvez associer des variables à Asc.scope dans le script principal de votre plugin, et elles seront accessibles dans la fonction transmise à this.callCommand().

Voici un exemple illustrant comment transmettre une variable texte à votre plugin vers l’éditeur :

(function (window, undefined) {
    window.Asc.plugin.init = function () {
    // In your main script (e.g., scripts/plugin.js)
    let text = "Hello from the plugin!";
    Asc.scope.dataForEditor = text; // Export variable to the shared plugin scope
    // In the command executed in the editor's scope
    this.callCommand(function () {
         debugger;
         let oDocument = Api.GetDocument();
         let Paragraph = Api.CreateParagraph();
         oParagraph.AddText(Asc.scope.dataForEditor);// Access the variable via Asc.scope
         oDocument.InsertContent([oParagraph]);
    }, true);
  };
})(window, undefined);

Une utilisation correcte d’Asc.scope garantit que les données sont transmises correctement entre différents contextes, ce qui est essentiel pour créer des plugins complexes.

Problèmes courants et dépannage

Lors du débogage, vous pouvez rencontrer plusieurs problèmes courants. Voici quelques-uns des problèmes les plus fréquents et leurs solutions :

L’instruction du débogueur ne fonctionne pas.

L’instruction debugger; est ignorée et l’exécution ne s’interrompt pas.

• Assurez-vous que les outils de développement du navigateur (F12) sont ouverts avant d’exécuter le plugin.
• L’instruction debugger; ne fonctionne que lorsque DevTools est actif.

Le plugin ne se charge pas ou n’est pas visible

• Vérifiez que votre fichier config.json est correctement formaté (JSON valide).
• Vérifiez que tous les champs obligatoires dans config.json sont présents (nom, guid, baseUrl).
• Vérifiez la console du navigateur pour voir s’il y a des erreurs de chargement.
• Assurez-vous que le plugin est correctement installé dans l’onglet Modules complémentaires d’ONLYOFFICE.
• Installation manuelle avec le fichier .plugin compressé ou la méthode Asc.editor.installDeveloperPlugin().

Erreurs Cors (partage de ressources entre origines)

• Installez ONLYOFFICE Docs.
• Pour les éditeurs Web dans ONLYOFFICE Docs, assurez-vous d’exécuter http-server dans votre dossier de plugins.
• Ou modifiez le chemin d’accès à votre fichier config.json dans installDeveloperPlugin().

Asc.editor.installDeveloperPlugin("https://<documentserver>:<port>/<folder-name>/config.json")

Fichiers modifiés, l’ancien code fonctionne toujours – Éditeurs Web

• Si vous avez modifié les fichiers locaux de votre plugin, vous devrez actualiser votre page et vider le cache.
• Cliquez avec le bouton droit sur le bouton d’actualisation de votre navigateur et sélectionnez « Vider le cache et recharger complètement », puis relancez votre plugin.

Un débogage efficace est essentiel pour développer des plugins ONLYOFFICE stables et fonctionnels. En utilisant les techniques et les outils mentionnés, vous pouvez rapidement identifier et résoudre les problèmes dans votre code, améliorant ainsi la qualité et les performances de vos plugins.

Nous sommes ouverts à toutes vos questions, suggestions et idées de plugins. Si vous souhaitez partager votre travail avec nous, n’hésitez pas à nous contacter. Nous sommes ouverts à toute collaboration et ravis d’échanger avec vous.