Building a host page
In order to instantiate the Office Online applications, a host must create an HTML page that will host an
element within it pointing to a particular :ref:`WOPI action URL <WOPI Actions>`. A host page provides a number of
- Since the Office Online application is hosted within a host page, the host page can communicate with the frame easily using :ref:`PostMessage <PostMessage>`. This allows a richer integration between the host and Office Online.
- 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
formelement and :http:method:`POST` the :term:`access token` and :term:`access_token_ttl` values to the Office Online iframe :ref:`for security purposes <Passing access tokens securely>`.
- It must manage :ref:`wd* query string parameters <wd Parameters>`.
- It must apply some specific CSS styles to the
bodyelement and Office Online iframe to avoid visual bugs.
- It must declare a
viewportmeta 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 :ref:`wd* query string parameters <wd Parameters>` or :ref:`PostMessage`. 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 must pass the :term:`access token` and :term:`access_token_ttl` values to the Office Online iframe using a form :http:method:`POST`. This technique is illustrated, along with :ref:`dynamic iframe creation<iframe behavior>`, in :numref:`code sample %s <secure-tokens-sample>`.
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 :abbr:`CSRF (Cross-Site Request Forgery)` token.
.. literalinclude:: ../../../samples/SampleHostPage.html :caption: Markup from `SampleHostPage.html`_ illustrating how to dynamically create the Office Online iframe and pass access tokens securely :name: secure-tokens-sample :language: html :linenos: :lineno-match: :lines: 39-64
Note that in an actual implementation, the
<ACCESS_TOKEN_TTL_VALUE> strings must be replaced with appropriate :ref:`action URL<Action URLs>`,
:term:`access token`, and :term:`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:
wd* parameters must not be removed from the host page URL.
Host page headers
If the host page headers are not correctly set, some browsers may cache the response which can result in the host page not properly reloading when the user navigates to it. This can result in errors if the user reloads a cached page after the :term:`access token`, or :term:`access_token_ttl` have expired. One way this can happen is by reloading the page using the forward/back buttons. For more information about cache management refer to RFC 7234.
To prevent this, at the very least, the following headers should be set on the host page.
- :http:header:`Cache-Control`: no-cache, no-store
- :http:header:`Expires`: -1
- :http:header:`Pragma`: no-cache
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 :ref:`favicon URL provided in WOPI discovery <favicons>`.
All of these requirements are illustrated in the sample host page:
.. literalinclude:: ../../../samples/SampleHostPage.html :caption: Markup from `SampleHostPage.html`_ illustrating appropriate styles and favicons in a host page :language: html :linenos: :lineno-match: :lines: 3-38 :emphasize-lines: 9-10, 12-13, 16-21, 23-34