SharePoint 2013: Working With Chrome Control And Cross Domain Execution In Provider Hosted Apps

In the new SharePoint 2013 app model, the apps can be hosted in one of the following hosting models: SharePoint Hosted (within SharePoint domain), provided hosted, and auto hosted (outside SharePoint domain).

One of the biggest issues that we can see with the apps running outside the SharePoint domain is the branding, since these apps have separate homes or landing pages than SharePoint and do not follow visual paradigms like navigation menus, back links  to home pages and so on similar to SharePoint.

Intranet users can feel disconnected from the app due to this huge gap in the UI experience.

In order to overcome this obvious issue, SharePoint allows us to import a very basic version of SharePoint 2013 Chrome into their apps without applying the custom CSS styles manually by means of a client side rendering control called “Chrome Control”.

The functional implementation details of this control reside in “SP.UI.Controls.js”file located in the new “/_layouts/15” virtual directory or “Layouts” Folder in 15 Hive.

By now, you must have a fair understanding of Chrome control and now is the time to move on to see it in action.

In order to demonstrate this implementation of Chrome control, we will start with a provider hosted app, as shown in the below steps:

Create a new SharePoint app project by selecting “App for SharePoint” project template.



Choose hosting model as “Provider-Hosted”.



Choose “ASP.Net Web Forms Application” as a template for provisioning the remote site.



Specify the Certificate location, decrypting the password and issuer ID (This ID was generated, while we configure the S2S trust for provider hosted apps),



Once the project has been added to the solution, it would look like this:



I have added a dummy feature to force SharePoint to create an app Web for this app, though this is purely optional, as shown below:



We can review the app Web, using any SharePoint Object Browser. Here, I am using SharePoint Manager to look at the same.



Also, notice that we have changed the start page for the app to “ChromeCrossDomain.aspx”, as highlighted below:



Allowing read permission for the app in site collection hosting it in AppManifest.xml is shown below:



Also, in the remote Web project, we have the pages folder, which contains the pages for our app.



We have “ChromeCrossDomain.aspx” page residing inside this folder, which will serve as a start page for this app, as shown below:



Similarly, we have a Scripts folder, which is holding all JavaScript Files in use by this app, as shown below:

Apart from standard JavaScript Files supporting JQuery, we also have two app specific custom JavaScript files “ChromeLoader.js” and “CrossDomainExecutor.js”,  which is implementing the core of Chrome control for this app, shown below:



In the start page HTML, follow the steps given below:

First, we have to add the “Script” Tags to include custom JavaScript files.

Afterwards, we need to add a “Div” Tag with id = “Chrome_ctrl_container” (you can use any unique value as ID) at the top level, as shown highlighted:



Now, if we explore the code in one of the Custom JS files “ChromeLoader.js”, we can see it as:

Step 1: “getParameterByName” is a helper function, that can be utilized to read the query string parameters from the incoming request.

Step 2: Read the “SPHostUrl” query string parameter to get the handle on host Web

Step 3: Load “SP.UI.Controls.js” file in the context of host Web and once loaded, call “renderChrome” method.

Step 4: Inside “renderChrome” method, we are preparing an object holding the Chrome configuration options.

• appIconUrl: Icon URL, that we need to show at the top header of the app.
• appTitle: Header Title for the app.
• appHelpPageUrl: Help page URL for the app.
• settingsLinks: Links to be shown under settings menu.

Step 5: “SP.UI.Controls.Navigation” method is used to load the Chrome control inside the div with Id = “chrome_ctrl_container” along with the settings applied, based on the “options” object we created in Step 4.

Step 6: The Chrome control that lets SharePoint UX render is visible, which takes precedence over the app defaults.



This is it for loading the Chrome control in our custom app.

Now, let see how we can enable cross domain execution for this app.

If we investigate the other custom JS File “CrossDomainExecutor.js”, we can notice the execution as follows:

Step 1: Getting “SPHostUrl” and “SPAppWebUrl” Query String Parameters using “getParameterByName” method as before. “SPHostUrl” provides the URL of host Web where the app has been installed while “SPAppWebUrl” providedsthe URL of app Web,  which we created during the app installation (by means of Dummy Feature).

Step 2: Getting the reference of “SP.RequestExecutor.js” JS file in context of the host Web, as mentioned earlier. “SP.RequestExecutor.js” is used to execute cross domain calls to SharePoint i.e. the call from SharePoint App (domain 1) to SharePoint (domain 2).

Step 3: Instantiating the context of app Web and instantiating the object of AppContextSite to get the handle on the host Web object. Once it is done, the rest of the things are simply applying JSOM operations.

Step 4: Query announcements list in the host Web and interface its records in the app start page.



Before moving forward, let’s have a look into the announcements list to see what items we have for querying on the app start page.


We can see, there are two items available to be displayed within the app start page.

Build the solution and deploy it.

Trust the security certificate and move on.



Trust the app when asked to and move on.


Provide the credentials for authentication.



We are all set with the final outcome, which can be analyzed as follows:

Step 1: Showing the app URL ensuring we are looking at the start page of the app.

Step 2: Showing app site header image and title fetched by Chrome control from within the host Web context.

Step 3: Showing settings links added during configuring options for the Chrome control.

Step 4: Showing announcement list Items queried from the host Web executed by cross domain request to SharePoint.


So it is evident that by making use of Chrome Control we could save significant efforts in maintaining synch between SharePoint and App UI Designs.