SharePoint 2013 : Working with Chrome Control and Cross Domain Execution in Provider Hosted App

In the new SharePoint 2013 App model, the Apps can be hosted in one of the following hosting model: SharePoint Hosted (with in SharePoint Domain), Provided Hosted and Auto Hosted (Outside SharePoint Domain).

One of the biggest issue that we can see with Apps running outside SharePoint Domain is Branding, since these Apps has got separate Home or Landing Pages than SharePoint and does not follow Visual Paradigms like Navigation Menus, Back Link to Home Page and so on similar to SharePoint.

Intranet Users can feel disconnected with the App due to this huge gap in UI Experience.

In order to overcome this obvious issue SharePoint allows to import a very basic version of SharePoint 2013 Chrome into their Apps without apply 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.

Hope up to this point you grasp a fair understanding in Chrome Control and now it is 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 show in below steps:

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

1

Choose Hosting Model as “Provider-Hosted”

2

Choose “ASP.Net Web Forms Application” as template for provisioning the Remote Site

3

Specify the Certificate location, decrypting password and Issuer ID (This ID was generated while we configure the S2S Trust for Provider Hosted Apps)

4

Once the Project has been added to the solution it would look like as below:

5

I have added a dummy feature to force SharePoint to create an App Web for this App, though this is purely optional.

6

We can review the App Web using any SharePoint Object Browser, here I am using SharePoint Manager to lookout the same

7

Also notice that we have changed the Start Page for App to “ChromeCrossDomain.aspx” as highlighted below-

8

Allowing Read permission for the App in Site Collection Hosting it in AppManifest.xml

9

Also in the Remote Web Project we have Pages Folder which is containing pages for our App.

10

We have “ChromeCrossDomain.aspx” page residing inside this folder which will serve as Start Page for this App

11

Similarly we have 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” & “CrossDomainExecutor.js” which is implementing the core of Chrome Control for this App

12

In the Start Page HTML –

Firstly we have to add the “Script” Tags to include custom Javascript Files

Then 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

13

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

Step 1 – “getParameterByName” is a helper function that can be utilized to read 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 context of Host Web and once loaded call “renderChrome” method

Step 4- Inside “renderChrome” method, we are preparing 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 settings applied based on the “options” object we created in Step 4

Step 6- Visible the Chrome Control and let the SharePoint UX rendering takes precedence over the App defaults

14

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” provided the Url of App Web which we got created during the App Installation (by means of Dummy Feature).

Step 2- Getting the reference of “SP.RequestExecutor.js” JS file in context of Host Web as 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, 4, 5- Instantiating the context of App Web and instantiating the object of AppContextSite to get the handle on Host Web object. Once it is done rest of the things are simply applying JSOM operations

Step 6- Query Announcements List in Host Web and interface its records in the App Start Page

15

Before moving forward let’s have a look into the Announcements List to see what all items we have for query on App Start Page

16

We can see there are two items available to be displayed with in the App Start Page.

Build the Solution and deploy it

Trust the Security Certificate and move on

17

Trust the App when asked to and move on

18

Provide Credentials for Authentication

19

And we are all set with final outcome which can we analyzed as below:

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

20

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.

Hope you find it helpful.

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s