Pages

Monday, November 10, 2014

Using SharePoint Chrome Control in APP model


I have been working on building an SharePoint Hosted app for some time now. App as we all know is running in a separate web called app web. The app web does not inherit from the host web for its Styling or user experience. often times we hear that user wants the same user experience as SharePoint. It is actually good for the developers if we could get the SharePoint user experience because it is one less thing that we have to worry about. Users are already familiar with SharePoint user experience and we do not have to train them to use our app.

Getting the Apps to inherit the SharePoint user experience is easier said than done. There is something called Chrome Control that Microsoft exposes in SharePoint. This is the top blue bar that we are now familiar with. The blue bar provides a simple but useful navigation back to the host site from the app site. How many time we have to create either custom navigation or JavaScript code to get this done.




In this pursuit I set out to create a reusable control that help me implement the chrome control that I can just include in my Apps and not worry about writing code.In the recent times I am more than in love with AngularJs. The reason being that Angular lets me write less code which is always better for the developer and the product. So in this blog let's see how we can create the angular based chrome control that we can use in our Apps. Without further ado lets see the code and how we construct it

I am using Office 365 Developer Site to do my development. The approach works and code works pretty much same for on-premise environment as well. The app I have here is SharePoint Hosted app. This works the same way for provider hosted app and auto hosted app as well.


Now create a DIV tag in the HTML file or the default aspx page

 <div data-ng-app="chromecontrol" data-ng-controller="chromecontrolController">
     <div id="chrome_ctrl_container"></div>
</div>


The highlighted div is the container for the chrome control and since I am using angularjs I am surrounding it with the data-ng-app and data-ng-controller attributes to bootstrap my chrome control

Next we will see how we wire the code up

Create a new JS file to define the angular app. I named the file as chromecontrolapp.js

var chromecontrol = angular.module('chromecontrol', []);

I am not passing any other argument to the app and I am just defining what my app will be called which I have specified in the HTML above with data-ng-app attribute.

Next we need to define our controller. For which add another file called

chromecontrolcontroller.js

Code in the controller block

var hostWebUrl, hostWebTitle, hostWebLogoUrl, options;

chromecontrol.controller('chromecontrolController', function ($scope) {

    // get the HostWeb URL, title & logo image
    hostWebUrl = decodeURIComponent($.getQueryStringValue("SPHostUrl"));
    hostWebTitle = decodeURIComponent($.getQueryStringValue("SPHostTitle"));
    hostWebLogoUrl = decodeURIComponent($.getQueryStringValue("SPHostLogoUrl"));

    // create chrome control settings
    options = {
        siteUrl: hostWebUrl,
        siteTitle: hostWebTitle,
        appIconUrl: hostWebLogoUrl,
        appTitle: "Stock Ticker",
        settingsLinks: [
          {
              linkUrl: "../Lists/Stock Symbol",
              displayName: "LIST: Stock Symbol"
          }         
        ]
    };

    // create the chrome control
    var nav = new SP.UI.Controls.Navigation("chrome_ctrl_container", options);

    // show chrome control
    nav.setVisible(true);

    // hide top app chrome (image & app name)
    nav.setBottomHeaderVisible(false);

});


 In the controller block I am defining a global variable  for hostwebURL, hostWebTitle, hostWebLogoUrl, options.

variable options is used to define the items that will be shown when the gear icon is clicked. 

 I do not want to show my site icon and app title hence I am setting the bottomheader to be invisible using the  command

nav.setBottomHeaderVisible(false); 
 One more thing to remember to set in the app is

SPHostTitle={HostTitle}

This needs to be set in the App Manifest so that we can get the Host web title. The standard token do not contain Host title and it only bring APP URL and Host Web URL

The entire source can be downloaded from the GITHub project. For further reference please refer to MSDN