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

apps for Office

Learn how to set up your mail app in the app manifest for the desktop, tablet, and smartphone form factors, using the apps for Office manifests schema version 1.0.

Last modified: June 16, 2014

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

   Office.js: v1.0

   Apps for Office manifests schema: v1.0

In this article
Overview
Specifying the UI in the manifest file
Designing mail apps for OWA for Devices
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.0" 
xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance 
xsi:type="MailApp">

Note that in the above XML line of code, OfficeApp element specifies using version 1.0 of the apps for Office manifests schema. If you are using schema v1.1, see Set up a mail app for Outlook on tablets and mobile devices (schema v1.1).

In schema v1.0, mail apps are activated only when the user is viewing a message or appointment, and open only in the app pane. Depending on the device, you may customize the height of the app pane, but you cannot customize the width. To specify the devices to support, use the DesktopSettings, TabletSettings, and PhoneSettings elements in the XML manifest. You should always specify the DesktopSettings element as the desktop computer is the default device. If you intend your mail app to be used only on a desktop, you can specify just the DesktopSettings element in the XML manifest. For each chosen device, you can decide whether to further customize the user interface, and specify the location of the corresponding HTML file (by using the SourceLocation element) and the desired height of the app pane (by using the RequestedHeight element). Note that while you cannot explicitly specify the hosts for your mail app, specifying device support lets you determine subsets of hosts that are supported on a tablet or smartphone. Table 1 shows for each device, the XML elements to use, the supporting hosts, and the extent of control over the size of the app pane.

Table 1. Specifying devices and the corresponding size of the app pane

Device

XML elements in manifest

Supporting hosts

Height of app pane

Width of app pane

Desktop

DesktopSettings

  • SourceLocation

  • RequestedHeight

Outlook rich client

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

TabletSettings

  • SourceLocation

  • RequestedHeight

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

PhoneSettings

  • SourceLocation

OWA for Android

OWA for iPhone

Outlook Web App

Cannot specify the desired height. Outlook Web App 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 in the Outlook rich client, and can specify only the desired height of the app pane for the desktop and tablet form factors. If you specify a value for the RequestedHeight, the Outlook rich client 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). the Outlook rich client 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, the Outlook rich client 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, the Outlook rich client displays an app pane of up to 450 pixels high.

Specify the UI in the XML manifest file. The following example shows the setting elements (DesktopSettings, TabletSettings, and PhoneSettings) that provide a separate HTML file for each device, and specify the desired height of the app pane on the desktop and tablet devices.

<DesktopSettings>
   <SourceLocation DefaultValue="https://contoso.com/Desktop.html" />
   <RequestedHeight>250</RequestedHeight>
</DesktopSettings>
<TabletSettings>
   <SourceLocation DefaultValue="https://contoso.com/Tablet.html" />
   <RequestedHeight>200</RequestedHeight>
</TabletSettings>
<PhoneSettings>
   <SourceLocation DefaultValue="https://contoso.com/Mobile.html" />
</PhoneSettings>

Specify the TabletSettings and PhoneSettings elements to have your app run on OWA for Devices or Outlook Web App on tablets and smartphones. The following example shows the setting elements that define the location of a mail app that will use the same UI on the desktop and a tablet; the mail app is not supported on a smartphone.

<DesktopSettings>
   <SourceLocation DefaultValue="https://contoso.com/ui.html" />
   <RequestedHeight>200</RequestedHeight>
</DesktopSettings>
<TabletSettings>
   <SourceLocation DefaultValue="https://contoso.com/ui.html" />
   <RequestedHeight>200</RequestedHeight>
</TabletSettings>

You can generally design a mail app the same way regardless of whether it will run on Outlook Web App or OWA for Devices. However, be aware of the following requirements and behavior for OWA for Devices:

  • 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.

  • When the app pane opens on a tablet or smartphone, the item body becomes hidden. To return to the item, the user should close the app.

Show:
© 2014 Microsoft