Event

The event object is passed as a parameter to add-in functions invoked by UI-less command buttons. The object allows the add-in to identify which button was clicked and to signal the host that it has completed its processing.

For example, consider a button defined in an add-in manifest as follows:

<Control xsi:type="Button" id="eventTestButton">
  <Label resid="eventButtonLabel" />
  <Tooltip resid="eventButtonTooltip" />
  <Supertip>
    <Title resid="eventSuperTipTitle" />
    <Description resid="eventSuperTipDescription" />
  </Supertip>
  <Icon>
    <bt:Image size="16" resid="blue-icon-16" />
    <bt:Image size="32" resid="blue-icon-32" />
    <bt:Image size="80" resid="blue-icon-80" />
  </Icon>
  <Action xsi:type="ExecuteFunction">
    <FunctionName>testEventObject</FunctionName>
  </Action>
</Control>

The button has an id attribute set to eventTestButton, and will invoke the testEventObject function defined in the add-in. That function looks like this:

function testEventObject(event) {
  // The event object implements the Event interface

  // This value will be "eventTestButton"
  var buttonId = event.source.id;

  // Signal to the host app that processing is complete.
  event.completed();
}
Requirements
Requirement Value
Minimum mailbox requirement set version 1.3
Minimum permission level Restricted
Applicable Outlook mode Compose or read

Members

source :Object

Gets the identifier of the add-in command button that invoked the method.

The source property returns an object with the following properties.

Property Description
id The value of the id attribute of the Control element that defines the add-in command button in the add-in manifest.

This value can be used when more than one button invokes the same function, but you need to take different actions based on which button was clicked.

Type:
  • Object
Requirements
Requirement Value
Minimum mailbox requirement set version 1.3
Minimum permission level Restricted
Applicable Outlook mode Compose or read
Example
// Function is used by two buttons:
// button1 and button2
function multiButton (event) {
  // Check which button was clicked
  var buttonId = event.source.id;

  if (buttonId === 'button1') {
    doButton1Action();
  else {
    doButton2Action();
  }

  event.completed();
}

Methods

completed([options])

Indicates that the add-in has completed processing that was triggered by an add-in command button or event handler.

This method must be called at the end of a function which was invoked by an add-in command defined with an Action element with an xsi:type attribute set to ExecuteFunction. Calling this method signals the host client that the function is complete and that it can clean up any state involved with invoking the function. For example, if the user closes Outlook before this method is called, Outlook will warn that a function is still executing.

This method must be called in an event handler added via Office.context.mailbox.addHandlerAsync after completing processing of the event.

Parameters:
Name Type Attributes Description
options Object <optional> An object literal that contains one or more of the following properties.
options.allowEvent Boolean <optional> When the completed method is used to signal completion of an event handler, this value indicates of the handled event should continue execution or be canceled. For example, an add-in that handles the ItemSend event can set allowEvent = false to cancel sending of the message.
Requirements
Requirement Value
Minimum mailbox requirement set version 1.3
Minimum permission level Restricted
Applicable Outlook mode Compose or read
Examples
function processItem (event) {
  // Do some processing

  event.completed();
}

In the following example, the checkMessage function has been registered as an event handler for ItemSend.

function checkMessage(event) {
  // Get the item being sent
  var outgoingMsg = Office.context.mailbox.item;

  // Check if subject contains "BLOCK"
  outgoingMsg.subject.getAsync(function (result) {
    // Subject is in result.value
    if (result.value.indexOf('BLOCK') != -1) {
      // Value is found, stop send
      event.completed({allowEvent = false});
    } else {
      // Value wasn't found, allow send
      event.completed({allowEvent = true});
    }
  });
}