[ARCHIVED] Add-in Command Demo Outlook Add-in

Note: This repo is archived and no longer actively maintained. Security vulnerabilities may exist in the project, or its dependencies. If you plan to reuse or run any code from this repo, be sure to perform appropriate security checks on the code or dependencies first. Do not use this project as the starting point of a production Office Add-in. Always start your production code by using the Office/SharePoint development workload in Visual Studio, or the Yeoman generator for Office Add-ins, and follow security best practices as you develop the add-in.

The Add-in Command Demo add-in uses the commands model for Outlook add-ins to add buttons to the ribbon.

Prerequsites

In order to run this sample, you will need the following:

A web server to host the sample files. The server must be able to accept SSL-protected requests (https) and have a valid SSL certificate.
An Office 365 email account or an Outlook.com email account.
Outlook 2016, which is part of the Office 2016 Preview.

Configuring and installing the sample

Download or fork the repository.
Copy the add-in files to a web server. You have a couple of options:
1. Manually upload to a server:
  1. Upload the AllPropsView, Assets, FunctionFile, InsertTextPane, NoCommands, and RestCaller directories to a directory on your web server.
  2. Open command-demo-manifest.xml in a text editor. Replace all instances of https://localhost:8443 with the HTTPS URL of the directory where you uploaded the files in the previous step. Save your changes.
2. Use gulp-webserver (requires NPM):
  1. Open your command prompt in the directory where the package.json file is installed and run npm install.
  2. Run gulp serve-static to start a web server in the current directory.
  3. In order for Outlook to load the add-in, the SSL certificate used by gulp-webserver must be trusted. Open your browser and go to https://localhost:8443/AllPropsView/AllProps.html. If you are prompted that "there is a problem with this website's security certificate" (IE or Edge), or that "the site's security certificate is not trusted" (Chrome), you need to add the certificate to your trusted root certification authorities. If you continue to the page in the browser, most browsers allow you to view and install the certificate. Once you install and restart your browser, you should be able to browse to https://localhost:8443/AllPropsView/AllProps.html with no errors.
Logon to your email account with a browser at either https://outlook.office365.com (for Office 365), or https://www.outlook.com (for Outlook.com). Click on the gear icon in the upper-right corner.
- If there is a menu item called Manage integrations, follow these steps:
  1. Click Manage integrations.
  2. Click the text Click here to add a custom add-in, then choose Add from file....
  3. Browse to the command-demo-manifest.xml file on your development machine. Click Open.
  4. Review the warning and click Install.
- If there is not a menu item called Manage integrations, follow these steps:
  1. Click Options.
  2. In the left-hand navigation, expand General, then click Manage add-ins.
  3. In the add-in list, click the + icon and choose Add from a file.
  4. Click Browse and browse to the command-demo-manifest.xml file on your development machine. Click Next.
  5. On the confirmation screen, you will see a warning that the add-in is not from the Office Store and hasn't been verified by Microsoft. Click Install.
  6. You should see a success message: You've added an add-in for Outlook. Click OK.

Running the sample

Open Outlook 2016 and connect to the email account where you installed the add-in.
Open an existing message (either in the reading pane or in a separate window). Notice that the add-in has placed new buttons on the command ribbon.

Create a new email. Notice that the add-in has placed new buttons on the command ribbon.

Key components of the sample

command-demo-manifest.xml: The manifest file for the add-in.
FunctionFile/Functions.html: An empty HTML file to load Functions.js for clients that support add-in commands.
FunctionFile/Functions.js: The code that is invoked when the add-in command buttons are clicked.
InsertTextPane/InsertText.html: The HTML markup for the task pane UI displayed by the Insert custom message button.
InsertTextPane/InsertText.js: Code used by the task pane UI displayed by the Insert custom message button.
AllPropsView/AllProps.html: The HTML markup for the task pane UI displayed by the Display all properties button. This is also displayed by clients in read mode that do not support add-in commands.
AllPropsView/AllProps.js: Code used by the task pane UI displayed by the Display all properties button.
NoCommands/NoCommands.html: The HTML file that is loaded and displayed by clients in compose mode that do not support add-in commands.
NoCommands/NoCommands.js: The code that is invoked by clients in compose mode that do not support add-in commands.

How's it all work?

The key part of the sample is the structure of the manifest file. The manifest uses the same version 1.1 schema as any Office add-in's manifest. However, there is a new section of the manifest called VersionOverrides. This section holds all of the information that clients that support add-in commands need to invoke the add-in from a ribbon button. By putting this in a completely separate section, the manifest can also include the original markup to enable the add-in to be loaded by clients that do not support the add-in command model. You can see this in action by loading the add-in in Outlook 2013 or Outlook on the web.

The Add-in Command Demo add-in loaded in Outlook on the web

Read mail form

Compose mail form

Within the VersionOverrides element, there are three child elements, Requirements, Resources, and Hosts. The Requirements element specifies the minimum API version required by the add-in when loaded by clients that support the add-in model. The Resources element contains information about icons, strings, and what HTML file to load for the add-in. The Hosts section specifies how and when the add-in is loaded.

In this sample, there is only one host specified (Outlook):

<Host xsi:type="MailHost">

Within this element are the configuration specifics for the desktop version of Outlook:

<DesktopFormFactor>

The URL to the HTML file with all of the JavaScript code for the button is specified in the FunctionFile element (note that it uses the resource ID specified in the Resources element):

<FunctionFile resid="functionFile" />

The manifest specifies all four available extension points:

<!-- Message compose form -->
<ExtensionPoint xsi:type="MessageComposeCommandSurface">
<!-- Appointment compose form -->
<ExtensionPoint xsi:type="AppointmentOrganizerCommandSurface">
<!-- Message read form -->
<ExtensionPoint xsi:type="MessageReadCommandSurface">
<!-- Appointment read form -->
<ExtensionPoint xsi:type="AppointmentAttendeeCommandSurface">

Within each extension point, there is an example of each type of button.

A button that executes a function

This is created by setting the xsi:type attribute of a Control element to Button, and adding an Action child element with an xsi:type attribute set to ExecuteFunction. For example, look at the Insert default message button:

<!-- Function (UI-less) button -->
<Control xsi:type="Button" id="msgComposeFunctionButton">
  <Label resid="funcComposeButtonLabel" />
  <Supertip>
    <Title resid="funcComposeSuperTipTitle" />
    <Description resid="funcComposeSuperTipDescription" />
  </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>addDefaultMsgToBody</FunctionName>
  </Action>
</Control>

A drop-down menu button

This is created by setting the xsi:type attribute of a Control element to Menu, and adding an Items child element that contains the items to appear on the menu. For example, look at the Insert message button:

<!-- Menu (dropdown) button -->
<Control xsi:type="Menu" id="msgComposeMenuButton">
  <Label resid="menuComposeButtonLabel" />
  <Supertip>
    <Title resid="menuComposeSuperTipTitle" />
    <Description resid="menuComposeSuperTipDescription" />
  </Supertip>
  <Icon>
    <bt:Image size="16" resid="red-icon-16" />
    <bt:Image size="32" resid="red-icon-32" />
    <bt:Image size="80" resid="red-icon-80" />
  </Icon>
  <Items>
    <Item id="msgComposeMenuItem1">
      <Label resid="menuItem1ComposeLabel" />
      <Supertip>
        <Title resid="menuItem1ComposeLabel" />
        <Description resid="menuItem1ComposeTip" />
      </Supertip>
      <Icon>
        <bt:Image size="16" resid="red-icon-16" />
        <bt:Image size="32" resid="red-icon-32" />
        <bt:Image size="80" resid="red-icon-80" />
      </Icon>
      <Action xsi:type="ExecuteFunction">
        <FunctionName>addMsg1ToBody</FunctionName>
      </Action>
    </Item>
    <Item id="msgComposeMenuItem2">
      <Label resid="menuItem2ComposeLabel" />
      <Supertip>
        <Title resid="menuItem2ComposeLabel" />
        <Description resid="menuItem2ComposeTip" />
      </Supertip>
      <Icon>
        <bt:Image size="16" resid="red-icon-16" />
        <bt:Image size="32" resid="red-icon-32" />
        <bt:Image size="80" resid="red-icon-80" />
      </Icon>
      <Action xsi:type="ExecuteFunction">
        <FunctionName>addMsg2ToBody</FunctionName>
      </Action>
    </Item>
    <Item id="msgComposeMenuItem3">
      <Label resid="menuItem3ComposeLabel" />
      <Supertip>
        <Title resid="menuItem3ComposeLabel" />
        <Description resid="menuItem3ComposeTip" />
      </Supertip>
      <Icon>
        <bt:Image size="16" resid="red-icon-16" />
        <bt:Image size="32" resid="red-icon-32" />
        <bt:Image size="80" resid="red-icon-80" />
      </Icon>
      <Action xsi:type="ExecuteFunction">
        <FunctionName>addMsg3ToBody</FunctionName>
      </Action>
    </Item>
  </Items>
</Control>

A button that opens a task pane

This is created by setting the xsi:type attribute of a Control element to Button, and adding an Action child element with an xsi:type attribute set to ShowTaskPane. For example, look at the Insert custom message button:

<!-- Task pane button -->
<Control xsi:type="Button" id="msgComposeOpenPaneButton">
  <Label resid="paneComposeButtonLabel" />
  <Supertip>
    <Title resid="paneComposeSuperTipTitle" />
    <Description resid="paneComposeSuperTipDescription" />
  </Supertip>
  <Icon>
    <bt:Image size="16" resid="green-icon-16" />
    <bt:Image size="32" resid="green-icon-32" />
    <bt:Image size="80" resid="green-icon-80" />
  </Icon>
  <Action xsi:type="ShowTaskpane">
    <SourceLocation resid="composeTaskPaneUrl" />
  </Action>
</Control>

Questions and comments

If you have any trouble running this sample, please log an issue.
Questions about Office Add-in development in general should be posted to Stack Overflow. Make sure that your questions or comments are tagged with office-addins.

Additional resources

Copyright

Connect with me on Twitter @JasonJohMSFT

Follow the Outlook Dev Blog

This project has adopted the Microsoft Open Source Code of Conduct. For more information, see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

OfficeDev/outlook-add-in-command-demo