Using the Chrome Control in SharePoint 2013 Apps
In the new SharePoint 2013 App model, there are essentially two ways to host apps – within SharePoint itself or from an external web site (also known as "provider hosted" or "autohosted"). One of the disadvantages of external apps is that they don’t look or feel like SharePoint. All the familiar navigation menus and shortcuts are missing, resulting in a stark contrast between the default SharePoint visual experience and whichever app is currently being used unless the app developer went the extra mile (or ten) to style their app.
While this isn’t really a bad thing – the app is fully functional and can communicate with SharePoint – it doesn’t quite lend itself to a cohesive user experience. To bridge this gap, Microsoft allows developers to import a very basic version of the SharePoint 2013 chrome into their apps without having to manually create matching HTML controls. The functionality for this can be found in the SP.UI.Controls.js file located in the new /_layouts/15 directory. To use the chrome control, first add a reference to SP.UI.Controls.js (make sure you’ve already loaded the requisite JQuery files and other dependencies), then add an empty <div> to your page markup at or near the top of the page:
Note that the hostWebUrl variable is set with a call to decodeURIComponent that passes a function – getQueryStringParameter(string) – as a parameter. This is simply a helper function (with no relation to the navigation code) that parses out the host URL value as there are several variants for the host URL that can be set in the app.manifest file (and any number of custom parameters). The code for this function looks for the provided key and returns the appropriate value, like so:
The values in the ‘options’ object aren’t required but are helpful in decorating the chrome. In this example, the rendered HTML will include the host site name along with the app name and links back to the SharePoint site using the hostWebUrl value. Although these are hardcoded in the example, they could also be dynamically set in the code behind of the page after client context is established via TokenHelper, stored in hidden fields, and read into the control when the options object is created. When the app is executed, functions in the Chrome script call back to the host web, extract the themed markup, and render it within the designated control, as seen in the following snippet:
As you can see, the output is rather rudimentary. If you were expecting a full reproduction of the SharePoint 2013 UI you will be sorely disappointed. There’s just enough markup to establish a visual connection to the site the app was launched from – no more, no less. But, at least it’s a start; perhaps in the future we’ll gain deeper access into the host site design elements. For more information on the Chrome control, refer to the following MSDN article: http://msdn.microsoft.com/en-us/library/fp179916(v=office.15).aspx.