Monday, May 11, 2015

Manage your customizations with custom JS/CSS without changes

From time to time i see a lot of discussions about the Masterpages, Branding, Styles, Customizations, UI/UX in SharePoint/Office 365...
This article uses examples in my custom environment where i can explain how you can manage branding/styles and Customization changes in my SharePoint/Office 365 Sites and keep the environment regarding Out of the Box "Masterpage/Style files" being untouched, manageable and clean to constant the SharrePoint/Office365 upgrades.

This was done in Test environment, if you need to make change in production please reflect in the impact.

Important and recommend to read before you do something in Branding:

Every time you need to change the branding, think in all the impact and costs you could have and this means $$$ costs, this is the reason people talk about Customization Tax, because if you make changes this could have impact in newer version of your SharePoint/Office365 environment and that means COST.

There is a video from the ignite from Vesa Juvonen about "Deep Dive into Safe SharePoint Branding in Office 365 Using Repeatable Patterns and Practices" and shared in Channel9 explain all the impact and possible cost of changing the Branding and explains what is supported and not with a lot of recommendations.

Here a nice article talking about Branding from Chris O'Brien,

Video from ignite about Branding:

Deep Dive into Safe SharePoint Branding in Office 365 Using Repeatable Patterns and Practices

https://channel9.msdn.com/Events/Ignite/2015/BRK3164

PS: 
A lot of Designers/Dev/PowerUsers already the work with this approach in other ways, for them is not new stuff, but want to show different approaches for the same issues and explain how i work with this type of topic in Office 365 and SharePoint related.  
There is also a SharePoint Property call AlternateCssUrl that could do this trick, 

There is the 5 questions rule you should make your self every time you need to make something (Who, What, Where, When, Why).

It's always better to use Out of the box options and not reinvent the wheel.

Here is the output example of the changes made without changing Out of the Box files.

My Architecture definition for the Branding/Customization

Here is the Architectural View of the approach about Managing Branding/ Styles/ Customizations and functionalities in SharePoint/Office 365 using as base this SharePoint Provider App.


For this example used the 
Processlynx Custom Action and Ribbon Manager (here a Demo of the app in Office Store)

Process for implementation

DEV/Designer
  • This users are responsible to create the Customizations, Styles and functionalities in JS/CSS/images and other support files and include them in a Folder
  • If they have SharePoint Knowledge they should be able to configure the Out of box User Custom Actions provided by that SharePoint Object using UI SharePoint App, 

Site Administrator/PowerUser

  • This users are responsible to Manage the correct reference to Files
  • If they have the SharePoint Knowledge should be able to configure the Out of box User Custom Actions provided by that SharePoint Object using a SharePoint App,
This approach add new UserCustomActions in your SharePoint Webs Object where are located all the references to JS files, this files will manage the new designs styles/functionalities and can be propagated to all site or even site Collection.
Every time a new change is needed the Power User or site Administrator can remove or update the JS Files without the need of changes of OoB files and everything should work because in Background everything is Out of box and can assume the Office 365 Microsoft changes without errors.



Example:
This example explains how to use a JavaScript file to load dynamically a CSS in the header of the SharePoint Site to make the changes in the Styles. 

Creation of AddCSS.JS 

This JavaScript file add dynamically the CSS file "CustomCSS.css" to all headers of the SharePoint site by JQuery.

$(document).ready(function () {
    $("head").append("<link rel='stylesheet' href='" + _spPageContextInfo.webAbsoluteUrl + "/SiteAssets/CustomCSS.css' type='text/css' media='screen'>");
});


Creation of Custom.CSS

/* change the background of Ribbon Area */
.ms-cui-tabBody
{
background-color:#F2F2F2;
}



/* change the background of Left Menu */
.ms-core-listMenu-verticalBox
{
background-color: antiqueWhite !important;
}

/* change the size of contentPlaceholder*/
#s4-workspace{
width:60% !important;
position:absolute;
left: 20%;
}



/* change the background of SharePoint Site */
.ms-backgroundImage{
  background-color:#8CBF26; 
}


/* change the position of OoB SharePoint Search*/
#DeltaPlaceHolderSearchArea{
position:absolute;
left:50%;
top:10%;
}



Here the final CSS:
.ms-cui-tabBody
{
background-color:#F2F2F2;
}
.ms-core-listMenu-verticalBox
{
background-color: antiqueWhite !important;
}
#s4-workspace{
width:60% !important;
position:absolute;
left: 20%;
}
.ms-backgroundImage{
  background-color:#8CBF26; 
}
#DeltaPlaceHolderSearchArea{
position:absolute;
left:50%;
top:10%;
}
Include the files in SharePoint Library
Access to your Office 365 SharePoint and Site Assets library and add the following Files "AddCSS.JS" and "CustomCSS.css"



Add UserCustomAction to SharePoint Site
Using the Processlynx Custom Action and Ribbon Manager you can include your custom User Custom Action to refer your JS files.
Jquery.JS is mandatory to be 1, the second reference should be "AddCSS.JS" because uses JQuery code.


After the JavaScript is included in the SharePoint Object UserCustomAction by the SharePoint App, access to your Site and the changes in the MasterPage and Look and feel will be shown.


If you like to use Visual Studio and Declarative code you can use the option "Generate Declarative XML" to create the XML for your SharePoint Feature as shown.
You can also use JSOM or CSOM to make the same actions.

<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
 <CustomAction Id="Jquery" Title="Jquery" Description="" Location="ScriptLink"ScriptSrc="~Site/SiteAssets/Jquery.JS" Sequence="1" > </CustomAction>
</Elements>

<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
 <CustomAction Id="AddCSS" Title="AddCSS" Description="" Location="ScriptLink"ScriptSrc="~Site/SiteAssets/AddCSS.JS" Sequence="2" > </CustomAction>
</Elements>

To better understand the full power of this approach "
UserCustomAction" about customization's a design and functionality without breaking policies and keep it easily manage by Users for future upgrades:


Hope you like this article, 
André Lage
Post a Comment