CSPP UI Guidelines

  • Article

Important

These guidelines are not exhaustive. Hosts are expected to follow the terms of the Microsoft Cloud Storage Partner Program Integration Terms with respect to Office for the web integration.

Requirements

The following requirements apply to an Office for the web integration.

  1. Don't display any UI on or around the Office editor. The Office for the web editors must always be displayed 'edge-to-edge', with no surrounding UI. The editor cannot be 'light-boxed' or integrated as a component in host UI. The editor is a standalone application.

    The Office for the web viewers can be 'light-boxed' or otherwise embedded in your web experience. However, if the user transitions to a Word, Excel, or PowerPoint editor, the editor must be edge-to-edge.

    Embedding the Office for the web viewers or editors into native applications using a webview is not allowed.

Note

Refer to the support article titled Which browsers work with Microsoft 365 for the web and Microsoft 365 Add-ins for more information on browser support for Office for the web across platforms.

  1. Use Microsoft-provided application and file type icons. For more information, see Application and file type icons.

  2. Provide favicons for the Office applications. Whenever the editor or the viewer are displayed full-window or full-tab, respectively, the favicon for the page must be set to the appropriate favicon. The preferred method is to use the URLs provided in WOPI discovery. For more information, see Favicon URLs.

  3. Use Office application names in UI that activates Office. For example, if you have UI in your application that reads, Open, this UI would read Open in PowerPoint for the web, Open in Office for the web, or Open in Office in a browser. For more information, see the Office Online blog post.

  4. Provide breadcrumb and breadcrumb URL values. Breadcrumbs help users understand where their document is, as well as how to get back to where they were. For more information, see Breadcrumbs.

Other recommendations

While the following guidelines are not required, Office for the web strongly recommends partners do the following:

  1. Provide support for sharing within Office. Office for the web provides a mechanism to share documents with other users directly within the Office for the web applications. You should take advantage of this capability so that users can access sharing controls directly within Office for the web. For more information,see FileSharingPostMessage and FileSharingUrl.

  2. Provide an in-app Edit in Browser button. If you are using the Office for the web viewer and the current user has permissions to edit the document, you should provide a HostEditUrl so that the Edit in Browser button is always displayed. This helps provide a more seamless transition for users.

    Note

    You can also use the EditModePostMessage property to receive a PostMessage when the Edit in Browser button is clicked, so you can handle the transition to edit mode yourself.

  3. Include the document name in the HTML title tag so it displays in the browser tab/window text. This is especially important in cases where users may open multiple documents in different browser tabs/windows.

Application and file type icons

As part of the Cloud Storage Partner Program, Microsoft provides a branding toolkit that includes proper file type and application icons in various sizes, as well as vector-based image formats for re-sizing.

You can find the branding toolkit in the in the Network Resources section of the Office 365 Cloud Storage Partner Program Yammer group.


Important

We update product icons from time-to-time and you are responsible for keeping your WOPI solution up-to-date. Check the branding tookit on a regular basis to ensure your solution remains compliant with the latest CSPP UI requirements.


Use the icons as follows:

  1. When displaying an Office file, either individually or as part of a list of files, use the file type icons. Don't use the application icons for this purpose.

  2. When displaying a button or other UI element that opens an Office for the web application, use the application icons. For example, if you display an Open in Word on the web button, use the Word application icon.


Important

If you re-size or otherwise modify the provided icons, you must use the vector source files to maintain the high image quality of the icons.


Breadcrumbs are an important navigational tool for users. They dramatically improve the user experience by providing helpful anchors so users can both understand where the document they're working on is located and more easily navigate in and out of the Office for the web applications.

WOPI supports two levels of breadcrumbs only:

Set these properties to the root of your navigational hierarchy. A basic rule of thumb is that clicking the breadcrumb takes the user to their logical home within your WOPI host.

In some cases, you might have several different siloed hierarchies within your application. In such cases, it might make more sense to set these properties to the root of the particular hierarchy in which the current document is located.

Ultimately, pick a location most appropriate for your users and application structure.

Set these properties to the container in which the current document is located. A basic rule of thumb is that clicking this breadcrumb takes the user back to the same location they were in prior to opening the document.

Tip

If you support multiple paths to get to a file, you might wish to expose different breadcrumb properties depending on how the user navigated to the file. You can do this by using the session context to customize your CheckFileInfo response.

Example

Consider a logical hierarchy like this:

Documents
├── Reviews
|   ├── Data
|   |   ├── Aggregate Data.xlsx
|   |   └── Raw Data.xlsx
|   └── Monthly Review.pptx
└── Deals
    ├── Integration Plans.docx
    └── Leads.xlsx

In this case, if the user opens Aggregate Data.xlsx, BreadcrumbBrandName/BreadcrumbBrandUrl should be set to Documents, while the BreadcrumbFolderName/BreadcrumbFolderUrl should be set to Data.

Similarly, if the user opens Integration Plans.docx, BreadcrumbBrandName/BreadcrumbBrandUrl should be set to Documents, while the BreadcrumbFolderName/BreadcrumbFolderUrl should be set to Deals.