In this post I will show how to use the JavaScript library code (JavaScript Client Object Model: SP.Runtime.js and SP.js) for easily branding a SharePoint Online team site while respecting the new pattern and practices. This is a third approach compared with the two ones currently recommended by Microsoft for SharePoint Online, that is to mean: NCSSs versus Add-Ins.
I will show in the following tutorial how to easily perform some of the main operations done by the Add-in while avoiding most of the Add-In way complications.
For a complete round regarding the classical approaches, you can visit this post: Branding a SharePoint Online Team Site
You can also read this post that gives a more accurate overview of the recommendations: Latest Advice on Office 365 Branding.
If you read carefully the MSDN documentation (updated August 2015 the 12th) exposing the recommendations regarding the use of the No-Code Sandboxed Solution or NCSS (aka a .wsp containing no server code and deployed in the Solution store at the Site Collection level), versus the use of the SharePoint Add-Ins (formerly called Apps for SharePoint), you can summarize it with the following conclusions:
Microsoft recommends to use Add-Ins whenever you can, but recommends NCCSs for branding as the easiest way to do it.
Regarding the Add-In approach, you can already review the material available on the Office 365 Developer Patterns and Practices:
Video on Channel 19: Alternate CSS and set site logo
Associated source code for the Add-In available on GitHub
You will notice that in the Office 365 Developer Patterns and Practices sample, the Add-In :
Then you can figure out the pros and the cons of these two approaches:
Add-Ins:
2.1 Upload the new logo of the site manually
Use Bing or Google images to find a logo of the Contoso company. Try to find one based on a .gif or a .png with transparency (Contoso-Blue.png is fine).
When it's done, go to the SharePoint Online team site you want to customize (you can easily get a trial environement for 30 days). You need to be administrator of the Site Collection.
Then, create a folder called "images" in the site collection "Style Library" and Upload the Contoso logo image in the folder.
Don't forget to check in the logo image, in order visitors of the site will be able to see it. (if the logo image is checked out, only the administrator of the site will be able to see it).
2.2 Upload the new css of the site manually
Create a file called contoso.intranet.css and paste the following css within the file:
#siteIcon{margin-top:0px;}
#titleAreaBox{margin-top:0px;margin-left:20%;margin-right:20%;background-color:rgba(242, 242, 242, 1);}
#titlerow{background-color:rgba(242, 242, 242, 1);}
.ms-core-listMenu-horizontalBox{margin-top:30px;margin-left:-200px;}
.ms-breadcrumb-box {padding-top: 5px;padding-bottom: 5px;height:30px;}
#SearchBox{margin-left:200px;margin-right:-50px;}
#suiteBarDelta{margin:0px;margin-top:0px;}
#DeltaPlaceHolderSearchArea{padding-top:45px;}
.ms-srch-sb > input {width: 140px;}
Then, create a folder called "css" within the site collection "Style Library", and Upload the file within the "css" folder.
You can see that the .css file has been properly added within the folder, but it is checked out so only administrator will be able to see it. We have to check it in.
2.3 Creating the Site Page for branding the site
Navigate to the "Site Contents" page of your SharePoint Online team site, and locate the "Site Pages" library.
Open the Site Pages library and start creating a new Web Part page.
Call the page "Brand this Site"
The page appears in "edited" mode
Stop editing the page and note that the page was unexpectedly created within the "Site Assets" library.
2.4 Open the Site Page, using WebDAV protocol for modifying the source code
Now we are going to edit the page source code using WebDAV protocol. This is perfectly allowed since you will see in the page properties something called "Open with Microsoft SharePoint Designer".
If you have SharePoint Designer you can now open the page with it. If not, I will show you a trick to edit the page source code using the webDAV protocol with Notepad++. (Note that for me, depending on the machines I am working on, sometimes, clicking on the link "Open with Microsoft SharePoint Designer" while not having SharePoint Designer installed on the machine, leads to open the file in WebDAV protocol within the Notepad!)
Navigate to the Site Assets Library, and within the "Library" Tab of the Ribbon, locate the button called "Open With Explorer".
If you click on this button (be patient it takes time, and sometimes you have 2 warning pop-ups to close, and even to add the SharePoint Online domain in the trusted sites of your Internet Explorer) a Microsoft OS Explorer Window is opening where you can see the SharePoint files! (this is just amazing because actually the SharePoint files are stored, whether in the SharePoint content databases, or just as a link in the content databases pointing to the SharePoint server files system).
Note that this only works with Internet Explorer.
Now you can see the files within a Microsoft Explorer Window, you can as usual, right-click one of them, and choosing the option "Open with", open the file using WebDAV protocol with Notepad, Notepad++ or Visual Studio, or any HTML Code Source Editor of your choice.
2.5 Add Javascript and HTML code to the page in order to change automatically, the Logo, the css and the Master Page of the site.
Now we have to:
First, create a folder called "scripts" in the "Style Library" of the Site Collection and paste in it the jQuery-1.9.1.min.js. You can find this file within an Add'In (App) project created with Visual Studio. Any else jQuery library could be fine however, since we use just basic jQuery features in this tutorial code.
The complete source code of the brand-this-site.aspx Web Part Page and the .ccs file are available @ the dedicated GitHub repositery
Within your .aspx page open in the code source editor with WebDAV protocol, locate the last meta tag at the beginning of the page within "PlaceHolderAdditionalPageHead" section:
<meta name="CollaborationServer" content="SharePoint Team Web Site" />
I will show in the following tutorial how to easily perform some of the main operations done by the Add-in while avoiding most of the Add-In way complications.
For a complete round regarding the classical approaches, you can visit this post: Branding a SharePoint Online Team Site
You can also read this post that gives a more accurate overview of the recommendations: Latest Advice on Office 365 Branding.
1 - Add-ins versus NCSSs
If you read carefully the MSDN documentation (updated August 2015 the 12th) exposing the recommendations regarding the use of the No-Code Sandboxed Solution or NCSS (aka a .wsp containing no server code and deployed in the Solution store at the Site Collection level), versus the use of the SharePoint Add-Ins (formerly called Apps for SharePoint), you can summarize it with the following conclusions:
Microsoft recommends to use Add-Ins whenever you can, but recommends NCCSs for branding as the easiest way to do it.
Regarding the Add-In approach, you can already review the material available on the Office 365 Developer Patterns and Practices:
Video on Channel 19: Alternate CSS and set site logo
Associated source code for the Add-In available on GitHub
You will notice that in the Office 365 Developer Patterns and Practices sample, the Add-In :
- Change programmatically (Imperative approach) the logo and the CSS references for the site
web.AlternateCssUrl = web.ServerRelativeUrl + "/SiteAssets/contoso.css";
web.SiteLogoUrl = web.ServerRelativeUrl + "/SiteAssets/pnp.png";
web.Update();
web.Context.ExecuteQuery();
- Upload programmatically (Imperative approach) the logo and the CSS files for the site
// Use CSOM to upload the file in
FileCreationInformation newFile = new FileCreationInformation();
newFile.Content = System.IO.File.ReadAllBytes(cssFile);
newFile.Url = "contoso.css";
newFile.Overwrite = true;
Microsoft.SharePoint.Client.File uploadFile = assetLibrary.RootFolder.Files.Add(newFile);
web.Context.Load(uploadFile);
web.Context.ExecuteQuery();
// Get the path to the file which we are about to deploy
string logoFile = System.Web.Hosting.HostingEnvironment.MapPath(
string.Format("~/{0}", "resources/pnp.png"));
// Use CSOM to upload the file in
newFile = new FileCreationInformation();
newFile.Content = System.IO.File.ReadAllBytes(logoFile);
newFile.Url = "pnp.png";
newFile.Overwrite = true;
uploadFile = assetLibrary.RootFolder.Files.Add(newFile);
web.Context.Load(uploadFile);
web.Context.ExecuteQuery();
Then you can figure out the pros and the cons of these two approaches:
Add-Ins:
- The pros
- no impacts regarding Microsoft updates:
As Add-Ins are using imperative approach (doing things programmatically) the OOTB templates of SharePoint (Web Part Page Templates, Page Layouts, default.aspx page, Master Pages) are preserved so as any update from Microsoft regarding these templates will have no impacts on the customizations performed using Add-Ins. That is to mean: no custom Master Page anymore, no CAML anymore, ever!
- The branding action could be perform by a super user:
It seems that you can leverage the permission for the users just for the use of the Add-In so as the users to be able to activate the branding of a site themselves without belonging to the Site Collection Administrators.
- no impacts regarding Microsoft updates:
- The cons
- NCSSs are more powerful:
As Add-Ins are using imperative approach (doing things programmatically) and NCSSs can use both imperative (Client side of course with SharePoint JavaScript library code) and declarative approach (modifying HTML, CSS within the custom templates and CAML for deploying and registering these custom templates in the libraries), there are numerous things that you can do with NCSSs that you cannot do using Add-Ins. That is to mean: custom Master Pages, custom pages, with all the HTML and the server controls you want within the custom pages.
- Add-Ins require more time and more knowledge:
Add-In model is completely new and different from classical approaches, thus technical team will have to enhance knowledge to be really comfortable with these new approaches. As said in the MSDN documentation when using Add-Ins remote imperative approach "it would take a considerable amount of work to create this code".
Not only the SharePoint team will be involved, but also people working in the infrastructure and network areas because setting the necessary things regarding network and authentication for getting Add-ins work properly in a company requires also time and knowledge.
- NCSSs are more powerful:
- The Pros
- Although the new Add-Ins model for SharePoint (formerly called Apps) is documented by Microsoft as the the recommended way for customizing SharePoint, you can see in the official MSDN documentation that among the scenarios recommended by Microsoft for using No-Code Sandboxed Solutions instead of Add-Ins (formerly called Apps), Branding of SharePoint Sites is one of them:
[... SharePoint users often want to give their SharePoint sites, including their SharePoint Online sites, a custom appearance with their own colors, styles, layouts, and logos. This is generally easier to do with NCSSs than with SharePoint Add-ins.
...] MSDN SharePoint Add-ins compared with SharePoint solutions
But NCSSs compared with Add-Ins are not only an easier way for branding a SharePoint Online site. Regarding branding, Add-Ins are more limited:
[...
A SharePoint Add-in has declarative control over the appearance of only its own add-in web. For the host web, it can declaratively add only ribbon buttons and menu items (and add-in parts). Any other changes to a host web or its parent site collection, tenancy, or on-premisesSharePoint web application has to be done with code or script that uses one of the SharePoint's client object models. For example, new icons or CSS files would have to be programmatically deployed. This code could be run from the add-in itself after it is installed, or it could run in the add-in installation event handler. But it would take a considerable amount of work to create this code.
In addition, the add-in would need site collection-scoped permissions to change any websites outside its own add-in web and host web, and it would need tenant-scoped permissions to change more than just its parent site collection. A branding NCSS, however, can be deployed and activated to any site collection; and it could consist of only a few purely declarative components.
...] (MSDN)
- Although the new Add-Ins model for SharePoint (formerly called Apps) is documented by Microsoft as the the recommended way for customizing SharePoint, you can see in the official MSDN documentation that among the scenarios recommended by Microsoft for using No-Code Sandboxed Solutions instead of Add-Ins (formerly called Apps), Branding of SharePoint Sites is one of them:
- The Cons
- As your customized pages are not based on a OOTB SharePoint template anymore, if any update of the SharePoint templates is performed by Microsoft, these updates won't be taken into account by your customized page. You will miss new features of the product or maybe even lose current ones depending on the Microsoft updates. So you might perform sometimes unexpected maintenance operations for recovering all the features of the SharePoint product. (it might not be the case with custom master pages based on the use of the Design Manager with which you can convert an.html file into a SharePoint 2013 master page, a .master file. I have to check this more seriously. By the way, I planned to redo the same post using the SharePoint Publishing Features).
- Using NCSS for branding a SharePoint Online team site will require the privileges of Site Collection Administrator and cannot be performed by a super user.
2 - A third approach: using JavaScript Object Model within a Site Page
I will show in the following tutorial how to easily perform some of the main operations done by the Add-in while avoiding most of the Add-In way complications. We will : - Upload the new logo of the site manually
- Upload the new css of the site manually
- Create the page for branding the site manually
- Add Javascript code to the page in order to change automatically, the Logo, the css and the Master Page of the site.
2.1 Upload the new logo of the site manually
Use Bing or Google images to find a logo of the Contoso company. Try to find one based on a .gif or a .png with transparency (Contoso-Blue.png is fine).
When it's done, go to the SharePoint Online team site you want to customize (you can easily get a trial environement for 30 days). You need to be administrator of the Site Collection.
Then, create a folder called "images" in the site collection "Style Library" and Upload the Contoso logo image in the folder.
Don't forget to check in the logo image, in order visitors of the site will be able to see it. (if the logo image is checked out, only the administrator of the site will be able to see it).
2.2 Upload the new css of the site manually
Create a file called contoso.intranet.css and paste the following css within the file:
#siteIcon{margin-top:0px;}
#titleAreaBox{margin-top:0px;margin-left:20%;margin-right:20%;background-color:rgba(242, 242, 242, 1);}
#titlerow{background-color:rgba(242, 242, 242, 1);}
.ms-core-listMenu-horizontalBox{margin-top:30px;margin-left:-200px;}
.ms-breadcrumb-box {padding-top: 5px;padding-bottom: 5px;height:30px;}
#SearchBox{margin-left:200px;margin-right:-50px;}
#suiteBarDelta{margin:0px;margin-top:0px;}
#DeltaPlaceHolderSearchArea{padding-top:45px;}
.ms-srch-sb > input {width: 140px;}
Then, create a folder called "css" within the site collection "Style Library", and Upload the file within the "css" folder.
You can see that the .css file has been properly added within the folder, but it is checked out so only administrator will be able to see it. We have to check it in.
2.3 Creating the Site Page for branding the site
Navigate to the "Site Contents" page of your SharePoint Online team site, and locate the "Site Pages" library.
Open the Site Pages library and start creating a new Web Part page.
Call the page "Brand this Site"
The page appears in "edited" mode
Stop editing the page and note that the page was unexpectedly created within the "Site Assets" library.
2.4 Open the Site Page, using WebDAV protocol for modifying the source code
Now we are going to edit the page source code using WebDAV protocol. This is perfectly allowed since you will see in the page properties something called "Open with Microsoft SharePoint Designer".
If you have SharePoint Designer you can now open the page with it. If not, I will show you a trick to edit the page source code using the webDAV protocol with Notepad++. (Note that for me, depending on the machines I am working on, sometimes, clicking on the link "Open with Microsoft SharePoint Designer" while not having SharePoint Designer installed on the machine, leads to open the file in WebDAV protocol within the Notepad!)
Navigate to the Site Assets Library, and within the "Library" Tab of the Ribbon, locate the button called "Open With Explorer".
If you click on this button (be patient it takes time, and sometimes you have 2 warning pop-ups to close, and even to add the SharePoint Online domain in the trusted sites of your Internet Explorer) a Microsoft OS Explorer Window is opening where you can see the SharePoint files! (this is just amazing because actually the SharePoint files are stored, whether in the SharePoint content databases, or just as a link in the content databases pointing to the SharePoint server files system).
Note that this only works with Internet Explorer.
Now you can see the files within a Microsoft Explorer Window, you can as usual, right-click one of them, and choosing the option "Open with", open the file using WebDAV protocol with Notepad, Notepad++ or Visual Studio, or any HTML Code Source Editor of your choice.
2.5 Add Javascript and HTML code to the page in order to change automatically, the Logo, the css and the Master Page of the site.
Now we have to:
- Reference the JQuery Library.
- Create the code to brand and of course, unbrand the site.
First, create a folder called "scripts" in the "Style Library" of the Site Collection and paste in it the jQuery-1.9.1.min.js. You can find this file within an Add'In (App) project created with Visual Studio. Any else jQuery library could be fine however, since we use just basic jQuery features in this tutorial code.
The complete source code of the brand-this-site.aspx Web Part Page and the .ccs file are available @ the dedicated GitHub repositery
Within your .aspx page open in the code source editor with WebDAV protocol, locate the last meta tag at the beginning of the page within "PlaceHolderAdditionalPageHead" section:
<meta name="CollaborationServer" content="SharePoint Team Web Site" />
and ad the reference to the jQuery library.
Be careful to point to the right location depending of your Site Collection and Site Name. In my case, here is the code of the section within Visual Studio:
Be careful to point to the right location depending of your Site Collection and Site Name. In my case, here is the code of the section within Visual Studio:
<meta name="CollaborationServer" content="SharePoint Team Web Site" />
<!-- Added using WebDAV mode by Marc Charmois --->
<script type="text/javascript" src="/Sites/intranet2/Style%20Library/scripts/jquery-1.9.1.min.js"></script>
<!--script type="text/javascript" src="/_layouts/15/sp.runtime.js"</script-->/script>
<!--script type="text/javascript" src="/_layouts/15/sp.js"</script-->/script>
<!-- end of the WeDAV customization -->
<sharepoint:scriptblock runat="server">
<!--script type="text/javascript" src="/_layouts/15/sp.js"</script-->/script>
<!-- end of the WeDAV customization -->
<sharepoint:scriptblock runat="server">
Then, just below the <asp:Content ContentPlaceHolderID="PlaceHolderMain" runat="server"> opening tag, paste the JavaScript code and replace the paths to the files with the ones corresponding to your SharePoint Online team site:
<asp:Content ContentPlaceHolderID="PlaceHolderMain" runat="server">
<script>
function branding() {
try {
var context = new SP.ClientContext.get_current();
var web = context.get_web();
web.set_masterUrl('/sites/intranet2/_catalogs/masterpage/oslo.master');
web.set_siteLogoUrl('/sites/intranet2/Style%20Library/images/Contoso-Blue.png');
web.set_alternateCssUrl('/sites/intranet2/Style%20Library/CSS/Contoso.Intranet3.css');
web.update();
context.executeQueryAsync(onQuerySucceeded, onQueryFailed);
} catch (error) {
alert(error);
}
}
function unBranding() {
try {
var context = new SP.ClientContext.get_current();
var web = context.get_web();
web.set_masterUrl('/sites/intranet2/_catalogs/masterpage/seattle.master');
web.set_siteLogoUrl('/_layouts/15/images/siteIcon.png?rev=40');
web.set_alternateCssUrl('');
web.update();
context.executeQueryAsync(onQuerySucceeded, onQueryFailed);
} catch (error) {
alert(error);
}
}
function onQuerySucceeded(sender, args) {
alert("The branding of your site was succesfully changed");
window.location = window.location.href;
}
function onQueryFailed(sender, args) {
alert('Request failed. ' + args.get_message() +
'\n' + args.get_stackTrace());
}
</script>
<div class="ms-hide">
Below the <webpartpages:webpartzone control, place the HTML code for the buttons:
<div class="ms-hide">
<webpartpages:webpartzone runat="server" title="loc:TitleBar" id="TitleBar" allowlayoutchange="false" allowpersonalization="false" style="display: none;" />
</div>
<br>
<br>
<a href="JavaScript:branding();" id="brand-button">Brand this site</a>
<br />
<a href="JavaScript:unBranding();" id="unBrand-button">Unbrand this site</a>
<table class="ms-core-tableNoSpace ms-webpartPage-root" width="100%">
Finally, just before the end of the ContentPlaceHolder PlaceHolderMain section paste the code for disabling the button that is useless depending on the site is branded or not:
</table>
<script type="text/javascript">
var logoUrl =$(".ms-siteicon-img").attr('src');
if (logoUrl.indexOf('Contoso') > -1) {
document.getElementById('brand-button').disabled = "disabled";
document.getElementById('brand-button').style.color = "silver";
} else {
document.getElementById('unBrand-button').disabled = "disabled";
document.getElementById('unBrand-button').style.color = "silver";
}
</script>
</asp:Content>
2.6 Testing the page
After having copied the previous code at the right places within the Web Part page and well replaced the paths with the ones corresponding to the right locations of your environment you should obtain this scenario:
When you land on the page for the first time the site is not branded and the "Unbrand this Site" link-button is disabled:
If you click on the "Brand" button, you are soon warned that the customizations were successfully performed:
Then, when you close the Javascript alert pop-up, you are relocated onto the same page, but with the new site branding! And you can also see that the "Brand" button has been disabled while the "UnBrand" button has been enabled.
When you land on the page for the first time the site is not branded and the "Unbrand this Site" link-button is disabled:
If you click on the "Brand" button, you are soon warned that the customizations were successfully performed:
Then, when you close the Javascript alert pop-up, you are relocated onto the same page, but with the new site branding! And you can also see that the "Brand" button has been disabled while the "UnBrand" button has been enabled.
3 - Aknowledgements
