page_type	products	languages	extensions
sample	office-outlook office-365	javascript	contentType technologies createdDate samples Add-ins 8/21/2015 10:55:59 AM

Outlook-Add-in-Commands-Translator

The Translator add-in uses the commands model for Outlook add-ins to add a button to the ribbon in the new message form. The button sends the selected text from the message body to a translator web service to translate from English to Russian.

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. You can join the Office 365 Developer Program and get a free 1 year subscription to Office 365.
• An API key for the Yandex Translate API.
• Outlook 2016, which is part of the Office 2016 Preview.

Configuring and installing the sample

1. Download or fork the repository.
2. Open TranslateHelper.js in a text editor and replace the YOUR API KEY HERE value with your API key for the Yandex Translate API. Save your changes.
3. Upload the AppCompose, Content, and Images directories to a directory on your web server.
4. Open TranslateAppManifest.xml in a text editor. Replace all instances of YOUR_WEB_SERVER with the HTTPS URL of the directory where you uploaded the files in the previous step. Save your changes.
5. 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, then click Manage add-ins.

1. In the add-in list, click the + icon and choose Add from a file.

1. Click Browse and browse to the TranslateAppManifest.xml file on your development machine. Click Next.

1. 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.
2. You should see a success message: You've added an add-in for Outlook. Click OK.

Running the sample

1. Open Outlook 2016 and connect to the email account where you installed the add-in.
2. Create a new email. Notice that the add-in has placed a Translate button on the command ribbon.

1. Type some English text into the body. Select the text, then click Translate.

1. After a moment, the selected text will be replaced with the Russian translation, and you should see the message Translated successfully in the information bar.

Key components of the sample

• TranslateAppManifest.xml: The manifest file for the Translator add-in.
• AppCompose/FunctionFile/Home.html: An empty HTML file to load Translator.js for clients that support add-in commands.
• AppCompose/FunctionFile/Translator.js: The code that is invoked when the add-in command button is clicked.
• AppCompose/Home/Home.html: The HTML file that is loaded and displayed by clients that do not support add-in commands.
• AppCompose/Home/Home.js: The code that is invoked by clients that do not support add-in commands.
• AppCompose/TranslateHelper.js: Common code used by both Translator.js and Home.js.

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 (currently only Outlook 2016) 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 in a task pane under the original compose mode add-in model. You can see this in action by loading the add-in in Outlook 2013 or Outlook on the web.

The Translator add-in loaded in Outlook on the web

Within the VersionOverrides element, there are two child elements, Resources and Hosts. 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 also limits activation to the new message form by setting a single extension point:

<ExtensionPoint xsi:type="MessageComposeCommandSurface">

The properties of the button are specified in the Control element. Most importantly, the button's click event is connected to the translate function in Translator.js inside the Action element:

<Action xsi:type="ExecuteFunction">
    <FunctionName>translate</FunctionName>
</Action>

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

• Outlook Dev Center
• Office Add-ins documentation on MSDN
• More Add-in samples

Copyright

Copyright (c) 2015 Microsoft. All rights reserved.

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.