Eseguire debug dei plugin di ONLYOFFICE: una guida pratica

Sviluppare e fare debug dei plugin di ONLYOFFICE può essere impegnativo, ma con gli strumenti e le tecniche giuste il processo diventa molto più semplice. Questa guida ti spiega i passaggi necessari per eseguire correttamente il debug dei plugin in diversi ambienti.

Informazioni sui plugin ONLYOFFICE

ONLYOFFICE permette di estendere le funzionalità dei suoi editor tramite plugin. Questi plugin sono pagine HTML incorporate nell’editor e utilizzano un’API per interagire con esso. Capire la struttura del plugin e i metodi di debug è essenziale per uno sviluppo efficace.

Struttura del plugin

Un tipico plugin ONLYOFFICE è composto dai seguenti file:

• config.json: un file di configurazione che definisce le informazioni di base sul plugin.
• index.html: la pagina HTML principale del plugin.
• scripts: una cartella contenente i file JavaScript necessari al funzionamento del plugin.

Una struttura dettagliata ed esempi sono disponibili qui.

Debug dei plugin negli editor web

Per eseguire il debug dei plugin nella versione web dell’editor ONLYOFFICE, segui questi passaggi:

• Aggiungi il comando debugger al tuo 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);

• Premi F12 per aprire la console del browser.
• Nell’editor ONLYOFFICE, vai alla scheda Plugin ed esegui il tuo plugin.

Nota: il comando debugger funziona solo se gli strumenti per sviluppatori sono aperti; in caso contrario, viene ignorato. Puoi leggere di più su questa pagina.

Debug dei plugin negli editor desktop

Per eseguire il debug dei plugin nella versione desktop dell’editor ONLYOFFICE, utilizza il seguente approccio:

• Avvia l’editor con il flag –ascdesktop-support-debug-info.

• Questo flag abilita la visualizzazione di informazioni aggiuntive utili per il debug.
• Come negli editor web, inserisci debugger; nel punto desiderato del tuo codice.

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

• Premi F1 per aprire la console ed eseguire il plugin.

Dopo aver avviato l’editor con il flag indicato, apri il plugin e traccia l’esecuzione del codice.

Istruzioni dettagliate per i diversi sistemi operativi sono disponibili qui.

Gestione degli scope

Quando sviluppi un plugin ONLYOFFICE, è importante capire come passare dati tra l’interfaccia del plugin (la pagina HTML) e l’ambiente di esecuzione dell’editor, dove vengono eseguiti i comandi dell’API Document Builder. Questi sono contesti diversi o scope.

Una causa comune di bug è la gestione errata dei dati tra questi scope. ONLYOFFICE fornisce l’oggetto Asc.scope per facilitare il processo. Puoi associare variabili a Asc.scope nello script principale del plugin e saranno accessibili all’interno della funzione passata a this.callCommand().

Ecco un esempio di come passare una variabile di testo dal plugin all’editor:

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

Usare correttamente Asc.scope garantisce che i dati vengano passati correttamente tra i diversi contesti, cosa fondamentale per plugin complessi.

Problemi comuni e soluzioni

Durante il debug potresti incontrare vari problemi comuni. Ecco i più frequenti e come risolverli:

Il comando debugger non funziona

L’istruzione debugger; viene ignorata e l’esecuzione non si interrompe.

• Assicurati che gli strumenti di sviluppo del browser (F12) siano aperti prima di eseguire il plugin.
• L’istruzione debugger; funziona solo quando DevTools è attivo.

Il plugin non si carica o non è visibile

• Controlla che il file config.json sia formattato correttamente (JSON valido).
• Verifica che tutti i campi richiesti in config.json siano presenti (name, guid, baseUrl).
• Controlla la console del browser per eventuali errori di caricamento.
• Assicurati che il plugin sia installato correttamente nella scheda Plugin di ONLYOFFICE.
• Installazione manuale con file .plugin zippato o tramite il metodo Asc.editor.installDeveloperPlugin().

Errori CORS (cross-origin resource sharing)

• Installa ONLYOFFICE Docs.
• Per gli editor web in ONLYOFFICE Docs, assicurati di eseguire http-server all’interno della cartella del tuo plugin.
• Oppure modifica il percorso al file config.json in installDeveloperPlugin().

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

I file sono stati modificati ma il vecchio codice continua a essere eseguito – Web Editors

• Se hai modificato file locali del tuo plugin, devi aggiornare la pagina e la cache.
• Fai clic destro sul pulsante di aggiornamento del browser e seleziona “Empty Cache and Hard Reload”, poi esegui di nuovo il plugin.

Un debug efficace è fondamentale per sviluppare plugin ONLYOFFICE stabili e funzionanti. Usando le tecniche e gli strumenti menzionati, puoi identificare e risolvere rapidamente i problemi nel tuo codice, migliorando qualità e prestazioni dei tuoi plugin.

Siamo aperti alle tue domande, suggerimenti e idee per plugin. Se vuoi condividere il tuo lavoro con noi, non esitare a contattarci. Siamo disponibili alla collaborazione e felici di metterci in contatto.