Come aggiungere un nuovo plugin come scheda a ONLYOFFICE Docs

Con il rilascio di ONLYOFFICE Docs 8.1, abbiamo introdotto un’ampia gamma di nuove funzionalità progettate per migliorare la versatilità e semplificare l’esperienza dell’utente. Tra questi miglioramenti c’è la possibilità di visualizzare i plugin in una scheda separata. In questo post del blog ti illustreremo i passaggi per sfruttare al meglio questa nuova funzione.

Di cosa si tratta

Questa funzione consente di creare una scheda dedicata nella barra degli strumenti per un plugin specifico.

Questa può contenere funzionalità aggiuntive per il plugin, rendendole facilmente accessibili.

Implementazione

Per attivare questa funzione nel plugin è necessario apportare modifiche a due file:

config.json – Nel file config.json è necessario sottoscrivere l’evento onToolbarMenuClick cliccando il parametro events alla configurazione del plugin.

  "events"              : ["onToolbarMenuClick"]

code.js – Nel file code.js dovrai usare il metodo AddToolbarMenuItem, che consente di creare una scheda separata e di visualizzarne gli elementi.

this.executeMethod("AddToolbarMenuItem", [getToolbarItems()]);

Esempio di plugin come scheda

Diamo un’occhiata più da vicino a queste modifiche. A scopo dimostrativo, creeremo un nuovo plugin che inserisce diversi oggetti in un documento di testo, con le opzioni di inserimento gestite dal menù della barra degli strumenti. L’esempio di plugin si trova in questo repository di GitHub.

Modifa del file config.json 

Per registrare gli eventi che attivano la creazione di una scheda aggiuntiva, aggiungiamo il parametro onToolbarMenuClick al parametro events.

Ecco l’intero file config.json:

{
    "name"       : "Plugin as tab",
    "guid"       : "asc.{0616AE85-5DBE-4B6B-A0A9-455C4F1503AD}",
    "baseUrl"    : "",
    "variations" : [
        {
            "description"         : "Example of displaying a plugin in a separate tab",
            "url"                 : "index.html",
            "icons"               : ["resources/img/icon.png", "resources/img/icon@2x.png"],
            "isViewer"            : false,
            "EditorsSupport"      : ["word"],
            "isVisual"            : false,
            "isModal"             : false,
            "isInsideMode"        : false,
            "initDataType"        : "none",
            "initData"            : "",
            "isUpdateOleOnResize" : true,
            "buttons"             : [],
            "events"              : ["onToolbarMenuClick"]
        }
    ],
    "store": {
                "background": {
                    "light": "radial-gradient(circle, #B5BCC3 0%, #737D87 100%)",
                    "dark": "radial-gradient(circle, #B5BCC3 0%, #737D87 100%)"
                },
                "icons": {
                    "light": "resources/store/icons",
                    "dark": "resources/store/icons"
                },
                "categories": ["specAbilities", "work"]
            }
}

Modifica del file code.js file

Inizializzazione del plugin e aggiunta di elementi della barra degli strumenti

Per inizializzare il plugin usiamo il metodo window.Asc.plugin.init. Questo metodo è il punto di ingresso del plugin e viene richiamato automaticamente quando il plugin viene caricato.

 window.Asc.plugin.init = function () {
      this.executeMethod("AddToolbarMenuItem", [getToolbarItems()]);// the rest of the plugin code
  }

executeMethod(“AddToolbarMenuItem”): Questo metodo aggiunge la scheda personalizzata e i suoi elementi alla barra degli strumenti. Prende la configurazione restituita dalla funzione getToolbarItems:

  function getToolbarItems() {
        console.log()
        let items = {
          guid: window.Asc.plugin.info.guid,
          tabs: [{
            id: "tab_1",
            text: "Insert options",
            items: [
              {
                id: "insertText",
                type: "button",
                text: "Insert text",
                hint: "insert text into the document",
                icons: "resources/buttons/icon_txt.png", 
                lockInViewMode: true,
                enableToggle: false,
                separator: false
              },
              {
                id: "insertOleObject",
                type: "button",
                text: "Insert OLE Object",
                hint: "Insert an OLE object into the document",
                icons: "resources/buttons/icon_ole.png", 
                lockInViewMode: true,
                enableToggle: false,
                separator: false
              },
              {
                id: "insertImage",
                type: "button",
                text: "Insert image",
                hint: "Insert an image into the document",
                icons: "resources/buttons/icon_img.png", 
                lockInViewMode: true,
                enableToggle: false,
                separator: false
              }
            ]
          }]
        };
  
        return items;
      }
    };

Questa funzione restituisce l’oggetto di configurazione che definisce la scheda e i suoi pulsanti:

• guid: identificatore univoco del plugin.
• tabs: array di oggetti scheda, ciascuno contenente un ID, un’etichetta di testo e un array di elementi.
• items: array di configurazioni di pulsanti, dove ogni pulsante ha proprietà come id, tipo, testo, suggerimento, icone, ecc.

Gestione degli eventi di clic degli elementi della barra degli strumenti

Ogni pulsante della barra degli strumenti nella nostra scheda personalizzata genera un evento quando ci si clicca. È necessario gestire questi eventi per eseguire le azioni corrispondenti. Per farlo, si utilizza il metodo attachToolbarMenuClickEvent.

Quando si clicca il pulsante Insert text, si esegue un comando per inserire un nuovo paragrafo con testo formattato:

 this.attachToolbarMenuClickEvent("insertText", function (data) {
        this.callCommand(function () {
          var oDocument = Api.GetDocument();
  
          // Create a new paragraph
          var oParagraph = Api.CreateParagraph();
  
          // Add text to the paragraph
          oParagraph.AddText("ONLYOFFICE Docs 8.1");
  
          // Style the text as a title
          oParagraph.SetBold(true);              // Make the text bold
          oParagraph.SetFontSize(24);            // Increase the font size
          oParagraph.SetJc("center");         // Align text to the center
  
          // Insert the paragraph at the beginning of the document
          oDocument.InsertContent([oParagraph],0);
        });
      });

Per il pulsante Insert OLE Object, viene inserito un oggetto OLE (ad esempio un video di youtube) nel documento:

  this.attachToolbarMenuClickEvent("insertOleObject", function (data) {
        this.callCommand(function () {
          var oDocument = Api.GetDocument();
          var oOleObject = Api.CreateOleObject("data:image/jpeg;base64,<Base64ImageCode>", 130 * 36000, 90 * 36000, "https://www.youtube.com/watch?v=oYlRfQ2zhaQ", "asc.{38E022EA-AD92-45FC-B22B-49DF39746DB4}");
          var oParagraph = oDocument.GetElement(0);
          oParagraph.AddDrawing(oOleObject);
          oParagraph.SetJc("center");
        });
  
      });

Il pulsante Insert image permette di aggiungere un’immagine:

this.attachToolbarMenuClickEvent("insertImage", function (data) {
        this.callCommand(function () {
  
          var oDocument = Api.GetDocument();
          var oParagraph = oDocument.GetElement(0);
          var oDrawing = Api.CreateImage("data:image/jpeg;base64,<Base64ImageCode>", 150 * 36000, 90 * 36000);
          oParagraph.SetJc("center");
          oParagraph.AddDrawing(oDrawing);
  
        });
      });

Ora vediamo il plugin in azione!

Ci auguriamo che questo articolo ti sia utile per integrare questa funzione innovativa nei tuoi plugin. Noi di ONLYOFFICE ci impegniamo a migliorare continuamente l’esperienza dell’utente introducendo nuove funzionalità e miglioramenti.

Incoraggiamo sempre gli sviluppatori a trarre vantaggio da queste nuove funzionalità creando plugin innovativi che le sfruttino. Siamo sempre aperti alla collaborazione e alla discussione, quindi sentiti libero di condividere i tuoi plugin con noi. Insieme, possiamo continuare a rendere ONLYOFFICE uno strumento ancora più potente. In bocca al lupo e buon lavoro!