Building a host page

In order to instantiate the Office Online applications, a host must create an HTML page that will host an iframe element within it pointing to a particular WOPI action URL. A host page provides a number of benefits, including:

  1. Since the Office Online application is hosted within a host page, the host page can communicate with the frame easily using PostMessage. This allows a richer integration between the host and Office Online.
  2. URLs displayed in the user’s browser are host URLs. This means that from a user’s perspective, they are interacting with the host, not Office Online. This also ensures that URLs that are copied and pasted by users are host URLs, not Office Online URLs.

The host page is typically very simple; it must meet only the following requirements:

  • It must use a form element and POST the access token and access_token_ttl values to the Office Online iframe for security purposes.
  • It must include any JavaScript needed to interact with the Office Online iframe using PostMessage.
  • It must manage wd* query string parameters.
  • It must apply some specific CSS styles to the body element and Office Online iframe to avoid visual bugs.
  • It must declare a viewport meta tag to avoid visual and functional problems in mobile browsers.

Host page example

The Office Online GitHub repository contains a minimal example host page. Note that it does not illustrate managing wd* query string parameters or Using PostMessage to interact with the Office Online application iframe. The sections below will refer to it in more detail.

Passing access tokens securely

It is important, for security purposes, that access tokens not be passed to the Office Online iframe as a query string parameter. Doing so would greatly increase the likelihood of token leakage. To avoid this problem, hosts should pass the access token and access_token_ttl values to the Office Online iframe using a form POST. This technique is illustrated, along with dynamic iframe creation, in code sample 1.

Working around browser iframe behavior

Some browsers exhibit strange behavior with iframes when using bookmarks or the browser forward/back buttons. In some cases, this will cause the Office Online iframe to be loaded twice in a single navigation. This in turn can cause ‘file locked’ or ‘access token expired’ errors for users. In addition, sometimes the iframe is not recreated at all, which causes the Office Online application to load with the previous session’s state. This may cause a session to ultimately fail for a variety of reasons, including an expired CSRF token.

In order to work around this behavior, hosts should dynamically create the Office Online iframe using JavaScript, then dynamically submit it. This technique is illustrated in the sample host page:

Code sample 1 Markup from SampleHostPage.html illustrating how to dynamically create the Office Online iframe and pass access tokens securely
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
<body>

<form id="office_form" name="office_form" target="office_frame"
      action="<OFFICE_ONLINE_ACTION_URL>" method="post">
    <input name="access_token" value="<ACCESS_TOKEN_VALUE>" type="hidden"/>
    <input name="access_token_ttl" value="<ACCESS_TOKEN_TTL_VALUE>" type="hidden"/>
</form>

<span id="frameholder"></span>

<script type="text/javascript">
    var frameholder = document.getElementById('frameholder');
    var office_frame = document.createElement('iframe');
    office_frame.name = 'office_frame';
    office_frame.id ='office_frame';

    // The title should be set for accessibility
    office_frame.title = 'Office Online Frame';

    // This attribute allows true fullscreen mode in slideshow view
    // when using PowerPoint Online's 'view' action.
    office_frame.setAttribute('allowfullscreen', 'true');

    frameholder.appendChild(office_frame);

    document.getElementById('office_form').submit();

Note that in an actual implementation, the <OFFICE_ONLINE_ACTION_URL>, <ACCESS_TOKEN_VALUE>, and <ACCESS_TOKEN_TTL_VALUE> strings should be replaced with appropriate action URL, access token, and access_token_ttl values.

Passing through wd* parameters

Office Online will sometimes pass additional query string parameters to your host page. These query string parameters are of the form wd*. When you receive these query string parameters on your host page URLs, you must pass them, unchanged, to the Office Online iframe.

In addition, if the replaceState method from the HTML5 History API is available in the user’s browser, you should remove the following parameters from your host page URL after passing them to the Office Online iframe:

  • wdPreviousSession
  • wdPreviousCorrelation

Other wd* parameters must not be removed from the host page URL.

Applying appropriate CSS styles

To ensure that the Office Online applications behave appropriately when displayed through the host page, the host page must apply some specific CSS styles to the Office Online iframe (lines 22-33) and the body element (lines 15-20) as well as set a viewport meta tag for mobile browsers (lines 11-12). In addition, the host page should set an appropriate favicon for the page using the favicon URL provided in WOPI discovery.

All of these requirements are illustrated in the sample host page:

Code sample 2 Markup from SampleHostPage.html illustrating appropriate styles and favicons in a host page
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
<head>
    <meta charset="utf-8">

    <!-- Enable IE Standards mode -->
    <meta http-equiv="x-ua-compatible" content="ie=edge">

    <title></title>
    <meta name="description" content="">
    <meta name="viewport"
          content="width=device-width, initial-scale=1, maximum-scale=1, minimum-scale=1, user-scalable=no">

    <link rel="shortcut icon"
          href="<OFFICE ONLINE APPLICATION FAVICON URL>" />

    <style type="text/css">
        body {
            margin: 0;
            padding: 0;
            overflow:hidden;
            -ms-content-zooming: none;
        }

        #office_frame {
            width: 100%;
            height: 100%;
            position: absolute;
            top: 0;
            left: 0;
            right: 0;
            bottom: 0;
            margin: 0;
            border: none;
            display: block;
        }
    </style>
</head>