SharePoint 2010: Deploying Custom Branding Files – Part 1

Wow, it sure has been a long time since I last blogged. Nearly 5SPBrandingBook months! Part of the reason for the long hiatus is that most the of words I’ve written since my last blog post have been dedicated to a few different SharePoint 2010 book – but most specifically Professional SharePoint 2010 Branding and UI Design from Wrox.  If you’ve preordered the book or watching it on Amazon, first off thank you very much! Second, the publish date has been bouncing all around but I’m happy to report that the last chapters have been completed and we are pretty much just waiting for the printing presses to put ink on paper. If you’ve preordered the book, it shouldn’t be too much longer.  If you haven’t preordered the book you should – it has a motorcycle on the cover! I’m very excited about the book because I think it will speak to anyone and everyone looking to customize the SharePoint UI. Whether you are need basic help changing the look and feel or your site or you are trying to create an extremely custom design this book will help you out.

Enough of the shameless plug, but the reason I mention it is because one of the topics I cover in the book is around deploying custom branding files.  How should you do it and why? This is a fairly large topic but in this post I’m going to focus on some of the higher level issues and then dig deeper in later posts.

What is deployment?

Others may think about it differently, but to me deployment is simply how you get files into SharePoint. Often people associate SharePoint Solutions and Features (will discuss below) with deployment and while that is true, deploying files can be done manually too.  Ultimately, that’s the big decision point many have – “how should I deploy my files?”

What are the options for deploying my files?

If we wanted to get really technical there’s probably a lot more ways, but I’m going to break down the deployment options into three categories:

1) Manual Deployment: The act of deploying files by using SharePoint Designer or manually uploading them through the SharePoint UI.

2) Features and Solutions: If you aren’t familiar with SharePoint features and solutions at least on a basic level you should be. Although they have relatively generic names they refer to very specific capabilities in SharePoint. Solutions are a type of sealed cabinet (.CAB) file which has the extension of .WSP. In fact, if you have a SharePoint solution and change the extension to .CAB you can take a look at the contents inside – little troubleshooting tip that can be useful. Solutions are a way to move files around and get them physically to where they need to be in an organized way. For SharePoint 2010 there are two types of solutions: farm and sandboxed.  Farm solutions behave the same way solutions behaved in SharePoint 2007 – they deploy files to file system of the SharePoint server. To be more specific – the actual source of the files lives on the server file system similar to how all of the system files are deployed. Sandboxed solutions are deployed at the site collection level and the source of their files actually resides in the content database. There’s a lot more to the topic of solutions and a lot more you can do with them other than deploy branding files, but to avoid this post from becoming a book itself, I’m going to leave the description very high level.

SharePoint features are the mechanism that actually puts your files into SharePoint or performs the specific functionality you’ve defined.  A feature itself is comprised of a feature.xml file which has a schema that defines some basic things like title, description, has a unique identifier, the scope at which it can be activated, as well as references to assemblies (custom code you’ve written that will be run when the feature is activated), or references to manifest files which themselves are just files written in an XML-like language called CAML that define how and where certain files will be put in SharePoint. Again, the topic of features a massive one so I’m just scratching the surface.

3) Custom site definitions: When you create a site collection, the site definition itself is what defines it.  It can get a little confusing, but in this case the term “site” is actually referring to site collection.  A site definition itself is primarily made of a file called onet.xml and like a feature it is written in CAML. So when you actually go to create a new site collection, you choose a template from Central Administration and SharePoint goes and looks at the corresponding site definition to determine what features and files get deployed. One more time, I’ll mention custom site definitions are a big topic and just staying high level.

Which option should you choose?

Like with most technical discussions the answer is “it depends” – but what are the decision points? The biggest issue is going to be around whether to deploy your files in an uncustomized or customized state. Essentially the difference is going to be that files that are uncustomized all point back to a single source file.  Changes can be applied to that single file which could impact many places where that file is referenced.  Conversely, customized files are unique instances of a file.  This concept can get a little tricky to describe, and I’m planning a follow-up blog post to help clarify further.  Until then, for more information on the subject take a look at Andrew Connell’s article on TechNet called Understanding Customized and Uncustomized Files in WSS v3.  Most of the concepts still apply.  But consider that files deployed out of the box by SharePoint are all uncustomized and it would be possible to update an out of the box master page like v4.master and have the changes be applied to every site that uses v4.master.  (DISCLAIMER: That was just an example to demonstrate a concept – don’t modify system files! If you need to make a copy first!)

Of the deployment options described above, #1 deploys files in a customized state. #2 and #3 deploys files in an uncustomized state.  Keep that in mind as you read the rest of the post.

Your project is small and not very complex

If the project is very simple and the site is relatively low traffic then deploying manually will be just fine. But if you’d consider the project to be more complex or you aren’t sure then I’d suggest one of the other methods.  In other words, if you project is very simple deploying files in a customized state is probably fine.  But for even mildly complex projects deploying files in an uncustomized state is likely the better option.

For most projects – the next best option is to deploy files as a sandboxed solution

Sandboxed solutions have several advantages when it comes to branding. First off, most branding files such as master pages, page layouts, CSS, and images don’t require a DLL or assembly or anything else that would require they be deployed with full trust to the server.  This means that SharePoint admins don’t need to get involved with deploying sandboxed solutions – it just makes the deployment process easier.  Since there’s a limit to what can run in the sandbox there’s naturally much less risk to the farm so that is a great thing.  Another thing to consider is that if you are in a hosted model, whether internally or in the cloud, this might be the only option you have!

The biggest downside to deploying files via a Sandboxed Solution is that they are isolated to a single site collection.  So if you had a very large project and wanted to deploy your branding across several site collections then you’d either have to deploy the same sandboxed solution over and over again (which doesn’t sound like the best idea if you can avoid it) or you should consider a farm solution.

Farm solutions offer the most power and flexibility – but also require higher permission levels

For large projects that involve deploying consistent branding across multiple site collection farm solutions are going to be the way to go.  For example you could update a single master page file which would in turn apply those updates to every site collection where that master page is being used.  So if you had a corporate branded master page used across 10 site collections you could update one file and all of your sites would get updated.  Additionally, a farm solution might be required if you are deploying something else that can’t operate in the sandbox.

However, like solutions in SP2007, farm solutions in SP2010 need to be deployed by a farm administrator – which isn’t really a bad thing it just means that you are going to have to follow a few more steps every time you need to deploy something.  Which shouldn’t be a big deal if this is a bigger implementation; hopefully you’d be taking the proper steps to ensure that you are testing everything you deploy anyway!

What about custom site definitions?

They are definitely an option but personally I’m not a big fan except in very specific circumstances. My preference would be to evaluate what’s possible by using solutions and features.  If you still aren’t happy make sure you read this blog post from Eric Shupps called Site Definitions – the Good, the Bad, and the Ugly.

Quick summary:

Deploying files is all about how do you get your files onto your server, which option is best for you?

1) If your project is really small and simple, then manual deployment is probably fine.

2) Try to use sandboxed solutions the first choice if you need more than manual deployment. There are some limitations to deploying files as a sandboxed solution…

3) If sandboxed solutions are too limiting for your needs then a farm solution is likely the way to go but does require farm administrator permissions to deploy.

4) Custom site definitions are an option for very specific scenarios, but read up before going down that path to make sure you do it correctly!

What’s next? This is part 1 isn’t it? One might assume there will be a part 2.

In the next post I’ll be talking about the methodology that I typically use for deploying branding files.  Specifically, where do we deploy files to in SharePoint and why?

Stay tuned!