Customizing the SharePoint Chrome Control in LightSwitch

If you’ve done any LightSwitch apps for SharePoint you may have noticed that we incorporate a version of the SharePoint chrome control.  You may not have known what it was (or what it was called), but you do now.  You can also customize it and I’ll show you how.  I’m also going to cover a few things like navigating to the home page or retrieving the current user, things that apply to non-SharePoint apps as well.

The chrome control is just a little frame at the top of your app that by default let’s you jump quickly back to the SharePoint site that launched the app.  Here’s the quick & easy app we created in a previous post called “CustEdit” – you can see the chrome control was put in for us automatically.  It also matches the color theme of the SharePoint site the app was launched from – that may or may not be what you want but we’ll cover that in another post.  For now we just want to add a little more than what the default provides. 

We’ll add:

• A Home button that will take the user to the home page of the app
• A button that will take the user back to the SharePoint site
• The current user’s name and a link to the “my site”
• A “Sign Out” link

Let’s get started.

Add createSharePointChrome Function

LightSwitch will create the chrome for you but if it finds a declared JavaScript function called createSharePointChrome() then LightSwitch will use that to render the chrome control instead.  The frame of the control will remain the same but you can change the contents to whatever you want.  So the first thing we need to do is create this function and make it part of our project. Taking our CustEdit example, perform the following steps:

• In Solution Explorer, switch to File View and then Show all Files
• Expand the CustEdit.HTMLClient node, right-click on the UserCode node and select Add>New item…
• Add a new javascript file and name it customchrome.js
• Open up the default.htm file in the code editor and add a reference to the script file:

<script type="text/javascript" src="UserCode/customchrome.js">script>

Open up the customechrome.js file and declare the function:

function createSharePointChrome(element, spUrl) {//create the links we need for the chrome on O365}

• Press F5 and run your app – you should see an empty chrome.  That means LightSwitch found your empty function.

Now, we need some code to render the buttons.  The image I want to use for the SharePoint site, I’ll just pull from SharePoint itself.  For the home button I want to use the SharePoint app icon that’s part of the SharePoint project.  To add that, I’ll just create a link to that png file from the SharePoint project to the Server project.  Also, I customized my SharePoint appicon, but you don’t have to do that for this work, the default will work just fine.  The key here is that the SharePoint project will want an icon that is 96x96.  So if you don’t want to create one, just use the default.

To use a new icon:  (skip past this stuff to the next set of bullets if you want to use the default icon)

• Still in File View, right-click the CustEdit.SharePoint project node and select Add > Existing item…
• Browse to your 96x96 png file and add it to your project
• Open the appmanifest.xml file in the SharePoint project
• In the Icon text box browse to the png file you added

Now create the link to the file in the server project:

• Right-Click on the CustEdit.Server project and select Add >Existing Item…
• Browse to the CustEdit.SharePoint project on disk, and select the icon you want to use (mine is custedit.png the default is AppIcon.png)
• Click the arrow next to the Add button in the File Open dialog and select Add as link

You’ll now see a reference to the png file in the server project.  If you ever change that file in the SharePoint project, it will be automatically updated in the Server Project.  If you change the icon to another file, you’ll need to repeat those steps. So now you have this:

Next let’s add code to the createSharePointChrome() function:

//add the links$("" +"+"src='../custedit.png'" +"" +"style='margin-left: 4px; margin-right: 4px; padding: 4px;'" +"src='" + spUrl + "/_layouts/15/images/favicon.ico'").appendTo(element);//use the built-in LightSwitch method for the home page $(".home-link", element).click(function () {
    msls.application.navigateHome();
});

Press F5 to run the app and you’ll see the two image links in the chrome.  If you used the default appicon, then of course yours will be different.

Getting the User Name on the Server in the HTML Client

Now we want to add the current user name to the chrome.  We’ll also throw in the “Sign Out” link.  Note that this isn’t specific to SharePoint apps, any HTMLClient may want to use this technique.  We’ll use AJAX to call into the LightSwitchApplication on the server which has easy access to this information.

The first thing we need to do is add a generic http handler to our server.  Right-click on the CustEdit.Server project node in Solution Explorer.  Select Add>New item…– scroll down to find the Generic Handler and name it GetAppInfo.ashx.  In the code editor add the following snippet in the ProcessRequest sub.

VB:

Sub ProcessRequest(ByVal context As HttpContext) Implements IHttpHandler.ProcessRequestUsing serverContext = LightSwitchApplication.ServerApplicationContext.CreateContext()Using spContext = serverContext.Application.SharePoint.GetHostWebClientContext()
            spContext.Load(spContext.Web)
            spContext.ExecuteQuery()

            context.Response.ContentType = "text/plain"context.Response.Write(spContext.Web.Title)
            context.Response.Write(",")
            context.Response.Write(serverContext.Application.User.FullName)End Using
    End Using
End Sub

C#:

public void ProcessRequest(HttpContext context)
{using (ServerApplicationContext serverContext = 
           LightSwitchApplication.ServerApplicationContext.CreateContext())
    {using (Microsoft.SharePoint.Client.ClientContext spContext = 
               serverContext.Application.SharePoint.GetHostWebClientContext())
        {
            spContext.Load(spContext.Web);
            spContext.ExecuteQuery();

            context.Response.ContentType = "text/plain";
            context.Response.Write(spContext.Web.Title);
            context.Response.Write(",");
            context.Response.Write(serverContext.Application.User.FullName);
        }
    }            
}

This response will give us the user’s name and the “friendly” name of the SharePoint site that launched the app.  We could use the name of the site for a link or some alt text (as in this example), regardless it shows you a way to use the SharePoint CSOM from the client.  Now that we have the handler in place, we need some AJAX to call the handler.  This will still be part of our createSharePointChrome() function.  Let’s just replace what we have now with the entire snippet below.

function createSharePointChrome(element, spUrl) {//create the links we need for the chrome on O365var mySite = spUrl.replace(".sharepoint", "-my.sharepoint")var i = mySite.indexOf(".com") + 4;
    mySite = mySite.substring(0, i) + "/person.aspx";var signoutUrl = spUrl + "/_layouts/15/signout.aspx";var UserName;//call the code on the server$.ajax({
        type: 'GET',
        data: {},
        url: '../GetAppInfo.ashx',
        success: function success(response) {var n = response.split(",");
            myHostWebName = n[0];
            UserName = n[1];//add the links$("" +"+"src='../custedit.png'" +"" +"+"style='margin-left: 4px; margin-right: 4px; padding: 4px;'" +"src='" + spUrl + "/_layouts/15/images/favicon.ico'").appendTo(element);//use the built-in LightSwitch method for the home page $(".home-link", element).click(function () {
                msls.application.navigateHome();
            });//right side links$("
" +"+ "style='padding-top:2px' class='msls-sharepoint-chrome-link ui-link' " +"target='_blank' href='" + mySite + "'>" + UserName + " | " +"" +"Sign Out
").appendTo(element);
        }
    });
}

And now your chrome should look like this:

That’s it!  Now you know:

• what the chrome is
• how to customize the chrome with some images
• how to change the SharePoint app icon
• how to use the Home Page function the LightSwitch HTML client library
• how to use AJAX to call into the LightSwitch application and SharePoint CSOM on the server

Hope this helps, your comments are always welcome.

Brian Moore - Program Manager, LightSwitch