Debuggen von ONLYOFFICE-Plugins: Praktischer Leitfaden

Die Entwicklung und das Debuggen von ONLYOFFICE-Plugins können eine Herausforderung sein, lassen sich aber mit den richtigen Werkzeugen und Techniken deutlich vereinfachen. Dieser Leitfaden führt Sie durch die notwendigen Schritte zum effektiven Debuggen von Plugins in verschiedenen Umgebungen.

Über ONLYOFFICE-Plugins

ONLYOFFICE ermöglicht es Ihnen, die Funktionalität seiner Editoren mithilfe von Plugins zu erweitern. Diese Plugins sind HTML-Seiten, die in den Editor eingebettet werden und über eine API mit ihm interagieren. Das Verständnis der Plugin-Struktur und der Debugging-Methoden ist entscheidend für eine erfolgreiche Entwicklung.

Struktur von Plugins

Ein typisches ONLYOFFICE-Plugin besteht aus folgenden Dateien:

• config.json: Eine Konfigurationsdatei, die grundlegende Informationen über das Plugin definiert.
• index.html: Die Haupt-HTML-Seite des Plugins.
• scripts: Ein Verzeichnis mit den für die Funktionalität des Plugins benötigten JavaScript-Dateien.

Eine detaillierte Struktur und Beispiele finden Sie hier.

Plugins in Web-Editoren debuggen

Um Plugins in der Webversion des ONLYOFFICE-Editors zu debuggen, gehen Sie wie folgt vor:

• Fügen Sie den debugger-Befehl zu Ihrem Skript hinzu.

(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);

• Drücken Sie F12, um die Konsole in Ihrem Browser zu öffnen.
• Wechseln Sie im ONLYOFFICE-Editor zum Tab „Plugins“ und führen Sie Ihr Plugin aus.

Hinweis: Der debugger-Befehl funktioniert nur, wenn die Entwicklertools aktiv sind; andernfalls wird er ignoriert. Weitere Informationen finden Sie auf dieser Seite.

Plugins in Desktop-Editoren debuggen

Um Plugins in der Desktop-Version der ONLYOFFICE-Editoren zu debuggen, gehen Sie wie folgt vor:

• Starten Sie den Editor mit dem Parameter –ascdesktop-support-debug-info.

• Dieser Parameter aktiviert die Anzeige zusätzlicher, für das Debuggen hilfreicher Informationen.
• Fügen Sie, ähnlich wie bei Web-Editoren, debugger; an der gewünschten Stelle in Ihrem Code ein.

(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);

• Drücken Sie F1, um die Konsole zu öffnen und das Plugin auszuführen.

Nachdem Sie den Editor mit dem angegebenen Flag gestartet haben, öffnen Sie das Plugin und verfolgen Sie die Codeausführung.

Detaillierte Anleitungen für verschiedene Betriebssysteme finden Sie hier.

Verwaltung von Gültigkeitsbereichen (Scopes)

Bei der Entwicklung eines ONLYOFFICE-Plugins ist es wichtig zu verstehen, wie Daten zwischen der Benutzeroberfläche Ihres Plugins (der HTML-Seite) und der Ausführungsumgebung des Editors, in der die Befehle der Document Builder API ausgeführt werden, übergeben werden. Dies sind unterschiedliche Kontexte oder Gültigkeitsbereiche.

Eine häufige Fehlerquelle ist die fehlerhafte Datenverarbeitung zwischen diesen Gültigkeitsbereichen. ONLYOFFICE stellt das Objekt Asc.scope zur Verfügung, um dies zu vereinfachen. Sie können Variablen an Asc.scope im Hauptskript Ihres Plugins anhängen. Diese sind dann innerhalb der Funktion, die an this.callCommand() übergeben wird, zugänglich.

Hier ist ein Beispiel, wie Sie eine Textvariable von Ihrem Plugin an den Editor übergeben:

(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);

Die korrekte Verwendung von Asc.scope gewährleistet, dass Daten korrekt zwischen verschiedenen Kontexten übergeben werden, was für die Entwicklung komplexer Plugins von entscheidender Bedeutung ist.

Häufige Probleme und Fehlerbehebung

Beim Debuggen können verschiedene Probleme auftreten. Hier sind einige der häufigsten Probleme und ihre Lösungen:

Debugger-Anweisung funktioniert nicht

Die Anweisung debugger; wird ignoriert und die Ausführung wird nicht angehalten.

• Stellen Sie sicher, dass die Entwicklertools Ihres Browsers (F12) geöffnet sind, bevor Sie das Plugin ausführen.
• Die Anweisung debugger; funktioniert nur, wenn die Entwicklertools aktiv sind.

Plugin wird nicht geladen oder ist nicht sichtbar

• Überprüfen Sie, ob Ihre config.json-Datei korrekt formatiert ist (gültiges JSON).
• Stellen Sie sicher, dass alle erforderlichen Felder in der config.json-Datei vorhanden sind (Name, GUID, Basis-URL).
• Prüfen Sie die Browserkonsole auf Ladefehler.
• Stellen Sie sicher, dass das Plugin im ONLYOFFICE-Plugin-Tab korrekt installiert ist.
• Manuelle Installation mit einer gezippten .plugin-Datei oder der Methode `Asc.editor.installDeveloperPlugin()`.

CORS-Fehler (Cross-Origin Resource Sharing)

• Installieren Sie ONLYOFFICE Docs.
• Für Web-Editoren in ONLYOFFICE Docs: Stellen Sie sicher, dass der http-Server im Plugin-Ordner ausgeführt wird.
• Alternativ können Sie den Pfad zur config.json-Datei in der Funktion installDeveloperPlugin() anpassen.

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

Dateien geändert, alter Code läuft noch – Web-Editoren

• Wenn Sie lokale Dateien Ihres Plugins geändert haben, müssen Sie Ihre Seite und den Cache aktualisieren.
• Klicken Sie mit der rechten Maustaste auf die Aktualisierungsschaltfläche Ihres Browsers und wählen Sie „Cache leeren und neu laden“. Starten Sie anschließend Ihr Plugin erneut.

Effektives Debugging ist entscheidend für die Entwicklung stabiler und funktionaler ONLYOFFICE-Plugins. Mithilfe der genannten Techniken und Tools können Sie Probleme in Ihrem Code schnell identifizieren und beheben und so die Qualität und Leistung Ihrer Plugins verbessern.

Wir freuen uns über Ihre Fragen, Anregungen und Plugin-Ideen. Wenn Sie Ihre Arbeit mit uns teilen möchten, kontaktieren Sie uns gerne. Wir sind offen für Kooperationen und freuen uns auf den Austausch.