Export (0) Print
Expand All

Set up a mail app for Outlook on desktops, tablets and mobile devices (schema v1.1)

apps for Office

Learn how to set up your mail app in the app manifest to work on a desktop, tablet, or smartphone, using the apps for Office manifests schema version 1.1.

Last modified: November 12, 2014

Applies to: Exchange Online | Exchange Server 2013 SP1 | Outlook 2013 RT | Outlook 2013 SP1 | Outlook Web App | OWA for Devices

   Office.js: v1.1

   Apps for Office manifests schema: v1.1

Note Note

In this article, "Outlook" refers to Outlook for Windows, Outlook RT, OWA for Devices, and Outlook Web App. This article doesn't apply to Outlook for Mac. At this point, Outlook for Mac supports JavaScript API for Office in only Outlook read mode, and can activate mail apps that reference office.js version 1.0 or 1.1 and use apps for Office schema version 1.0.

In this article
Overview
Customizing source files per form type
Customizing app pane dimensions per form type
Tips for designing mail apps for desktops, tablets and smartphones
In this section
Additional resources

One of the design pillars for apps for Office is write-once. For mail apps, this means you can create and run an app on a desktop, tablet, or smartphone device without necessarily customizing the HTML and JavaScript for each device. The JavaScript API for Office works seamlessly across these devices. You can choose the devices to support, and depending on the user interface design of the mail app, decide whether to customize the user interface for each of the selected devices.

A mail app runs on desktop, tablet and smartphone

The flexibility to customize the user interface for specific devices is afforded by the MailApp type in the app manifest:

<OfficeApp xmlns="http://schemas.microsoft.com/office/appforoffice/1.1" 
xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance 
xsi:type="MailApp">

Note that in the above XML line of code, the OfficeApp element specifies using version 1.1 of the apps for Office manifests schema. If you have an existing mail app that uses schema v1.0, see Set up a mail app for Outlook on desktops, tablets and mobile devices (schema v1.0). To find out more about the different versions, see Choosing a version of the platform for your mail app for Outlook

Starting in schema v1.1, you can have mail apps activated when the user is composing or viewing a message or appointment. If your mail app supports both a compose scenario and read scenario, you would likely use different objects and members in the JavaScript API for Office and provide different user interface for each scenario, hence you should provide separate source files for the mail app for each scenario. Any customization of the mail app for devices (desktop, tablet or smartphone) also depends on whether the app is activated in a compose form or read form.

To specify the source files for a mail app in the app manifest:

  1. Insert the FormSettings and Form elements.

  2. For each type of form (compose or read) that your app supports, use the xsi:type attribute to specify ItemEdit or ItemRead as appropriate.

  3. For each type of form, specify the devices that your app supports using the corresponding DesktopSettings, TabletSettings, and PhoneSettings elements. You should always include the DesktopSettings element because the desktop computer is the default device. Note that even though you cannot explicitly specify the hosts for your mail app, specifying device support lets you determine subsets of hosts that can host your app on a tablet or smartphone. For example, specifying support on a tablet means OWA for iPad, Outlook RT, and Outlook Web App can be hosts for your app.

  4. For each supported form type and device, specify the location of the corresponding HTML file by using the SourceLocation element. While you should provide distinct source files for compose and read scenarios, within a given scenario, you can choose whether or not to further customize the user interface for each device and provide distinct source files for the supported devices, or simply use the same source file for all the devices.

For example, if you intend your mail app to be used on the desktop and tablet devices in a compose scenario, you can use the same source file and specify the DesktopSettings and TabletSettings elements in the app manifest as shown below.

<FormSettings>
  <Form xsi:type="ItemEdit">
    <!-- Compose scenario.                    -->
    <!-- Use the same source for each device. -->
    <DesktopSettings>
      <SourceLocation DefaultValue=
        "https://<domain>/source_compose.html" />
    </DesktopSettings>
    <TabletSettings>
      <SourceLocation DefaultValue=
        "https://<domain>/source_compose.html" />
    </TabletSettings>
  </Form>
</FormSettings>

When activated in a compose form, a mail app opens in a vertical app pane; Outlook adjusts the height and width of the app pane dynamically, and you cannot customize either dimension. Table 1 shows the XML elements that you can use in the app manifest when specifying source files for various devices in a compose scenario. When activated in a read form, a mail app opens in a horizontal app pane. For the desktop and tablet devices, you can use the RequestedHeight element to customize the height. You cannot customize the width of the app pane. Table 2 shows the XML elements to use to specify source files and any app pane customization per device in the read scenario.

Elements for compose scenario

The following table lists the XML elements that you can use to specify source files for each device in a compose scenario. You can specify these elements under the FormSettings element in the app manifest.

Table 1. Specifying source files per device in a compose scenario

Device

XML elements in manifest

Supporting hosts

Height of app pane

Width of app pane

Desktop

Outlook for Windows

Outlook Web App

Cannot specify the desired height.

Cannot specify the desired width.

Tablet

OWA for iPad

Outlook RT

Outlook Web App

Cannot specify the desired height.

Cannot specify the desired width.

Smartphone

OWA for Android

OWA for iPhone

Outlook Web App

Cannot specify the desired height. The app pane uses the entire screen of the smartphone.

Cannot specify the desired width.

Elements and app pane customization for read scenario

The following lists the XML elements and the kind of customization you can apply to the app pane for each device in a read scenario. You can specify these elements under the FormSettings element in the app manifest.

Table 2. Specifying source files and app pane customization per device in a read scenario

Device

XML elements in manifest

Supporting hosts

Height of app pane

Width of app pane

Desktop

Outlook for Windows

Specify the desired height using RequestedHeight under DesktopSettings.

Cannot specify the desired width.

Outlook Web App

Specify the desired height using RequestedHeight under DesktopSettings.

Cannot specify the desired width. Outlook Web App uses a 3-column layout.

Tablet

OWA for iPad

Outlook RT

Outlook Web App

Specify the desired height using RequestedHeight under TabletSettings.

Cannot specify the desired width. The host uses a 2-column layout.

Once the app pane opens on a tablet, the item body is no longer visible.

Smartphone

OWA for Android

OWA for iPhone

Outlook Web App

Cannot specify the desired height. The app pane uses the entire screen of the smartphone.

Cannot specify the desired width. The host uses a single-column layout. Once the app pane opens, it occupies the entire screen of the smartphone. The item body is no longer visible.

You do not have control over the width of the app pane, and can specify only the desired height of the app pane for the desktop and tablet form factors. If you specify a value for RequestedHeight, Outlook for Windows determines the height of the app pane to be the lesser of that value and 50% of the height of the Reading Pane or inspector window of that item (whichever is applicable). Outlook for Windows also observes the following limits for the height of an app pane:

  • The minimum height for an app pane is 32 pixels. If the RequestedHeight element is set to less than 32 pixels, Outlook for Windows displays an app pane that is 32 pixels high.

  • The maximum height for an app pane is 450 pixels. If the RequestedHeight element is set to more than 450 pixels, Outlook for Windows displays an app pane of up to 450 pixels high.

Example

The following example supports both compose and read scenarios, and for each scenario, provides a separate source file for each device. It also customizes the default height of the app pane in the read scenario for the desktop and tablet devices.

<FormSettings>
  <Form xsi:type="ItemEdit">
    <!-- Compose scenario allows customizing source -->
    <!-- files, but not app pane dimensions.        -->
    <DesktopSettings>
      <SourceLocation DefaultValue=
        "https://<domain>/source_compose_richclient.html" />
    </DesktopSettings>
    <TabletSettings>
      <SourceLocation DefaultValue=
        "https://<domain>/source_compose_tablet.html" />
    </TabletSettings>
    <PhoneSettings>
      <SourceLocation DefaultValue=
        "https://<domain>/source_compose_phone.html" />
    </PhoneSettings>
  </Form>
  <Form xsi:type="ItemRead">
    <!-- Read scenario allows customizing source -->
    <!-- files and height of app pane except on  -->
    <!-- the smartphone.                         -->
    <DesktopSettings>
      <SourceLocation DefaultValue=
        "https://<domain>/source_read_richclient.html" />
      <RequestedHeight>350</RequestedHeight>
    </DesktopSettings>
    <TabletSettings>
      <SourceLocation DefaultValue=
        "https://<domain>/source_read_tabet.html" />
      <RequestedHeight>250</RequestedHeight>
    </TabletSettings>
    <PhoneSettings>
      <SourceLocation DefaultValue=
        "https://<domain>/source_read_phone.html" />
    </PhoneSettings>
  </Form>
</FormSettings>

You can generally apply the JavaScript API for Office in a mail app the same way regardless of the devices it will run on. You may want to pay attention to the UI design and interaction on different devices though. The following are some tips for displaying an item or opening a pop-up box:

  • You can use the JavaScript window.open method to open pop-up boxes in your mail app.

  • Properly encode characters in a URI when specifying the URL argument for window.open.

  • You can use window.open to display an item in the user’s mailbox. To do that:

    • Call the Exchange Web Services GetItem operation to get a URL in the WebClientReadFormQueryString element. The URL is typically of this format:

      https://<somedomain>/owa/#viewmodel=ReadMessageItem&ItemID=<someValidID>&ispopout=1
      
    • Remove the query string &ispopout=1, if it exists.

    • Concatenate the resultant URL with the OWA endpoint and provide it as the input parameter to window.open.

Mail apps that activate in read forms on tablets or smartphones

Be aware that when the app pane opens on a tablet or smartphone, the item body becomes hidden. To return to the item, the user has to close the app.

Mail apps that activate in compose forms on tablets or smartphones

Be aware that when the app pane opens on a tablet or smartphone, the item body may or may not be visible:

  • If the tablet is in landscape orientation, the item body and app pane are adjacent to each other.

  • If the tablet is in portrait orientation, or if the app pane is opening on a smartphone, the item body becomes hidden. To return to the item, the user has to close the app.

Also, if you're creating a compose app that supports tablets or smartphones, note that currently iOS touch devices (iPads, iPhones) do not always automatically provide the user a vertical scroll bar if the content in the app pane is longer than the height of the iframe. Follow the guidelines below to enable proper vertical scrolling on such devices:

  • In the CSS for your mail app, style the html element with height:100%.

  • Define the body element as follows:

    • height: 100%

    • overflow-y: auto

    • And to support inertial scrolling, -webkit-overflow-scrolling: touch

Show:
© 2014 Microsoft