Depuración de plugins de ONLYOFFICE: guía práctica

Desarrollar y depurar plugins de ONLYOFFICE puede ser un reto, pero con las herramientas y técnicas adecuadas el proceso puede ser mucho más sencillo. Esta guía te mostrará los pasos necesarios para depurar plugins de manera efectiva en diferentes entornos.

Acerca de los plugins de ONLYOFFICE

ONLYOFFICE permite ampliar la funcionalidad de sus editores mediante plugins. Estos plugins son páginas HTML incrustadas en el editor y utilizan una API para interactuar con él. Comprender la estructura del plugin y los métodos de depuración es clave para un desarrollo exitoso.

Estructura de un plugin

Un plugin típico de ONLYOFFICE consta de los siguientes archivos:

• config.json : Un archivo de configuración que define la información básica del plugin.
• index.html: La página HTML principal del plugin.
• scripts: Un directorio que contiene los archivos JavaScript necesarios para el funcionamiento del plugin.

Una estructura detallada y ejemplos están disponibles aquí.

Depuración de plugins en los editores web

Para depurar plugins en la versión web del editor ONLYOFFICE, sigue estos pasos:

• Añade el comando debugger en tu 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);

• Pulsa F12 para abrir la consola en tu navegador.
• En el editor ONLYOFFICE, ve a la pestaña Extensiones y ejecuta tu plugin.

Nota: El comando debugger solo funcionará si las herramientas de desarrollador están abiertas; de lo contrario, será ignorado. Puedes leer más sobre esto en esta página.

Depuración de plugins en los editores de escritorio

Para depurar plugins en la versión de escritorio del editor ONLYOFFICE, utiliza el siguiente método:

• Ejecuta el editor con el flag –ascdesktop-support-debug-info.

• Este flag habilita la visualización de información adicional útil para la depuración.
• Al igual que en los editores web, inserta debugger; en el lugar deseado de tu código.

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

• Pulsa F1 para abrir la consola y ejecutar el plugin.

Después de iniciar el editor con el flag especificado, abre el plugin y sigue la ejecución del código.

Instrucciones detalladas para diferentes sistemas operativos están disponibles aquí.

Gestión de ámbitos (scopes)

Al desarrollar un plugin de ONLYOFFICE, es importante entender cómo pasar datos entre la interfaz de usuario del plugin (la página HTML) y el entorno de ejecución del editor donde se ejecutan los comandos de la API del Document Builder. Estos son contextos o scopes diferentes.

Una fuente común de errores es el manejo incorrecto de datos entre estos ámbitos. ONLYOFFICE proporciona el objeto Asc.scope para facilitar este proceso. Puedes adjuntar variables a Asc.scope en el script principal de tu plugin, y serán accesibles dentro de la función que pasas a this.callCommand().

Aquí tienes un ejemplo de cómo pasar una variable de texto de tu plugin al 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);

Usar correctamente Asc.scope garantiza que los datos se transfieran adecuadamente entre los distintos contextos, lo cual es fundamental para construir plugins complejos.

Problemas comunes y soluciones

Durante la depuración puedes encontrarte con varios problemas frecuentes. Aquí tienes algunos de los más comunes y cómo resolverlos:

El debugger no funciona

El comando debugger; es ignorado y la ejecución no se detiene.

• Asegúrate de que las herramientas de desarrollador del navegador (F12) estén abiertas antes de ejecutar el plugin.
• El comando debugger; solo funciona cuando DevTools están activas.

El plugin no carga o no es visible

• Verifica que tu archivo config.json esté correctamente formateado (JSON válido).
• Comprueba que todos los campos obligatorios estén presentes en config.json (name, guid, baseUrl).
• Revisa la consola del navegador en busca de errores de carga.
• Asegúrate de que el plugin esté instalado correctamente en la pestaña de plugins de ONLYOFFICE.
• Si la instalación es manual, usa un archivo .plugin comprimido o el método Asc.editor.installDeveloperPlugin().

Errores CORS (cross-origin resource sharing)

• Instala ONLYOFFICE Docs.
• Para los editores web en ONLYOFFICE Docs, asegúrate de ejecutar http-server dentro de la carpeta de tu plugin.
• O ajusta la ruta a tu archivo config.json en installDeveloperPlugin().

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

Los archivos cambiaron, pero el código antiguo sigue ejecutándose – Editores web

• Si cambiaste archivos locales de tu plugin, necesitarás actualizar la página y limpiar la caché.
• Haz clic derecho sobre el botón de recarga de tu navegador y selecciona “Empty Cache and Hard Reload”, luego ejecuta nuevamente tu plugin.

La depuración efectiva es fundamental para desarrollar plugins de ONLYOFFICE estables y funcionales. Utilizando las técnicas y herramientas mencionadas, podrás identificar y resolver rápidamente los problemas en tu código, mejorando así la calidad y el rendimiento de tus plugins.

Agradecemos tus preguntas, sugerencias e ideas de plugins. Si deseas compartir tu trabajo con nosotros, no dudes en ponerte en contacto. Estamos abiertos a colaborar y encantados de conectar contigo.