FunctionFile element

Specifies the source code file for operations that an add-in exposes in one of the following ways.

• Add-in commands that execute a JavaScript function instead of displaying UI.
• Keyboard shortcuts that execute a JavaScript function.

Add-in type: Task pane, Mail

Valid only in these VersionOverrides schemas:

• Task pane 1.0
• Mail 1.0
• Mail 1.1

For more information, see Version overrides in the add-in only manifest.

The <FunctionFile> element is a child element of DesktopFormFactor or MobileFormFactor. The resid attribute of the <FunctionFile> element can be no more than 32 characters and is set to the value of the id attribute of a <Url> element in the Resources element that contains the URL to an HTML file that contains or loads all the JavaScript functions used by function command buttons, as defined by the Control element.

The following is an example of the <FunctionFile> element.

<DesktopFormFactor>
  <FunctionFile resid="Commands.Url" />
  <ExtensionPoint xsi:type="PrimaryCommandSurface">
    <!-- Information about this extension point. -->
  </ExtensionPoint>

  <!-- You can define more than one ExtensionPoint element as needed. -->
</DesktopFormFactor>

...

<Resources>
    <bt:Urls>
        <bt:Url id="Commands.Url" DefaultValue="https://www.contoso.com/commands.html" />
    </bt:Urls>

    <!-- Define other resources as needed. -->
</Resources>

The JavaScript in the HTML file indicated by the <FunctionFile> element must initialize Office.js and define named functions that take a single parameter: event. It should also call event.completed when it has finished execution. Functions in Outlook add-ins should use the notification APIs to indicate progress, success, or failure to the user. The name of the functions are used in the FunctionName element for function command buttons.

You can define and register the function specified by the <FunctionName> element in a separate JavaScript file that is loaded by the HTML file. The following is an example of such a file.

// Initialize the Office Add-in.
Office.onReady(() => {
  // If needed, Office.js is ready to be called
});

// The command function.
async function highlightSelection(event) {

    // Implement your custom code here. The following code is a simple Excel example.  
    try {
          await Excel.run(async (context) => {
              const range = context.workbook.getSelectedRange();
              range.format.fill.color = "yellow";
              await context.sync();
          });
      } catch (error) {
          // Note: In a production add-in, notify the user through your add-in's UI.
          console.error(error);
      }

    // Calling event.completed is required. event.completed lets the platform know that processing has completed.
    event.completed();
}

// You must register the function with the following line.
Office.actions.associate("highlightSelection", highlightSelection);