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
Choose Hosting Model as “Provider-Hosted”
Choose “ASP.Net Web Forms Application” as template for provisioning the Remote Site
Specify the Certificate location, decrypting 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 as below:
I have added a dummy feature to force SharePoint to create an App Web for this App, though this is purely optional.
We can review the App Web using any SharePoint Object Browser, here I am using SharePoint Manager to lookout the same
Also notice that we have changed the Start Page for App to “ChromeCrossDomain.aspx” as highlighted below-
Allowing Read permission for the App in Site Collection Hosting it in AppManifest.xml
Also in the Remote Web Project we have Pages Folder which is containing pages for our App.
We have “ChromeCrossDomain.aspx” page residing inside this folder which will serve as Start Page for this App
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
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
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
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
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
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
Trust the App when asked to and move on
Provide Credentials for Authentication
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
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.
by Prashant Bansal via Everyone's Blog Posts - SharePoint Community
No comments:
Post a Comment