How to call commands

To call commands and send the data back to the editor, use the Editor.RunMacro method. In editors before version 10.0, use the callCommand method instead. Both methods allow the plugin to send structured data that can be inserted to the resulting document file (formatted paragraphs, tables, text parts, and separate words, etc.).

RunMacro always keeps the plugin window open and recalculates the document. To close the window after the command or skip recalculation, use callCommand.

Editor.RunMacro

Office JavaScript API code is run with the RunMacro method of the global Editor object. The method passes its other arguments to the function and returns a Promise with the value that the function returns:

const count = await Editor.RunMacro((text, bold) => {
  const oDocument = Api.GetDocument();
  const oParagraph = Api.CreateParagraph();
  oParagraph.AddText(text).SetBold(bold);
  oDocument.InsertContent([oParagraph]);
  return oDocument.GetElementsCount();
}, "Hello world", true);

The arguments replace the Asc.scope object that callCommand uses to pass data, so nothing needs to be stored before the call:

const text = "Hello world";

await Editor.RunMacro((text) => {
  const oDocument = Api.GetDocument();
  const oParagraph = Api.CreateParagraph();
  oParagraph.AddText(text);
  oDocument.InsertContent([oParagraph]);
}, text);

RunMacro sends the function to the editor in the same way as callCommand, so the same rules apply:

• The function runs in its own context and cannot see the plugin variables. Pass everything it needs as arguments. The Asc.scope object is still available inside it.
• The arguments are serialized to JSON. Strings, numbers, booleans, null, arrays, and plain objects arrive intact. Functions, DOM nodes, and class instances are lost or arrive as plain objects.
• Only the JS standard types can be returned. Office JavaScript API objects, such as ApiParagraph, arrive in the plugin as undefined.
• The document is always recalculated after the function runs, and the plugin window stays open, as with callCommand(func, false, true).

Errors

Unlike callCommand, RunMacro passes the errors thrown by the function back to the plugin. If the function throws, the Promise rejects with an Error whose message contains the name and the message of the original error, for example, TypeError: Cannot read properties of null (reading 'GetRange'). The Promise also rejects if the editor rolls back the changes made by the function, with the message The editor rolled back the changes made by the command. Handle both cases with try...catch around await:

try {
  await Editor.RunMacro(() => {
    Api.GetDocument().GetElement(100).GetRange().Select();
  });
} catch (e) {
  console.error(e.message);
}

If the last argument is a function, it is used as a callback, and RunMacro does not return a Promise. When the function throws, the callback receives an object with the error text in the onlyoffice_id_error_message property instead of the result:

Editor.RunMacro(() => {
  return Api.GetDocument().GetElementsCount();
}, (result) => {
  if (result && result.onlyoffice_id_error_message) {
    console.error(result.onlyoffice_id_error_message);
    return;
  }
  console.log(result);
});

callCommand

Parameters

Name	Type	Description
func	function	The command written in JavaScript to form structured data which can be inserted to the resulting document file (formatted paragraphs, tables, text parts, and separate words, etc.). Then the data is sent to the editors. The command must be compatible with Office JavaScript API syntax.
isClose	boolean	Whether the plugin window must be closed after the code is executed or left open waiting for another command or action. The true value is used to close the plugin window after executing the function in the func parameter. The false value is used to execute the command and leave the window open waiting for the next command. The default value is false.
isCalc	boolean	Whether the document will be recalculated or not. The true value is used to recalculate the document after executing the function in the func parameter. The false value will not recalculate the document (use it only when your edits surely will not require document recalculation). The default value is true.
callback	function	The result that the method returns. Only the JS standard types are available (any objects will be replaced with undefined).

Returns

This method doesn't return any data.

Example

Asc.plugin.callCommand(() => {
  const oDocument = Api.GetDocument();
  const oParagraph = Api.CreateParagraph();
  oParagraph.AddText("Hello world");
  oDocument.InsertContent([oParagraph]);
}, true, true, (returnValue) => {});

Asc.scope object

This method is executed in its own context isolated from other JavaScript data. If some parameters or any additional data (objects, parameters, variables, etc.) need to be passed to this method, use Asc.scope object.

note

The functions cannot be passed to the callCommand method using the Asc.scope object

Example

Asc.scope.text = text;
Asc.plugin.callCommand(() => {
  const oDocument = Api.GetDocument();
  const oParagraph = Api.CreateParagraph();
  oParagraph.AddText(Asc.scope.text);
  oDocument.InsertContent([oParagraph]);
}, true, true, (returnValue) => {});

More examples

Insert a table

Asc.plugin.callCommand(() => {
  const oDoc = Api.GetDocument();
  const oTable = Api.CreateTable(3, 4);
  oDoc.InsertContent([oTable]);
}, false);

Insert an image from URL

Asc.scope.imageUrl = "https://example.com/image.png";

Asc.plugin.callCommand(() => {
  const oDoc = Api.GetDocument();
  const oParagraph = Api.CreateParagraph();
  const oImage = Api.CreateImage(Asc.scope.imageUrl, 100 * 36000, 60 * 36000);
  oParagraph.AddDrawing(oImage);
  oDoc.InsertContent([oParagraph]);
}, false);

Work with content controls

// Add a tagged content control
Asc.plugin.executeMethod("AddContentControl", [
  1, // type: 1 = richText
  { Tag: "myField", Lock: 0 },
]);

// Get all content controls
Asc.plugin.executeMethod("GetAllContentControls", [], (controls) => {
  controls.forEach((ctrl) => console.log(ctrl.Tag, ctrl.InternalId));
});

info object

The Asc.plugin.info object is a property of the Asc.plugin object. See Asc.plugin > info object for the full list of properties and examples.

Debugging

To log all callCommand and executeMethod calls to the browser console, set the asc_plugin_commands_log key in the browser's local storage:

localStorage.setItem("asc_plugin_commands_log", "true");

To disable logging, remove the key:

localStorage.removeItem("asc_plugin_commands_log");

The setting persists across page reloads.