Deploying a custom sharepoint branding

Featured

Talking with other SharePoint guys about how to deploy and manage in a Sharepoint project the customization of the masterpage or the look and feel in a Sharepoint site I realized that there exists a lot of confusion, specifically about how as a Sharepoint developers we should to develop and deploy the branding for a site, in this post Im going to explain step by step how we should structure our branding project.

We are going to work in our Branding project with four kind of files MasterPage, Images, css and javascript files, these files let to us change the branding of a site and except the masterpage file they should be deployed in some specifically locations under the 14 sharepoint folder, first of all is not a good approach to store these files in document libraries because users could change or delete these files, and other wrong approach is to save those files in the root folder of the site collection that would be good only for the root web site, when we start to create complex structures of subsites it will be a problem the way of reference these files in each mastepage, next Im going to describe each file and the location they should be store.

MasterPage

This is the core file that define the base layout of a site, this file can be access via sharepoint UI /_catalogs/masterpage/Forms/AllItems.aspx, or using Sharepoint Designer /catalogs/masterpage/.

Images

Images that we are going to use in the design of our site should be deployed in \14\TEMPLATE\IMAGES\

Css & js

This kind of file should be store in 14\TEMPLATE\LAYOUTS\INC, that’s because all you put in that folder will be cached, so its a good approach to store there the files that will be access all the time.

Project Structure

Im going to show you how to deploy a new sharepoint branding using a feature this feature would have a web scope, ok first we have to create an empty sharepoint project in visual studio and add two mapping folders Images and INC (fig.1).

Fig 1.

Now we have to add our images in the Images folders and js files and css files in Inc folder, when we deploy our solution all that were added to these folders will be deploy to the folders  \14\TEMPLATE\IMAGES\ and \14\TEMPLATE\LAYOUTS\INC, with this step we will have all our css, js and images in a place that could be access by all our sites and websites in our farm.

MasterPage File

To upload our new masterpage to the site we have to use a sharepoint object called Module, this is because the masterpage lives in a directory that could not be mapped as the Image and Inc folder, so we are going to use the module object this module let to us upload files to a sharepoint locations that does not live in the database and no in the file system like the lists and the _catalog folder, to create a new module in the project we have to right click on project and select the option insert new module (fig 2).

fig 2.

After add the module we have to remove the sample.txt file and add our masterpage file to the module our project should looks like fig (3).

Fig 3.

After that we have to configure the module to add MyMasterPage file in to the masterpages folder in sharepoint to do that we open the elements.xml file and add this code:

<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
	<Module Name="MasterPage"  Url="_catalogs/masterpage">
		<File Path="MasterPage\MyMisterPage.Master" 
                       Url="MyMisterPage.Master" 
                       Type="GhostableInLibrary" 
                       IgnoreIfAlreadyExists="TRUE" />
	</Module>
</Elements>

In code shown below we are loading our MyMisterPage.Master file to the _catalogs/masterpage folder this is the library where sharepoint store all its masterpage files, be aware to set the property type=”GhostableInLibrary” this property should be set to files that are going to be uploaded to a sharepoint library, finally the property IgnoreIfAlreadExists is set to override existing files in the document library with the same name of the file we are uploading.

Finally we have to set our sharepoint feature to set our new masterpage as the default masterpage file to do that we have to create an event reciever to our feature this event reciever let to us add a couple of code lines to set our masterpage as the default masterpage, ok to add a new event receiver to our project right click on the feature and select the option add event reciever vs 2010 will add a new code file to the feature (fig 4).

 Fig 4.

If we check that code we can see that file have a couple methods commented those methods basically are events that will be triggered in a specific moment during the deploy, retract and upgrade of our feature,  we are going to use the method FeatureActivated this method should be triggered after the feature had been deployed, that event is important to us because is the moment when we know that all our files are in the correct folder I mean that event will be triggered after the masterpage, files and images have been uploaded to sharepoint, so we should uncomment the FeatureActivated method and add this code:

public override void FeatureActivated(SPFeatureReceiverProperties properties)
{
var currentWeb = (SPWeb)properties.Feature.Parent;
var urlSite = new Uri(currentWeb.Url +
“/_catalogs/masterpage/MyMasterPage.master”);
currentWeb.MasterUrl = urlSite.AbsolutePath;
currentWeb.CustomMasterUrl =
urlSite.AbsolutePath;
currentWeb.Update();

   }

The code shown bellow just get a reference of the current website the website where the feature is been activated as we know our feature has a web scope we can take a spweb reference trough  the feature parent line 1, next lines get the path of our masterpage file deployed and set that masterpage file the default masterpage for the web where our feature is been activated, after follow steps bellow we have a feature that install our customized masterpage, an aditional step as a good practice will be add code in the event FeaturedeActivating to set the old masterpage as default masterpage of the web when our feature been deactivated, I hope this post will be helpful.