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.

Advertisements

How to start a simple JS application using modules + webpack

It’s been awhile since my last post lots of thing happening in technology it’s amazing how fast technology and particularly the frontEnd development world is changing, well this post will be helpful for those who know a little bit about a javascript and are interested in how to start a modular javascript application at the end of this short tutorial we will developed this to-do list.

Screenshot from 2017-05-17 09:19:46

Complete code will be downloaded here but first of all let’s take a moment to clarify terminology.

Javascript Module is a pattern that allow frontEnd developers to encapsulate functionalities like classes to be reused in different places.

Webpack is a module bundler and basically helps to create a deployable file with all the modules in it, think this is like a compiler that takes all your js modules and create a unique file to be used in your html page.

Needed Software

In order to start with our sample application we will need to install

  • node (https://nodejs.org/en/download/)
  • npm  (once node was installed open a console and run ‘npm install npm -g’)
  • Choose an IDE, personally I’m using visual studio code since a year it works very good.

Let’s play !

First of all you will need to create a folder in your file system next open your IDE and install Webpack using the command npm install webpack -g

Screenshot from 2017-05-11 12:40:47

Now we have all we need to create our sample application, let’s create something simple lets build a todo list with simple actions (task creation, complete task, delete task)

Project Structure

Let’s create the project structure below which will contain our code.

Screenshot from 2017-05-11 12:59:52

Now we need a package.json file which will help us to control the modules we are going to use in our application, lets create it in an automated web using npm, using npm init command  follow the instructions below, you just can leave the default values for each property the command will ask.

Screenshot from 2017-05-11 13:19:43

After that you will notice there is a new file package.json in your project

Screenshot from 2017-05-11 13:21:31

That guy will contain data about our modules, now we can start coding our todo-list application.

Let’s create the view for our application sample, download the code in this link add this code to the index.html file.

Now we are going to create the modules we are going to use, we will have two modules our main module called app.js and other will manage the logic behind the creation of the tasks.

Screenshot from 2017-05-17 09:52:08

App.js

Take a look to the module pattern, basically this pattern allowed us to create elements with an scope detached from the global scope, before start coding we will need to install a jquery as a module in our application.

Screenshot from 2017-05-15 14:43:51

The line above install jquery as a module to be used in our application.

App.js code.

Well finally this is our main module or the entry point of our application, the code is separated in two parts the first one at the top are how we include the modules we are going to use in our module for example with the second line we are include the jquery module and will be able to make a jquery reference through the $ simbol in our module.

The second section in app.js file is the declaration of our module, there you can see a couple of interesting things in it …

  • Maybe if you will think what are those () at the end of the file ? … well those parenthesis  are there in order to  execute the function immediately this is called IIFE pattern (Immediately-Invocked Function expression)  help us to make our code more private and detached of the global scope.
  • What about that return { … } inside the function ? …well that is called a closure and basically allow us to keep couple of variables private like list and tasks array which we don’t want to be accessible out of the scope of our module.

Screenshot from 2017-05-17 10:26:59

task.js

Here you can see basically is the same pattern why applied to the main module and we are using a closure with the return statement as well, we have a render method will be executed each time the user will add a new task and then there is the a method which will attend the remove task button and the complete task button in the view.

Screenshot from 2017-05-17 10:32:48

Finally Webpack  ….

After we did create all our modules and we have all our code in place we are going to use webpack in order to concatenate our modules in to one js file, basically what webpack does to read first the entry point (app.js) read recursively the required lines and start to take each required module and concatenate all them in just one file to be included in our html file, there are two ways to use webpack one with a webpack config file where we define rules to be follow during the concatenation process, but for the sake of the example we are going to use just a command console in order to generate our concatenated file. If you install webpack as I show you at the beginning of the post you will be able to use webpack ./src/app.js bundle.js  command.

Screenshot from 2017-05-17 10:55:26

After run the webpack command you will see an output like in the image above and then a new file called bundle.js in your project file tree.

Screenshot from 2017-05-17 10:59:24

Now with this files in place you will be able to see the to-do list if you call your index.html file, this could be lot of information feel free to download the project here and leave any comment or questions.

Transactional behaviors in Sharepoint

I know some sharepoint developers would say “Are you kidding me ?” when read the title of the post, yes I know sharepoint is not recommended to implement transactional behaviors, this is for particular situations for example Imagine an situation where an action in your form implies to execute three operation at business level, for example image that with a click in a submit button you should to insert a item in a list, update an existing item in another list and finally load a document to document library. Now imagine that you develop this functionality and everything is nice until your QA team makes some nice tests and discover that some times that code is breaking in the last operation, I mean loading the document in the document library, so you notice that the transaction is incomplete and this makes your software unstable. If we were working with a Database get a solution for this issue would be very easy using transactions, rollbacks and commit, but Sharepoint does not support the use of transactions natively.

So Im going to describe the way that our develop team is avoiding this kind of issues. Basically we are emulating transactions using the most simple design pattern we know, the  command pattern. Steps below show how we implement transactions in Sharepoint

Creating a base command clase

The command pattern is one of the most simplest patterns and its based in an interface and our approach with this pattern is to separate all the operations of a transaction in classes that should implement the base interface, using this approach we will have command classes  that are responsible for execute a command and also undo the command if some exception is thrown. Figure 1 show the implementation of the base command class.

Fig. 1

As you can see this interface only has two methods you can add more if you need, for example some times is necessary a validation after execute the command so you can add a method called Validate() to validate something before execute your command, next step is create all the commands, for this example Im going to base my code in the description of the problem at the begin of the post, so Im going to implement the two first commands creation of an item in a list and update an existing list, figure 1 and 2 show how this classes would look.

Commands Implementation

Fig. 2

Fig. 3

Transaction Implementation

The last class is the transaction, this class basically is a command too, the difference with the others is that this command will be responsible for the execution and undo of the commands if is necessary of the other two commands.

Fig. 4

Fig 5.

Fig 4 and 5 is the implementation of the transaction. As you can see the execute method is responsible for the execution of the other commands and after the execution of each command the executed command is stored in an stack this is because if something is wrong and an exception is thrown the undo method of the transaction needs to know what commands have been executed. I really like this approach because is simple and in addition of the undo possibility for a transaction, this approach help to organize the code and makes the code legible and more maintainable, I hope this would help in your SharePoint projects, I will be appreciate any feedback about this approach or another approaches to make SharePoint work with transactions in SharePoint.

Deploying content pages using SharePoint features

Following with the branding topic  in SharePoint 2010 in this post Im going to explain an easy way to deploy content pages using modules and features in sharepoint 2010.

One of the common tasks in SharePoint is the creation of page content, I mean pages based in diferent page layouts, with text, images, media content webparts to show video and soon, in this post Im going to show you how to create a feature that deploy this content pages using the cks dev tools this is a set of templates that could be installed in visual studio 2o1o, cks dev tools came with an important list of templates and tools some of that are templates to create delegate controls, projects templates for create a sharepoint site branding and tools to work with linq-to-sharepoint and tools for deployment, for this post Im going to use a feature of cks dev tools to export the content of a publishing page in a SharePoint Site, we are going to assume that the page exist I mean we are going to assume that the designer finish its work with this page and we are going to proceed to create a feature to install this new page, first of all we need to install the cks dev tools in visual studio, that tools could be download from this url http://visualstudiogallery.msdn.microsoft.com/ee876627-962c-4c35-a4a6-a4d89bfb61dc/

Creating the Project

After download an install the cks dev tools we need to create the project (fig 1), the solution should be created as a farm solution.

fig. 1

Export the content page

As I said in previous lines we are going to assume the contet page exists and lives in the Pages library of in our site, ok to export the page we need to connect our visual studio to the site were the page is located, to do this first click in principal visual studio menu on the option View -> Server Explorer, in the tab that should be open right click on Sharepoint Connections and enter the url of the site where the page is located, after that visual studio add the connection for this site (fig 2).

fig. 2

Now you can see all the structure of the selected site, now the page that we need to package in a feature lives in the pages document library so we should open that library, locate the page we want to package, right click on the page select the option export (fig 3).

fig. 3

After click on the export option an xml file should be appear in our project, this xml file contains all the properties of the publishing page, you can see there the author, editor, etc (fig.4 )

fig. 4

Now we are going to use this metadata to create a module to deploy this page, we need to follow three steps first is download the .aspx content page file from the page library, second we need to create a new module object in our project and third we need to add the downloaded content page file to the module created in second step, our project should looks like fig. 5.

fig. 5

The last step is configure the module with the exported metadata, we need to copy all the tag Module in the xml created by the export option in fig 4, and replace all the tag module in the element.xml module file created in previous step, after that we need to make to changes in the element.xml file in our module first change the property name of the module for publishing which is the correct name of the module, the second step is add the property path of the file tag and set this property with the path of the  .aspx content page in the module (fig 6).

.

fig. 6

After this modifications we can deploy this solution and the content page should be deployed to the page library, we need to have some considerations here one of this considerations is that the page layout attached to the page should exists in the target farm, if your page layout is a custom page layout you need to create a feature to deploy your custom page layout, you can see in my previous post how to do this, in the same way the content type attached to the page layout should exists, in the other hand properties like author could be modified to have coherent values there because it would be possible that the author in source farm does not exists in target farm.

I hope this short post will be helpful.

Deploying page layouts using features in Sharepoint 2010

In this post im going to describe  one of the most useful ways to deploy page layouts. One of the most interesting features in the world of the Sharepoint branding is the possibility to create differents page layouts and apply this page layouts to different pages on a sharepoint site

Page Layouts and Masterpages

First of all is necessary to understand that a page layout and a masterpage are different things, a masterpage is basically the way to apply a different branding (images, colors, background, menus) to a entire site, a page layout is the distribution of sections in a particular publishing page, Sharepoint by default create a couple of page layouts for all new sites as we can see in figure 1, but if you are a serious sharepoint dev there will be a moment when you will need to create a custom page layout to give to your page sites a particular distribution.

fig 1.

Steps to Create a Page Layout Feature Installer

For this post im going to focus in the creation of the feature to deploy the page layout not in the creation of the page layout because of that is the work of the designer but you can see a good step by step:  http://blog.henryong.com/2010/06/08/how-to-create-custom-sharepoint-2010-page-layouts-using-sharepoint-designer-2010/.

1. Creating visual studio project

fig 2.

2. Adding the new feature

Right click in the feature folder and click on new Feature, the new feature should be created at web scope like.

fig 3.

3. Adding the new module

Modules in Sharepoint are the objects that let us to upload files to differents locations in sharepoint like images to document libraries or files to a particular folder in the Sharepoint hive, so we are going to create a new module to upload the page layout to the masterpages gallery, to add the module to the project right click in the project, add new item and select the module item, after add the item to the project it should looks like fig 4.

fig 4.

The new module by default add a new file called sample.txt, we remove that file.

4. Configuring module

The first thing to do with the module is to add the pagelayout file, to do this right click on the module icon an select add existing item, select the pagelayout file to deploy, module should looks like fig 5, in this case my pagelayout is the home.aspx file.

fig 5.

After added the pagelayout file we need to edit the element.xml in the module object, this is the key of the process its a little tricky because of for a page layout module is necessary to define a couple of special properties to get a correct deployment in the gallery, figure 6 show how should be write the content of the xml file

fig 6.

The property with the commas and the sharp is a field that should be filled in that way to tell to the module that the contenttype associated with that masterpage is the Welcome Page the GUID in the field value is the conttype id of the Welcome Page contenttype, it could be possible to use one of the default conttypes in sharepoint but if we need to create pages based in a custom contenttype we could reference our custom contenttype in that field.

5. Deploy the feature

At this point we can deploy the feature and after the deploy if we go to the MasterPage gallery our new page layout should be visible and if we create a new publishing page our new page layout should appear in the list of available pages layouts in the site.

I hope this post will be useful..