SharePoint 2013: Working with Chrome Control and Cross Domain Execution in Provider Hosted App
SharePoint 2013 App Models Hosting
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)
Challenge of Provided Hosted and Auto Hosted
One of the biggest issues that we can see with apps running outside SharePoint Domain is Branding since these apps have got separate Home or Landing Pages than SharePoint and do 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.
Solution
In order to overcome this obvious issue, SharePoint allows importing 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.
Hope up to this point you grasp a fair understanding of 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 shown in below steps:
Create a new SharePoint App Project by selecting “App for SharePoint” project template
https://howtodowithsharepoint.files.wordpress.com/2015/08/117.png?w=300&h=207
Choose Hosting Model as “Provider-Hosted”
https://howtodowithsharepoint.files.wordpress.com/2015/08/215.png?w=300&h=216
Choose “ASP.Net Web Forms Application” as a template for provisioning the Remote Site
https://howtodowithsharepoint.files.wordpress.com/2015/08/34.png?w=300&h=216
Specify the Certificate location, decrypting the password and Issuer ID (This ID was generated while we configure the S2S Trust for Provider Hosted Apps)
https://howtodowithsharepoint.files.wordpress.com/2015/08/44.png?w=300&h=216
Once the Project has been added to the solution it would look like as below:
https://howtodowithsharepoint.files.wordpress.com/2015/08/54.png?w=300&h=172
Add a dummy feature to force SharePoint to create an App Web for this app, though this is purely optional.
https://howtodowithsharepoint.files.wordpress.com/2015/08/64.png?w=300&h=260
We can review the App Web using any SharePoint Object Browser, here we are using SharePoint Manager to look out the same
https://howtodowithsharepoint.files.wordpress.com/2015/08/74.png?w=237&h=300
Also, notice that we have changed the Start Page for the app to “ChromeCrossDomain.aspx” as highlighted below-
https://howtodowithsharepoint.files.wordpress.com/2015/08/84.png?w=300&h=120
Allowing Read permission for the app in Site Collection Hosting it in AppManifest.xml
https://howtodowithsharepoint.files.wordpress.com/2015/08/94.png?w=300&h=112
Also in the Remote Web Project, we have Pages Folder which is containing pages for our app.
https://howtodowithsharepoint.files.wordpress.com/2015/08/104.png?w=300&h=212
We have “ChromeCrossDomain.aspx” page residing inside this folder which will serve as Start Page for this app
https://howtodowithsharepoint.files.wordpress.com/2015/08/118.png?w=300&h=252
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” and “CrossDomainExecutor.js” which is implementing the core of Chrome Control for this app.
https://howtodowithsharepoint.files.wordpress.com/2015/08/124.png?w=300&h=256
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
https://howtodowithsharepoint.files.wordpress.com/2015/08/133.png?w=300&h=107
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 the 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 the 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
https://howtodowithsharepoint.files.wordpress.com/2015/08/143.png?w=300&h=226
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 the 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
https://howtodowithsharepoint.files.wordpress.com/2015/08/153.png?w=300&h=168
Before moving forward let’s have a look at the Announcements List to see what all items we have for query on App Start Page
https://howtodowithsharepoint.files.wordpress.com/2015/08/163.png?w=300&h=145
We can see there are two items available to be displayed on the App Start Page.
Build the Solution and deploy it.
Trust the Security Certificate and move on
https://howtodowithsharepoint.files.wordpress.com/2015/08/173.png?w=300&h=144
Trust the app when asked to and move on
https://howtodowithsharepoint.files.wordpress.com/2015/08/183.png?w=300&h=163
Provide Credentials for Authentication
https://howtodowithsharepoint.files.wordpress.com/2015/08/193.png?w=300&h=135
And we are all set with the 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
https://howtodowithsharepoint.files.wordpress.com/2015/08/203.png?w=300&h=92
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.