Tips for using the shared JavaScript runtime in your Office Add-in
This blog is the second of a series highlighting the shared runtime feature of the Office Add-ins platform.
The shared JavaScript runtime allows your Office Add-in JavaScript code to run in a single JavaScript runtime. Using a shared JavaScript runtime can simplify your code: Data and functionality is shared across all the code files in your project. Your project can access the task pane’s DOM from any code file, including ribbon commands, and custom functions. Your code will continue running even if the task pane is closed. And there are many newer UX features, such as keyboard shortcuts, that are enabled when you use the shared runtime.
Configure your project to use the shared runtime
Convert any existing project to use the shared runtime by applying a few changes to the manifest.xml file. We recommend following the steps in Configure your Office Add-in to use a shared JavaScript runtime.
After you configure your project, be sure to specify the correct requirements for the shared runtime. You want to specify the SharedRuntime requirement in your manifest as shown in the following XML.
<Requirements> <Sets DefaultMinVersion="1.1"> <Set Name="SharedRuntime" MinVersion="1.1"/> </Sets> </Requirements>
If your add-in also implements custom functions for Excel, you need to specify both SharedRuntime and CustomFunctionsRuntime as shown in the following XML.
<Requirements> <Sets DefaultMinVersion="1.1"> <Set Name="SharedRuntime" MinVersion="1.1"/> <Set Name="CustomFunctionsRuntime" MinVersion="1.1"/> </Sets> </Requirements>
Share data and functionality in your code
Once your Office Add-in project is set up to use the shared runtime, all parts of your code will run in the same JavaScript runtime and can share data. JavaScript functions in one file can call functions in another file — there are no boundaries between your code files. For example, functions in commands.js can call functions in taskpane.js.
The following code sample shows how to set up and store a global variable when the user presses a Reset image length button.
// commands.js file
// Import functions from taskpane.js.
import {taskPaneUpdateImageMetrics} from "../taskpane/taskpane.js";
// Handle the button press event, set global variable, and call task
// pane to update its UI.
function btnResetImageLength(event)
{
// getglobal() is a helper function yo office builds into the project.
let g = getGlobal();
g.imageLength=100;
taskPaneUpdateImageMetrics();
event.completed();
}
...
// taskpane.js file
// Import functions from commands.js.
import {getGlobal} from "../commands/commands.js";
// Update element in the DOM by reading global variable value
export function taskPaneUpdateImageMetrics()
{
const g = getGlobal();
document.getElementById("imageLength").textContent=g.imageLength;
}
Run code even when the task pane is closed
The shared runtime continues to run even if the task pane is closed. This means you can create global variables and not lose state when the user closes the task pane window.
// You can rely on this variable to persist even if the task pane is closed
var userName;
function setUserName(name)
{
userName = name;
}
Also, the shared runtime sends events when the task pane is opened or closed. Handle these events to take an action when the user opens or closes the task pane. For example, you may want to load or refresh data when the task pane is opened. For more information, see Show or hide the task pane of your Office Add-in.
Office.addin.onVisibilityModeChanged(function(args)
{
if (args.visibilityMode = "Taskpane");
{
// Code that runs whenever the task pane is made visible.
// For example, an Excel.run() that loads the names of
// all worksheets and passes them to the task pane UI.
}
}
);
Access the task pane DOM from anywhere
Using shared runtime allows you to access the DOM of your task pane from any code file. For example, say your add-in has a button to set the add-in to use metric units. The code needs to update the task pane UI to reflect the state change. The following example shows how to handle a button press event in commands.js and update a checkbox on the task pane.
function btnSetMetric(event)
{
document.getElementById('metric').checked="true";
event.completed();
}
Handle events anywhere
Code to handle events doesn’t need to be in a specific file. For example, you can handle command events from the ribbon in the taskpane.js file. Or move custom functions from functions.js to a different file. Note that if you move custom functions, you need to be sure the custom functions metadata generator points to the correct file location in webpack.config.js. For more information, see the README.md in OfficeDev/Office-Addin-Scripts (github.com).
Features enabled in shared runtime
There are many features that are enabled when you use the shared runtime. See the following documents for more information about any feature you are interested in, or required in your Office Add-in.
- Enable and Disable Add-in Commands
- Create custom contextual tabs in Office Add-ins
- Position a custom tab on the ribbon
- Custom keyboard shortcuts in Office Add-ins
- Show or hide the task pane of your Office Add-in
- Run code in your Office Add-in when the document opens
- Automatically open a task pane with a document
- Call Excel JavaScript APIs from a custom function
More resources
Many Office Add-ins, including yours, could benefit from using the shared runtime. Whether you’re creating a new Office Add-in or updating an existing one, get started by reading Configure your Office Add-in to us a shared JavaScript runtime. We also have several PnP shared runtime samples available if you want to explore more. With PowerPoint shared runtime support on Windows now in Public Preview, there’s even more coming soon. Keep an eye out for new blog posts here as new information becomes available.
David Chesnut
David Chesnut is a Senior Dev Writer on the Microsoft 365 Developer Platform Team
Light
Dark