Developing Mobile Document Viewers

Applies to: SharePoint Foundation 2010

This topic describes how you can create mobile pages that host document viewers that enable users to view on their mobile device documents in the format of particular applications, such as word processor or spreadsheet applications. This enables mobile end users to open files in Microsoft SharePoint Foundation document libraries on their mobile device. Some mobile devices may have a built-in viewer for the type of document. You can configure the response system to check whether the requesting device has such a viewer and, if it does, optionally let the requested document be opened in the device’s browser instead of your browser.

Overview

There are two major parts to making a mobile document viewer available to users of your SharePoint Foundation solution:

• Create the page that hosts the viewer.

• Register the viewer page.

Create the Viewer Hosting Page

A mobile viewer hosting page is typically an .aspx file that you deploy to the %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\14\TEMPLATE\Layouts\Mobile folder on each front-end web server. No absolute generalizations about the contents of the page can be made. The heart of the page is typically a reference to a control that can display a document of the specified type. There may also be controls to enable editing, paginating, or other functionality relevant to the document type.

Register the Page

To register the page, you create an XML file named mdocview_*.xml, where the * is some string of valid file name characters. We recommend that you use your company name or some other string that is not likely to duplicate the name used by other document viewer providers. The page is deployed to %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\14\Config on all front-end web servers.

The top node of the file is a MobileDocViewers element. Add at least one child MobileDocViewer element. The following is an example of a MobileDocViewer element:

<MobileDocViewers>
  <MobileDocViewer Name="xps" FilePath="/_layouts/mobile/mxps.aspx" QueryId="doc" AppendSourceUrl="true" />

</MobileDocViewers>

The Name attribute identifies the file name extension of the type of files that the viewer can display. The FilePath attribute identifies the website-relative path and file name of the file that you created to host the viewer. The QueryId attribute specifies the key of the URL query; in this case, "?doc=" is appended to the end of the URL for your viewer-hosting page. The AppendSourceUrl attribute specifies whether the URL of the document that the user wants to view should be appended to the end of the URL. In this case, because the value is true, the URL is appended. Accordingly, the complete website-relative URL to view a file named File.xps in the document library at http://MyServer/Shared Documents/File.xps would be /_layouts/mobile/mxps.aspx?doc=http:%2F%2FMyServer%2FShared%20Documents%2FFile%2Exps.

We recommend that you package your page as a Feature that can be activated or deactivated at the site collection level. If you do this, your MobileDocViewer element also has a FeatureId attribute that identifies the Feature by GUID. The following is an example.

<MobileDocViewers>
  <MobileDocViewer Name="xps" FilePath="/_layouts/mobile/mxps.aspx" QueryId="doc" AppendSourceUrl="true" 
                   FeatureId="XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX" />

</MobileDocViewers>

If the viewer can open documents that have more than one kind of file name extension, add a separate MobileDocViewer element for each extension.

If the requesting device has its own viewer for the type of document that your viewer opens, the compat.browser file located in %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\14\CONFIG\Browsers can have an entry for the browser that indicates this capability. For example, a Windows Mobile 7.0 telephone has an Office Mobile Client that can open certain Microsoft Office document types on the mobile phone. The entry for this client in compat.browser is shown here.

<browser id="OfficeMobileClient" parentID="default">
  <identification>
    <userAgent match="^Office Mobile Web Access$" /> 
  </identification>
  <capabilities>
    <capability name="isMobileDevice" value="true" />
    <capability name="overrideMobileDocViewerRedirection" value="true" />
  </capabilities>
</browser>

The capability element named overrideMobileDocViewerRedirection is set to true. This means that this browser can view certain Microsoft Office document types.

You can let a browser’s own viewer override your viewer by adding a child BrowserCondition element to the MobileDocViewer element. The BrowserCondition element checks whether the requesting device has its own browser and, if it does, redirects the request from your viewer hosting page to some other request handler. For example, the following MobileDocViewer specifies that .docx files are opened in the mWord.aspx file. However, if the browser has its own viewer, the request is diverted to MobileDocHandler.ashx instead.

<MobileDocViewer Name="docx" FilePath="/_layouts/mobile/mWord.aspx" FeatureId="8DFAF93D-E23C-4471-9347-07368668DDAF" QueryId="doc" AppendSourceUrl="true" >
  <BrowserCondition Id="overrideMobileDocViewerRedirection" Value="true">
    <Override FilePath="/_layouts/MobileDocHandler.ashx" AppendSourceUrl="false" />
  </BrowserCondition>
</MobileDocViewer>

Do not reuse the term overrideMobileDocViewerRedirection for your capability name, because that capability refers to the Office Mobile Client viewer. Instead, create a term to use. For example, if a type of browser has an XPS viewer, you can add an entry for that browser to the compat.browser file and give it a capability element with a CanViewXPS as the value of the name attribute. Then add a BrowserCondition child element to your MobileDocViewer element, and use CanViewXPS as the value of the Id attribute.

See Also

Concepts

Mobile Development with SharePoint Foundation

Building Block: Mobile Pages, Controls, and Adapters