CleverWorkarounds » CSS

SharePoint Branding Part 7 -The ‘governance’ of it all..

admin — Tue, 13 Nov 2007 17:16:49 +0000

Well, here we are! After delving into dark arts where everybody but metrosexual web designers fear to tread (HTML and CSS), we then delved into the areas that metrosexual web designers truly fear to tread (packaging, deployment and even some c# code!). Finally, we get to the area where everybody is interested until it happens to get in their way! (Ooh, I am a cynical old sod tonight).

That is Governance!

May I start by quoting from that wise band “Faith No More” and their first hit “We Care A Lot”, who in 1987 were of course thinking of collaborative document management when they wrote..

“We care a lot about the gamblers and the pushers and the geeks
We care a lot about the crack and smack and whack that hits the street
We care a lot about the welfare of all the boys and girls
We care a lot about you people cause we’re out to save the world

And it’s a dirty job but someone’s gotta do it”

Now, we are only going to talk about governance in relation to branding here, which is really a pimple on the butt of the overall governance of SharePoint. In saying that though, much of the philosophical basis from which I write this article is pretty much applied to the other areas of SharePoint governance anyhow.

So, what are we trying to do anyway? If you go and google or wikipedia the subject of governance, you can pretty much summarise the academic definition as “cover your ass”! Whether you are answerable to the CEO of a blue chip with a billion dollar market cap, or to the CEO of a 25 user small business, if you are going to take the fall, you want to make sure you take a few others with you, right?

Therefore, one of the first governance issues to deal with is the fact that we need a team with well defined roles and responsibilities. Each team will cover off different areas of SharePoint governance that can broadly be grouped into a few different categories:

Project Management
Infrastructure
Development/Design
Operation
Training

Now, you may group things a little differently then me, but you get the idea. I have deliberately NOT listed design (and with it branding) separately because it depends on the type of SharePoint project being implemented. If it is a web content management oriented project (like an internet site), then design probably warrants its own category. However, if it is a collaborative project, then design is quite likely part of development process.

I think this point deserves further consideration.

WCM vs Collaborative Sites

SharePoint is a multipurpose beast. It can be used as a straight out CMS system and compete with the likes of Joomla, Drupal, RedDot and EpiServer. It can also be used as a document management system, management reporting tool, project tracking system, collaboration platform and so on and so forth…

When used as a CMS only, it’s pretty good, all things considered. There are some pretty snazzy examples of WCM sites that make you stop and think, “wow – is that SharePoint?”. But the typical visitor to a WCM based SharePoint site will not likely be using many of the other goodies that SharePoint offers. In these type of sites, there are a few content authors, but mostly the people using the site are visitors consuming the web content. Really, that’s about it.

But if you have been reading this series of articles, I spent the first three talking about how much of a pain the core.css and application.master issue is on corporate branding. If you haven’t, I suggest taking a look.

The issue is that many aspects of collaborative functionality use parts of SharePoint that is tough to brand. Cameron Moll has written a brilliant article on this issue and I consider it mandatory reading. Many collaborative functions are based on a central master page called APPLICATION.MASTER. Therefore, if you have made a well branded master page for your content, the user experience will be inconsistent when they perform certain administrative type tasks.

Cameron nails the issue perfectly here: “This is all perfectly fine in the CMS scenario, as only an infinitesimal fraction of your users will switch between published screens and admin screens. However, in the collaboration scenario, nearly any user can, and will, switch between published screens and admin screens to complete tasks. Because your skinning won’t be reflected in the admin, what should otherwise be a continuous visual flow for users instead becomes a jarring transition from your beautiful theme to SharePoint’s vanilla theme and back again”.

Now this entire series of articles has been based on the ‘other’ side of SharePoint (i.e. *not* WCM). In my opinion, in a purely collaborative SharePoint implementation, branding should be one of the last things you do. Your time is better spent refining collaborative functionality. However if you are doing WCM, it should be one of the first things to do.

You can imagine then, that the worst case scenario for all involved in a SharePoint project is mixing WCM and collaboration. It carries with it the exact same type of problems and risks that I outlined in my article on collaborative document management vs records management. Try and do both, and you will not only dilute the benefits of each, but you end up with an over time/budget process with plenty of pissed users and stakeholders.

Moral of the story? Decide what you want to be!

So let’s move on.

Best Practice Standards

A while back, I posted a series of articles on best practice methodologies and the laws around compliance. For many areas of governance, much of the work is done for you by these best practice standards. Certainly, aspects of the ITIL books on ICT change management, deployment management, design and planning and operations management will factor in branding governance.

I hope for people who have read those articles wondering why I included my four articles in a SharePoint oriented blog, you should see it all start to come together now. They are your philosophical starting point to approaching SharePoint governance

For what it’s worth, although ITIL is currently flavour of the month for many IT departments, I think that you can get a lot out of ISO27000/27001 and COBiT as well. ITIL is very inwards facing in a lot of its subject areas. What I mean by that is that non IT Senior management and board level tend not to give a crap about ITIL, but are likely to have more of an interest in COBiT, particularly in the US (not just because it has prettier pictures either). COBiT is a much “higher level” standard than ITIL, and is a better philosophical starting point than ITIL which is more prescriptive. In reality the standards well complement each other, but if you are wondering which one to start on, I’d go with COBiT. (Another much more detailed post on SharePoint governance against these standards is in the works).

It’s a dirty job but someone’s gotta do it

So let’s start with some high level governance principles for branding a collaborative SharePoint site. Here is what we need to define and document.

A management structure for supporting the development and deployment of branded MOSS Sites
Key roles and responsibilities within this structure
Policies, standards, guidelines, and decision processes required to support the deployment of branded SharePoint Sites

What are the rationales for setting up a framework to assign accountabilities?

Knowing who is responsible for making decisions
Knowing how decisions are made
Knowing who is responsible for implementing decisions

In addition to this, branding governance aims to:

Consistently provide a high quality user experience by ensuring that the branding governance plan is followed
Establish clear decision making authority and escalation criteria so that issues are resolved on a timely basis
Ensure compliance with established corporate style guide

Roles and Responsibilities

ISO27000/27001 puts a big emphasis on accountability. Without a strong culture of accountability, it is very difficult to adopt governance without it getting out of hand. One organisation I worked for had mapped out their process for dealing with the service desk and it was too big for an A4 sized page. It had to be printed on poster size and was the ugliest flowchart you have ever seen. This is a common symptom when clear lines of accountability do not exist. There is safety in complexity and ambiguity.

Thus, it is vitally important that the right roles are assigned the right responsibilities and people are fully aware of where their accountability lies.

The following table is a typical example of the roles and responsibilities of personnel involved in the governance of the MOSS branding. Depending on the size of your organisation, consolidate the roles and positions to suit. I’ve put the responsibility definitions into cleverworkarounds’ plain english to make it more interesting, but you may want to formalise these a little more if you use this

Role	Position	Responsibility
Steering Committee	Senior Divisional Heads Marketing Manager IT Manager SharePoint Architect	The buck stops here! If it all goes to hell, these are the guys who get burned! (but have no doubt they will apportion the blame all round)As a result of that prospect, they tend to like to signoff on all branding things! (and everything else too)Oddly enough, they also therefore believe that they provide vision and direction to the MOSS branding
Business Owner	Board Level Project Sponsor	The person who writes the cheques! They are who the steering committee answers to. Thus, people are generally very nice to them!They get to set the direction of what they want, even if their branding taste is dodgy (If they try and mix WCM and Collaboration try and tactfully dissuade them)
SharePoint Support Team	Application Support Manager SharePoint Administrator SharePoint Designer SharePoint Developer	These guys take all the vision stuff from the Business Owner and Steering Committee and actually designs and develops the corporate MOSS brandThis team also resolves operational issues and enforces best practice in relation to the MOSS branding solution
Site Collection Owner	SharePoint Administrator	Activation of branding features is performed by the site collection owner
Infrastructure Operations Team	Farm Owner Site Collection Owner Infrastructure Owner	These guys keep the support team honest. They ensure that branding is packaged up according to policy and install those features/solutions to the farm. This ensures the technical integrity of the branding development

Policies and Standards

So now we have defined who is responsible for what, we can now put it all into policy.

Corporate Style Guide

The first thing you need to do is define a corporate style guide, or locate the existing one and refresh it via the steering committee. The style guide houses all relevant standards, requirements, and recommendations surrounding corporate brand. It is not a technical document, as it covers the tone, presentation and all implementation aspects, specifications, attributes and elements, summed up to present a brand consistently throughout all media.

This guide changes over time and its owner is likely the marketing division of the organisation and not just the SharePoint branding steering committee. It is best to engage with the division or individual that owns this guide, to ensure that the steering committee is in the loop during periods of review and updating.

Once you have an approved style guide, you can now apply it to SharePoint components.

Master Pages

If you adopt the principles of my earlier posts in this series, you may not need to have more than a single master page for your entire farm. A well defined master page with clever use of CSS override techniques allow you to offer different branding, yet using a single master page. If this is a realistic prospect for you, then it makes sense to enshrine in policy that you will only maintain one corporate master page.

Best to leave the master page in the master page gallery for the site collection. That document library has versioning and content approvals enabled. Thus, it eases change and configuration management, as well as packaging and deployment.

The master page should be named according to a consistent convention. I personally like to prepend the company name to the master pages, as well as layout pages as then it is very easy to see what components are customised from what is build in. I enshrine this in the branding policy as a mandatory requirement.

That master page should be well documented with all of the modifications made to it. Typically, if you have modified say, DEFAULT.MASTER, you will have to document modifications like

Any assembly references added to the master page (see this post if you want an explanation)
Any hard-coded links to other CSS files and the definition of new styles
Modification of the HTML structure of the master page (e.g. Adding left and right borders to the default master page)
Any examples of non-compliance with the corporate style guide

Layout Pages

A collaborative style SharePoint site may require additional layout pages. The rules pretty much apply as per master pages.

Name them consistently with master pages (eg prepend company name)
Document their setup, where it is used and why it was required

Styles

Corporate style sheet guidelines should be documented and these are a direct translation from the corporate style guide. Logo’s, fonts, formatting, colors, backgrounds, etc are documented either as mandatory standards or recommended guidelines in the CSS style guide.

In addition, CSS style sheets should be both well documented within the CSS file using comments, as well as documentation around the implementation of the style. If you have overridden say, some of CORE.CSS, then mention it in the comments for the style why it was done.

CSS styles should live in the Style Library for each site collection. Unless you have an exceptional reason, there is no point in reinventing the wheel and putting them anywhere else. Naming of CSS sheets should also be consistent with the master pages and page layouts. So if I was writing a governance policy for ABC corporation, I would use something like

ABCDefault.master
ABCWelcomeSplash.aspx
ABCDefaultStyle.CSS

Site Templates

Although I didn’t cover site templates in this series on branding, the concept is simple. Once you have set up a site the way you want it, you can save it as a template that can be re-used for other sites. Certainly, it is common for project oriented companies to create a project site template with a particular combination of lists, web-parts, workflows, event handlers and libraries. Each time a new project is initiated, a site is created for that project based on the template.

This helps us to achieve the governance of a consistent user experience, as well as improving change and configuration management.

The process of creating a site template is potentially complex as the amount of collaborative functionality provided grows over time. Therefore, guidelines for the development of site templates must be developed to ensure they meet minimum standards. Potentially, site templates will be used by different organisational groups, with their own unique requirements. You will need to find a balance between overall site/branding consistency versus the costs and overheads of accommodating unique requirements.

Therefore, a formal approval process culminating with steering committee approval should be in place to manage the ongoing management of every corporate site template. The corporate style guide will also very likely influence the look and feel of custom site templates.

For each template, you also need to determine which parts of the template may be changed by site owners, and which may not. This can be enforced by security settings, but you still need the official policy to fall back on if tool based controls do not give you what you need.

Having said all of this, much of the governance around site templates is focused on non-branding considerations such as security, audiences, functionality and the like. We will not discuss this here as it is not really a branding consideration.

The point is, site templates have similar branding governance requirements to master pages, page layouts and styles.

Operational Management

In the previous section I looked at the governance requirements of branding from a SharePoint building block point of view. Now lets take an ITIL oriented perspective

Change management and approvals

With change management, go straight to ITIL and get what you need as far as process is concerned. ITIL defines the objective of change management as:

“The objective of Change Management in this context is to ensure that standardized methods and procedures are used for efficient and prompt handling of all changes to controlled IT infrastructure, in order to minimise the number and impact of any related Incidents upon service.

ITIL defines a CAB or change authority board that advises the ‘change manager’ prior to change approval. For my money, the steering committee will delegate the CAB function to the other groups who assume *custodianship* of the process. For example, the steering committee still bear ultimate accountability over the deployment of branding, but once the policy has been set, they delegate the validation of the deployment to the IT Infrastructure Operations Team.

Now bear in mind, we are talking about branding only here, and ITIL in the wrong hands can create ridiculous amounts of red tape.

But in relation to change management, this is the sort of stuff that should be considered.

Change justification. Have we recorded the request (who and why)?
Assess the impact of the change (cost vs benefit)
Test the change. Any branding changes require comprehensive testing on a non production environment. You never know how various web-parts render, and a formal testing methodology must be defined to ensure that say, your latest snazzy style turns out to make the calendar view look crap.
Packaging and deployment. Updates to branding should be packaged and deployed in accordance with corporate policy. The goal here is to ensure efficient, consistent deployment with easy means of rollback. We will delve more into packaging and deployment in a moment.
Implement the change, update documentation and logs
Conduct post implementation review of the change

Packaging and deployment of branding

Well, unless you are reading this series backwards, I think you should have a fair idea by now that I recommend that all branding should be implemented as a SharePoint solution. Check article four, five and six for more info. For me personally, I consider that if an application developer does not comply with this requirement (or whines about having to comply), then they have no serious idea about the importance of governance. That for me is a risk that I would prefer not to live with.

You will need to ensure that if 3rd party developers are doing your branding, that they are aware of all your other branding requirements, such as naming conventions so that the content packaged up inside the solution follows your governance standard.

When branding is packaged up into a SharePoint solution, we have a single file than can be easily deployed to the farm, upgraded and rolled back. In a disaster recovery situation, re-applying your branding is literally as easy as installing the solution and activating it.

Source control

On a large scale site, you may opt to use source control like Subversion for your branding components, especially if you are writing custom event receiver assemblies as I described in article six.

But then again, SharePoint itself is actually a great platform for implementing a governance site. You can make use of version enabled document libraries to hold your packaged solutions, procedures, standards and guidelines and other related content. Plus, you can use a calendar list+workflow for scheduling and notifying stakeholders of updates or changes, a task list for logging and tracking issues and infopath+workflows for automating the change management process.

Furthermore, I have found Colligo Reader to be very useful for SharePoint governance sites, as it alleviates the chicken-egg risk of storing all of your governance and change history in the same tool that you are governing. Often I am asked, “what if SharePoint is down, how can I get to my documentation?”.

Colligo allows you to have a full offline sync of all your governance lists, documents and views, thereby significantly reducing this risk and that barrier to adoption. I also suggest that you buy a copy of this product and add to your governance policy that you will always keep an up to date sync of your governance site offline.

Summing Up

So finally it ends. I originally thought I’d cover it all in 3 articles but in the end it took 7 large articles. But I’ve now gotten to the end of this arduous task of attempting to cover SharePoint branding from end-to-end. I hope that you have found this series of articles of use, and I appreciate you for sticking with me. If these articles were of help to you, please drop me a line and let me know. If you really want to show your appreciation, and you live in Perth, West Australia, I’m quite partial to Hoegaarden (but if its your buy I’ll drink anything! )

over and out

Paul

No Tags

SharePoint Branding Part 6 – A "solution" to all issues?

admin — Fri, 09 Nov 2007 22:42:22 +0000

There has been a bit of a gap in this series between part 5 and 6 – and fortunately for the both of us, I think this is the penultimate post in my series on SharePoint branding. While it has been an interesting exercise for me, I must confess each successive article is getting harder to write as my interest is shifting So many sub-disciplines within MOSS – I think I might delve into WCM soon .

To recap for those of you hitting this page first, I suggest you go back and read this series in order.

Part 1 dealt with the publishing feature, and some general masterpage/CSS concepts and some quirks (core.css and application.master) that have to be worked around.
Part 2 delved into the methods to work around the application.master and core.css issue
Part 3 delved further into the methods to work around the application.master and core.css issue and the option that solved a specific problem for me
Part 4 then changed tack and introduced how to package up your clever branding via features
Part 5 expanded on features and also noted a couple of major bugs that can catch you out if you aren’t aware of them

Now, we will finish off on features and move onto solutions. As you will see, aside from playing a very important part in SharePoint deployment/governance process, solutions actually solve one of the bugs I mentioned in part 5 – the one where deactivating and reactivating a branding feature does not always update the components. (More on that later).

In addition, whilst our feature is not too bad, it is not uber clever yet! As described in the previous article, a site collection administrator still has to manually perform some tasks after activating the feature. This may be totally fine, but generally, you would only activate a branding feature, if you meant to use it.

So presently, we have to pick the our master page from the master page list, as well as apply the right theme based CSS file as shown in the two images below.

We know how much of a strain those 2 steps must be to those bleating, underworked and overpaid site administrators, but fear not, lazy ones! We do have the means to do this automagically!

Feature Receiver Assembly

SharePoint features have the facility where you can write custom code that is triggered when certain events happen to features. It is a class called SPFeatureReceiver and when used, it traps events that are raised after Feature installation, uninstallation, activation, or deactivation action has been performed.

We are going to write some code that waits for the feature to be activated, and then set the master page for the site collection to pimpmysharepoint.master. While we are at it, we will do the CSS override too.

At this point if you are not a programmer, your eyes may glaze over at the stuff below. If you are happy to believe me that you can make the master page default to pimpmysharepoint.master then feel free to skip to the next section.

For the rest of you…

In our Feature.XML file, we add a new parameter in the XML element called “ReceiverAssembly“. It specifies the assembly holding the feature. Another parameter called ReceiverClass specifies the class within the aforementioned assembly. The XML element looks something like

ReceiverAssembly=”CleverWorkarounds.PimpMySharePoint, Version=1.0.0.0, Culture=neutral, PublicKeyToken=c4r56efbb122b266″
ReceiverClass =”CleverWorkarounds.PimpMySharePoint.SetDefaultMasterPage” >

This now tells the feature that when the feature is installed, activated, deactivated or uninstalled, call the above assembly DLL and look in the CleverWorkarounds.PimpMySharePoint.SetDefaultMasterPage class.

Let’s look at that class source code.

namespace CleverWorkarounds.PimpMySharePoint
{
    public class SetDefaultMasterPage : Microsoft.SharePoint.SPFeatureReceiver
    {
        public override void FeatureActivated (SPFeatureReceiverProperties properties)
        {
            SPWeb MyCurrentWeb = properties.Feature.Parent as SPWeb;
            MyCurrentWeb.MasterUrl = “/_catalogs/masterpage/pimpmysharepoint.master”;
            MyCurrentWeb.CustomMasterUrl = “/_catalogs/masterpage/pimpmysharepoint.master”;
            MyCurrentWeb.AlternateCSSURL = “/Style Library/pimpmintyfresh.css”;
            MyCurrentWeb.Update();
       }
    }
}

The namespace line (namespace CleverWorkarounds.PimpMySharePoint) matches the first part of the “ReceiverAssembly” parameter in the FEATURE.XML file. The class line (public class SetDefaultMasterPage : Microsoft.SharePoint.SPFeatureReceiver ) corresponds to the ReceiverClass parameter in the FEATURE.XML

Now SharePoint can find the DLL and the class to use.

Inside the class, it expects to find some code for each event. In the example above, we are only looking at the “FeatureActivated” event. So this assembly will only do something on feature activation, not install/uninstall/deactivation.

Looking at the activated event, it’s pretty easy to see what is happening.

SPWeb MyCurrentWeb = properties.Feature.Parent as SPWeb;
            MyCurrentWeb.MasterUrl = “/_catalogs/masterpage/pimpmysharepoint.master”;
            MyCurrentWeb.CustomMasterUrl = “/_catalogs/masterpage/pimpmysharepoint.master”;
            MyCurrentWeb.AlternateCSSURL = “/Style Library/pimpmintyfresh.css”;
            MyCurrentWeb.Update();

This code gets the current site collection the feature has been activated on, and sets the master page to pimpmysharepoint.master and sets the default CSS override..

Here is the full FEATURE.XML that incorporates the featuredependency directive we talked about in the last post, along with the receiverclass.

    Title=”Pimp my SharePoint”
    Description=”This is a feature that adds a new sexy CSS”
    Version=”1.0.0.0″
    Scope=”Site”
    ReceiverAssembly=”CleverWorkarounds.PimpMySharePoint, Version=1.0.0.0, Culture=neutral,    PublicKeyToken=c4r56efbb122b266″
    ReceiverClass =”CleverWorkarounds.PimpMySharePoint.SetDefaultMasterPage”
    xmlns=”http://schemas.microsoft.com/sharepoint/”>

So ,now the feature is much more clever. As clever as a branding feature needs to be. Of course, if the feature is deactivated, you should also write code against the deactivating event and reset all the customisations back to defaults, but for my purpose, this is clever!

CleverWorkAround Rating – Sweeeeeet

Uh-Oh, but what about the assembly DLL?

Hang on a second! It’s all well and good to have a feature refer to an assembly DLL that you have written to do clever things, but what if that DLL isn’t there? Shall we be like Mythbusters and try anyway?

C:\>stsadm -o installfeature -name pimpmysharepoint

Operation completed successfully.

Damn, that myth is totally busted .

Ah well, let’s activate the feature since ‘activation’ was the only event we actually trapped for!

YEAH BABY! A big, feral error runtime error! Now that is what I call a mythbusters moment!

And for those lovely search engine spiders, here it is in plain text (in teeny tiny font because you probably don’t care that much about it anyway Anyway, the first line confirms it. “Feature x could not be installed because the loading of the event receiver assembly x failed”.

Feature ’01c34560-6561-11dc-8314-0800200c9a63′ could not be installed because the loading of event receiver assembly “CleverWorkarounds.PimpMySharePoint, Version=1.0.0.0, Culture=neutral, PublicKeyToken=c4r56efbb122b266″ failed: System.IO.FileLoadException: Could not load file or assembly ‘CleverWorkarounds.PimpMySharePoint\, Version\=1.0.0.0\, Culture\=neutral\,\tPublicKeyToken\=c4r56efbb122b266′ or one of its dependencies. The given assembly name or codebase was invalid. (Exception from HRESULT: 0×80131047)
File name: ‘CleverWorkarounds.PimpMySharePoint\, Version\=1.0.0.0\, Culture\=neutral\,\tPublicKeyToken\=c4r56efbb122b266′
   at System.Reflection.AssemblyName.nInit(Assembly& assembly, Boolean forIntrospection, Boolean raiseResolveEvent)
   at System.Reflection.Assembly.InternalLoad(String assemblyString, Evidence assemblySecurity, StackCrawlMark& stackMark, Boolean forIntrospection)
   at System.Reflection.Assembly.Load(String assemblyString)
   at Microsoft.SharePoint.Administration.SPFeatureDefinition.get_ReceiverObject()

   at Microsoft.SharePoint.Administration.SPFeatureDefinition.get_ReceiverObject()
   at Microsoft.SharePoint.SPFeature.DoActivationCallout(Boolean fActivate, Boolean fForce)
   at Microsoft.SharePoint.SPFeature.Deactivate(SPSite siteParent, SPWeb webParent, Boolean fForce)
   at Microsoft.SharePoint.SPFeatureCollection.Remove(Guid featureId, Boolean force)
   at Microsoft.SharePoint.SPFeatureCollection.Remove(Guid featureId)
   at Microsoft.SharePoint.ApplicationPages.DeactivateFeaturePage.LnkbtnDeactivateFeature_Click(Object objSender, EventArgs evtargs)
   at System.Web.UI.WebControls.LinkButton.OnClick(EventArgs e)
   at System.Web.UI.WebControls.LinkButton.RaisePostBackEvent(String eventArgument)
   at System.Web.UI.WebControls.LinkButton.System.Web.UI.IPostBackEventHandler.RaisePostBackEvent(String eventArgument)
   at System.Web.UI.Page.RaisePostBackEvent(IPostBackEventHandler sourceControl, String eventArgument)
   at System.Web.UI.Page.RaisePostBackEvent(NameValueCollection postData)
   at System.Web.UI.Page.ProcessRequestMain(Boolean includeStagesBeforeAsyncPoint, Boolean includeStagesAfterAsyncPoint)

So, it should now be obvious that the DLL holding your event receiver class should be deployed to your web front end servers, either in the GAC, or in the BIN folder of each web app under INETPUB.

But how lame is that? You go to all that trouble to make a auto-installing feature and then you need to manually do this bit??? Isn’t that a little counter intuitive?

Fear not readers, you now know why SharePoint “Solutions” are the things that REALLY matter!

SharePoint Solutions – The plain english description

Back in this early post, I defined SharePoint Features as “a method to add/customise many areas of SharePoint”. Well, guess what, so are solutions as well! So what is the difference between the two?

Well, to answer that, let’s consider some of the things that you cannot do in a feature.

You cannot deploy an assembly to the GAC
You cannot edit the web.config of a web application
You cannot install a feature to all web front end servers in a farm at once

The latter is an important one. One of my clients has a 5 server farm with 3 WFE servers. If say, I have to update a webpart, I have to put the assembly into the GAC on all three servers. I then have to edit web.config on the web applications to mark the control as safe.

This is not only tedious but risky. Mistakes can be made, leaving WFE servers in an inconsistent state. (Hands up who has killed a web application because of a mistake in web.config. I bet all of you!)

If we have to roll back to a previous version, we have to do it manually on all three WFE servers. Also, what if we have several related features to install at once? That’s a lot of manual work and I am cheap and lazy!

So, MSDN says this about solutions: “The Microsoft Windows SharePoint Services solution framework provides a way to bundle all of the components for extending Windows SharePoint Services in a new file, called a solution file. A solution file is a cabinet or .CAB-based format with a .wsp extension. A solution is a deployable, reusable package that can contain a set of features, site definitions, and assemblies that you can apply to a site, and can also enable or disable individually. You can use the solution file to deploy the contents of a Web Part package, including assemblies, class resources, .dwp files, and other package components”

Therefore, to really be clever with the deployment of our clever branding, we now need to take our feature, and add it to a solution, that also copies the feature receiver assembly (DLL) into the GAC. In addition, the solution will do this consistently to all WFE servers, ensuring that they are consistent. If any one of them has a problem, we can roll back the solution deployment, fix the issue, and then re-deploy the solution.

CleverWorkAround Rating: Mandatory! If it is not a solution, I ain’t putting it in!!

Okay so how do I build my solution then?

Well, I have to say, when MOSS07/WSS3 came out, this was a truly ugly process. In the last year, plenty of clever people have written tools to make the job easier. Let’s examine the one I use: WSPBUILDER

I won’t fully detail the product – hey that’s what the wspbuilder site is for. But I will explain how to use it for the purpose of this branding exercise.

So assuming you have WspBuilder installed, we have two things to install.

The “CleverWorkarounds.PimpMySharePoint.DLL” eventreceiver assembly.
The PIMPMYSHAREPOINT feature

To create the solution, you can follow these basic steps (although real SharePoint developers will snigger at this, as I am not integrating this into a visual studio project).:

In the folder where WspBuilder was installed (I’ll assume C:\Program Files\WSPBuilder for now), create the following folder structure if it does not exist:
- 12\Template\Features (eg C:\Program Files\WSPBuilder\12\Template\Features)
Copy the PIMPMYFEATURE folder into the above folder, resulting in C:\Program Files\WSPBuilder\12\Template\Features\PimpMySharePoint
In the folder where WspBuilder was installed (I’ll assume C:\Program Files\WSPBuilder), create the GAC folder if it does not exist:
- C:\Program Files\WSPBuilder\GAC
Copy the CleverWorkarounds.PimpMySharePoint.DLL assembly to the C:\Program Files\WSPBuilder\GAC folder
Open a command prompt, and CD to the location of wspbuilder
- cd \program files\wspbuilder
Type wspbuilder at the prompt and press Enter
- c:\program files\wspbuilder>wspbuilder
The wspbuilder program will package up your components and create three files.
- wspbuilder.wsp
- manifest.xml
- solutionid.txt

For those of you who are really interested, the WSP file name will default to the name of the folder where WSPBUILDER.EXE resides. I strongly suggest renaming this to a meaningful name or running wspbuilder from an appropriately named folder. For our purposes, I renamed it to pimpmysharepoint.wsp.

Right! Now we have our magical WSP file. We need to add this solution to the SharePoint farm ‘solution store’, and then deploy this solution.

Deploying the solution and testing

To add the solution to the store, we use the STSADM command. But first, let’s clean up so we can test this.

Firstly, delete or rename the pimpmysharepoint feature in the C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\FEATURES folder. We want to see that the solution adds it back when deployed.

Also check the C:\WINDOWS\ASSEMBLY and ensure your assembly is not in the GAC. If it is, remove it.

So, back to STSADM. Below is the syntax..

C:\Program Files\WSPBuilder>stsadm -o addsolution -filename pimpmysharepoint.wsp

Operation completed successfully.

C:\Program Files\WSPBuilder>

Okay, now what? Well.. we now deploy this feature.

Deployment can be performed via STSADM or SharePoint Central Administration. I actually prefer central administration because it tells me more and leaves less to chance. (I tend to type badly and make spelling errors

In Central Administration, navigate to Operations -> Solutions Management under “Global Configuration”

Well how about that! There is our pimpmysharepoint.wsp file. Note that its status is “not deployed”.

I guess the only thing to do is to deploy it then!

Clicking the pimpmysharepoint.wsp link presents us with the solution deployment screen. Here we can see a summary of the solution. One of the key thing that we can see is that our solution contains an assembly DLL (“contains global assembly” is YES)

Click “Deploy Solution”. The next screen is the most important one of all. We are provided with a means to deploy this solution at a later time (perhaps on a weekend or other quiet time). The other really interesting thing is because this solution is of type “web front end server” (see previous image), we have the choice of which web application to deploy this solution to.

This is really important! Just because we have a solution added to the farm solution store, does not mean that we want to pimpmysharepoint feature installed on every web application.

I personally prefer to specify the web application the feature is for, rather than deploy to all of them. For a start, if you deploy to all, you are including the central administration site itself, as well as the SSP sites. I think 95% of the time they don’t need it. I’d rather keep such an important web application nice and vanilla).

For what its worth, depending on the solution components and scope, you can pick all or one web application to deploy to. If you have more than one web application that needs this feature, you can come back into this screen again via the solution management section in central admin. From there you are able to choose another web application.

Regardless of this, the assembly only gets loaded into the GAC once! It will do a version check if it finds one already there.

Click OK and if all goes to plan, the solution is deployed!

Let’s go and check!

First up, examine C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\FEATURES folder. Is there a PIMPMYSHAREPOINT folder? Yes indeedie!

Secondly, is our DLL in the GAC? Yep..

So things seems to be looking good!

Note! If we had several WFE servers, in this case, the feature and assembly would be been installed on all WFE servers for the solution to successfully be deployed. From a governance point of view, this is a significant time saver and ensures all WFE servers are consistent. If say, the deployment of the solution failed for one WFE server, you will be notified of the failure.

Upgrades and rollback

But it gets even better. Solutions can be upgraded. So you have new master page content and optimise the code in your feature receiver event handler. Simply recreate the WSP file using WSPBuilder. Then you can replace the existing solution with your updated one.

The beauty of this is that an upgraded solution will update the feature, install the newer assembly on all WFE servers. In addition, if something goes wrong, SharePoint will automatically roll back to the pre-upgrade solution as well!

A solution is upgraded when a newer WSP file is created. The STSADM -o upgradesolution command is used to do the upgrade. For example.

C:\Program Files\WSPBuilder>stsadm -o upgradesolution -name pimpmysharepoint.wsp -filename pimpmysharepoint-v2.wsp

Want to retract a deployed solution from a site? That’s easy too. You can do it via the solution management admin screen in central administration or use the STSADM -o retractsolution command. You can retract a solution from one or all web applications as well.

In our sample, retracting a solution from a web application will remove the feature from the feature list. You will no longer be able to activate it.

Finally, you can completely remove the solution as well. This will do a complete cleanup. The PIMPMYSHAREPOINT feature folder will be deleted from C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\FEATURES and the cleverworkarounds.pimpmysharepoint assembly will be removed from the GAC.

But wait! there’s more!

If I haven’t convinced you enough already, I will give you one more reason. In part 5 of this series, I outlined the stupidly annoying issue where the deactivation and reactivation of a branding feature will not work properly. Specifically, feature files will not be overwritten when they have been modified via publishing a new version of files within the site collection galleries. “Seems that as soon as a new version has been published, any updates via a feature will not overwrite. The feature gives no indication that this has occurred either!”

But guess what! When you upgrade a solution via STSADM -o upgradesolution, this issue does not occur. All updates to features that are packaged into a solution get properly distributed to any site collection that has the pimpmysharepoint branding feature activated!

Why the behaviour is different when deactivating and activating a feature is anybody’s guess, but it works for me!

Summing Up

My aim in this article was to educate and convince you that solution’s the best way to install features. Notwithstanding the fix for my annoying feature bug, the ability to push out updates across multiple servers consistently, and ease of upgrades and retracting make your complex environment just that little bit more manageable.

So if a 3rd party tells you “oh just put this updated DLL into the GAC”, politely tell them that if it is not packaged into a solution, you are not going to do it! Might sound tough, but there is pretty good reasoning behind this attitude. My last post of this branding series will expand on this sort of thing when I cover the governance of SharePoint branding, based on all we have learned so far.

For now though, I hope you found this post useful!

No Tags

SharePoint Branding Part 5 – Feature Improvements and Bugs

admin — Fri, 26 Oct 2007 17:14:32 +0000

So, here we are at the fifth article in my series on SharePoint branding. By now, we have left all the master page stuff way behind, and we have created a custom feature to install our branding to a server.

To recap for those of you hitting this page first, I suggest you go back and read this series in order.

Part 1 dealt with the publishing feature, and some general masterpage/CSS concepts and some quirks (core.css and application.master) that have to be worked around.
Part 2 delved into the methods to work around the application.master and core.css issue
Part 3 delved further into the methods to work around the application.master and core.css issue and the option that solved a specific problem for me
Part 4 then changed tack and introduced how to package up your clever branding

Now we will move onto some more advanced aspects of features to make it more clever and identify two really annoying bugs that can make the whole experience painful. You should be aware of them.

So, picking up where we left off, we have a feature that we successfully deployed to the SharePoint server. It performed the tasks of copying CSS files to the style library of the activated site collection and copying the master page file to the master page gallery.

As described in the previous article, we still have to manually perform some tasks after activating the feature. We have to pick the PIMPMYSHAREPOINT.MASTER from the master page list, as well as apply the right theme based CSS file as shown in the three images below.

This is clever, in the sense that site collection and farm administrators do not have to worry about manually copying the files into the style library and master page gallery, but it’s still a manual task. In addition, as discussed in prior articles, this all depends on the “Office SharePoint Server Publishing Infrastructure” feature need to be active first.

Let’s see what happens, if it is not activated.

Breaking the rules

Below, you can see that the publishing feature is not active. (The lack of ability to pick a new master page is a tell-tale sign).

To make 100% sure we are dealing with a clean site with no publishing, let’s examine the site in SharePoint Designer. Does a style library exist? Nah-uh!

So, first up, let’s see if our feature will install and activate.

C:\>stsadm -o installfeature -name PimpMySharePoint

Operation completed successfully.

C:\wspbuilder>

So, what can we conclude from this? It seems feature dependencies do not prevent the installation of the feature to the server.

Ah, but of course, we all know by now that a feature has no effect until it’s activated. So, let’s do that next for a test site.

GONG! We have a problem. Something went wrong!

Now the error message here sucks in terms of readability, I wonder what list does not exist? The style library maybe?

Failed to instantiate file “PimpMintyFresh.css” from module “MyPimpedStyles”: The specified list does not exist. at Microsoft.SharePoint.Library.SPRequestInternalClass.EnableModuleFromXml(String bstrFeatureDirectory, String bstrUrl, String bstrXML)
at Microsoft.SharePoint.Library.SPRequest.EnableModuleFromXml(String bstrFeatureDirectory, String bstrUrl, String bstrXML

Looking closely at the message, it is saying that it tried to copy PimpMintyFresh.CSS to the location defined my the module MyPimpedStyles. As a refresher, here the the XML file containing the module directive.

http://schemas.microsoft.com/sharepoint/”>



[snip]

Can you see the directive that has a parameter called “name” with a value of MypimpedStyles? The other parameter in is the URL parameter, which for MypimpedStyles is “Style Library”.

The error states “The specified list does not exist”, which means that there is no “Style Library”. Makes sense doesn’t it – as the publishing feature, not yet activated, has not created it?

Okay let’s obey the rules then!

So, after breaking it by trying our feature without its pre-requisites, let’s now be good children and activate the pre-requisite publishing feature before retrying this process.

Step 1. Activate the “Office SharePoint Server Publishing Infrastructure”

GONG! WHAT THE?… An error now!

The explanation is a hint…

“The specified name is already in use”

…and the full text version for uncle google

“A list, survey, discussion board, or document library cannot have the same name as another list, survey, discussion board, or document library in this Web site. Use your browser’s Back button, and type a new name. at Microsoft.SharePoint.Library.SPRequestInternalClass.CreateList(String bstrWebUrl, String bstrTitle, String bstrDescription, String bstrListUrl, String bstrFeatureId, Int32 lTemplateID, String bstrDocTemplateType, ListQuickLaunchOptions qlOpt)
at Microsoft.SharePoint.Library.SPRequest.CreateList(String bstrWebUrl, String bstrTitle, String bstrDescription, String bstrListUrl, String bstrFeatureId, Int32 lTemplateID, String bstrDocTemplateType, ListQuickLaunchOptions qlOpt) “

So what could be causing this? Let’s look again at the site in SharePoint Designer.

AHA! – A style library folder got created – nice error checking MS!

But this “Style library” must be a folder, not a document library because of the previous error message “The specified list does not exist”.

Anyway, the obvious thing to do is to delete this style library. So let’s do that using Designer and then re-attempt activating the publishing feature.

Aaah … That’s better!

So, for educational value, have a look at the site now in designer. As you can see below, the publishing feature adds a lot of stuff! If you want more detail on what the publishing feature adds to a site collection, check my first post in this series or head over to Penny’s blog.

So, although we have been clever in creating a feature for our branding, it’s just not darn clever enough. I wonder if we can make this better?

CleverWorkaround Rating – better than nothing

Being Cleverer

(is ‘cleverer’ a word?)

Another XML element that we can add to our FEATURE.XML is called, “ActivationDependencies”. MSDN explains it all but it’s pretty self explanatory anyway. Here is an example of an activationdependence for the publishing feature.

How do we know that this is the Publishing Feature? The FeatureID refers to the GUID of the FEATURE.XML for that feature. (So now it should make sense why each feature needs a unique GUID).

So here is the amended FEATURE.XML.

Title=”Pimp my SharePoint”
Description=”This is a feature that adds a new sexy CSS”
Version=”1.0.0.0″
Scope=”Site”
xmlns=”http://schemas.microsoft.com/sharepoint/”>

Backing out..

So, now we get to see one of the main benefits of features. The fact that they can be deactivated and uninstalled. The process is basically the reverse of the install/activate process. We deactivate the feature on all sites where it is used, and then we uninstall the feature. We then install our new feature.

C:\>stsadm -o uninstallfeature -name pimpmysharepoint
Operation completed successfully.
C:\>stsadm -o installfeature -name pimpmysharepoint
Operation completed successfully.
C:\>

Reactivating

So, now let’s activate our feature with this dependency information. That’s better… we get a friendly message that lists the feature by name (even though we only supplied the GUID).

So, we do as asked and activate the publishing feature. Now let’s re-attempt the install of our feature.

Yay

So, now we check the style library – all good!

The next experiment

At this point, I need to acknowledge the value of Andrew Connell’s blog. We are going to discuss some interesting quirks in the next section, and his site was really useful.

So, the next experiment. Let’s deactivate this feature and reactivate it to see what actually gets removed. Click deactivate against the pimpmysharepoint feature and accept the obligatory warning.

It has deactivated ok.

So, let’s check the style library again. Interesting – the files are still there. I initially thought that a feature would clean up after itself. But Yoda Andrew, sets the record straight.

“That is by design. Deactivation of features does not remove data that was created when the feature was activated. if you want to “clean up” the data that was created, you need to create a Feature receiver handler and have the FeatureDeactivating() event handler manually remove the file.”

and

“Keep in mind though, data is left in SharePoint BY DESIGN. What would happen if you had deployed a page layout with a Feature and someone removed it while it was in use by thousands of pages? Oops… blamo!”

Andrew has spoken – amen!

So, that left me wondering what happens when a feature is reactivated. Do newer files overwrite these orphans?

Test 1: Update master page in the feature definition and reactivate

Update master page with small change and copy to the feature folder
Deactivate the feature
Check if the site still renders with the feature deactivated
Uninstall the feature
Install the Feature
Reactivate the Feature
Re-Examine site. Master page changes are reflected

Test Passed!

Test 2. Publish a master page as a major version in SharePoint designer and repeat test 1.

Make a benign change and publish it as a major version

Deactivate and uninstall feature
Check if the site still renders with the feature deactivated
Update the master page file and recreate the feature
Reactivate the feature on the site collection
Check the site – the rendering does NOT reflect the updated master page in the feature.

Test Failed!

The feature has not overwritten the master page on the site. Seems that as soon as a new version has been published, any updates via a feature will not overwrite. The feature gives no indication that this has occurred either! This is serious! So, how can we re-push out branding? This breaks the whole model.

Another bug? By design?

CleverWorkaround Rating: Shame, Shame, Shame

More Gripes

So, I think to myself, what if I delete the master page from the gallery prior to deactivating, reinstalling and reactivating the feature? Sure, it defeats the purpose of feature based updates as it introduces a manual step, but maybe it will solve the problem.

I tried and deleted it and I got this error.

Okay, makes sense. I forgot to set the master page of the site collection back to default.master or something else. So I did that and re-attempted.

GONG! Same issue! – Not having a good SharePoint day.

Now, I will cut a long story short here and explain this bug to you. It’s a different one from the master page not being updated by the feature, but is just as annoying. If you create a new site collection with no sub-sites, the master page above will delete just fine once you stop using it. But if you have made any sub-sites you may have this problem.

What seems to happen is this. If you make a sub-site, and then tell it to inherit the master page settings from the parent, AND then delete that sub-site, SharePoint seems to ‘forget’ to update its internal status that the master page is no longer used for the deleted sub-site. Thus, you are prevented from deleting, when it is actually not in use.

Check this KB article, it describes the issue but not the cause. http://support.microsoft.com/kb/926812

So, would you believe that in real life, I got nailed by both these two bugs at the same time! Made troubleshooting a real bitch I can tell you!

Wrapping up

So, to sum up, features are a “good thing” ™ and you should use them and also mandate their use. As I have demonstrated, they are beset by a couple of bugs that can give you a few more grey hairs, but once you are aware of this, they can be worked around with some governance rules. I hope, though, that Microsoft fix this rather soon – as it’s their bigger, enterprise customers who are more likely to be affected! (i.e. more sites, more people making changes, etc).

For what it’s worth, I found a workaround which will be fully detailed in my next exciting installment where I finish off features and finally dive into SOLUTIONS!

Bye for now!

del.icio.us Tags: SharePoint , SharePoint Branding , Masterpages , SharePoint Features

No Tags

SharePoint Branding Part 4 – Packaging up your masterpiece into a Feature

admin — Wed, 24 Oct 2007 18:14:36 +0000

Welcome to the fourth article in my series on SharePoint branding. Sorry for the time it’s taken to get this one out, but a certain game called “The Legend of Zelda: Hourglass Phantom” on NDS got in the way. I finished it yesterday and only had to cheat via google once . Anyway it’s out of my system now so I can get back to this.

After 3 epic articles on all that painful CSS and master page stuff (part one, two and three), we now focus on what you have to do to get your branding masterpiece deployed to the SharePoint farm the clever way. In this next set of articles, we will look at where things should go, and then how to get it there the right way.

Now web designers, put down that hairspray because I am talking to you! Don’t switch off just because we are shifting our focus to the packaging and deployment of your branding work. Just because you have produced a master page, CSS files and images does not mean your job is over. In my SharePoint world, you are expected at the very least, to also package your work into a feature so it can be deployed the clever way.

Technical geeks, stop sniggering because you are just as bad as the designers if not worse! Despite all your whining about process and documentation and how cowboy-like web designers are, you rarely do any documentation yourself and will happily make production changes with no change control or proper testing! .

IT Managers… hmm… Why don’t you just go back to playing solitaire because I’m going to use some big words in this post.

Right! Let’s go.

Now I’ve already covered some of this stuff in my previous two articles on SharePoint features. We will recap some of this here, but I recommend for a full background, read the features post and the feature example post.

The CleverWorkarounds definition of SharePoint “Features” is that they provide a easy, consistent method to add/customise SharePoint. Once a feature has been installed to a SharePoint farm, it is available to be activated for specific sites or site collections. In the first article of this branding series, I showed how the “SharePoint Server Publishing Infrastructure” feature installs several master pages, among other things such as the style library. If you followed the advice in the first three articles on branding, it is exceedingly likely that you have your own customized master page, several CSS files and probably a few other associated files like images. You will also likely require the publishing feature to be activated for your branding to work.

So it makes sense, does it not, to package up and deploy your branding in the same manner as the publishing feature. Consistency is good!

So we will create a new feature that when activated for a site collection, adds our new master page, CSS and other supporting files to the master page gallery. From there, a site administrator can choose to use your marvelous custom master page by choosing it from the look and feel under “Site Administration”

The Custom Master Page

In this post, I am going to use a mythical custom master page called PIMPMYSHAREPOINT.MASTER. This master page is based around my hybrid branding technique as described in article 3. If you have not read this article yet, I suggest you go back and do so.

Anyway, this master page contains a custom reference to a CSS file called PIMPMYSHAREPOINT.CSS. Additionally, there are some other theme oriented CSS files that can be used for different skinning of sites. (In other words, site administrators have the choice of 3 color schemes to go with this master page).

PimpMintyFresh.CSS
PimpBlingGold.CSS
PimpGothicBlack.CSS

There are also several image files that go with each of these CSS files. To make this example easier, we will just use 1 image file for each of the skinning CSS files.

PimpMintyFreshBack.JPG
PimpBlingGold.JPG
PimpGothicBlack.JPG

So, along with PIMPMYSHAREPOINT.MASTER, we have 7 files here in total.

So where do I put the files?

Short answer, same place as the publishing feature uses for its master pages and styles. If that’s all you’re looking for, skip the next three headings, otherwise let’s dive a little deeper as to why they go here.

I really want to know – where does the master page go?

So we have our files, now we have to put them onto a site. Master page files obviously go in the master page gallery, but which one? A site collection has a master page gallery, but so does each and every individual site created inside that site collection. I can illustrate this by creating a site collection and a sub-site and then examining both of them in SharePoint designer. You will see that both the top level site of the site collection as well as the sub-site have individual _catalog/masterpage document libraries.

Below is the content of the master page gallery for the sub-site “blank” of the site collection “tidemo”. Note, there is not a lot in the master page gallery

Now let’s look at the site collection (root) level. Whoa! The publishing feature puts a lot in there!

Okay, so we now know that we have two choices in relation to master page galleries. Which do we use? Fortunately, the answer is pretty much determined for us. Recall how by activating the publishing feature for a site collection, enables you the ability to choose a master page via the SharePoint “Site Settings” GUI interface. Guess what? When you have the publishing feature enabled and you choose a master page from “Look and Feel” of Site Settings, it always refers to the master page gallery for the site collection, not the site.

So the short answer is: put your master page in the master page gallery for the site collection. That way it is selectable via the GUI. It also means it is available to all sub sites. If you roll out an update to a master page in the site collection master page gallery, then sites in the site collection will reflect the change.

Now if you are clever and use something similar to the hybrid method for branding as described in part 3, it is fine to put all of the files in at a site collection level. This is because any new branding that you want to experiment with is just a new CSS file that can be deployed to the farm, and then can be referred to from the “alternate CSS URL” screen under “master page settings” in site administration. E.g.

But, I suppose there are valid circumstances where this central approach is not flexible enough. Let’s say, you have a particular site that you do not want to change at all when site collection updates are made to master pages and CSS files. In this case, you could copy the master page from the site collection master page gallery to the site master page gallery and edit the page layouts and default.aspx to refer to the site level master page gallery.

How? Well you would have to modify your layout and existing content pages and change the ~masterurl token that is used by default, to something else. (I spoke about tokens in the “master page theory” section of part 1 and won’t rehash it here). But changing ~masterurl/default.master to ~site/_catalogs/masterpages/< your master page file> will do the trick. It does hard-code the name of the master page. It will reference the master page from the master page gallery of the site and not the site collection.

I haven’t had the need to actually change the token as described above, so I’ll reserve judgement on its CleverWorkaround rating for now..

For the record.. I’d recommend Stramit’s page for a more detailed explanation of the tokens.

Ok, so where do the CSS and supporting files go?

This next bit can be tricky. Why? Because it all depends on how you set up your master page in the first place. We spent article 2 and 3 looking at methods to have a master page reference a CSS file. You can hard-code a reference to a CSS link into a master page directly or using methods like CssRegistration. Either way, if you do not use tokens here, you will get yourself into trouble. Consider the following master page source code:

[snip]

” runat=”server”/>
[snip]

As you can see where I have marked in bold, it expects a document library to exist called “Style Library and looks inside it for a file called pimpmysharepoint.css”. This will result in the following browser HTML

[snip]

[snip]

Now if this is a single top level site collection, we are fine and dandy. The publishing feature does indeed create a document library called “Style Library” and it is the recommended place to put CSS files (more on this later).

But don’t forget, a single SharePoint web application can have many hundreds of site collections. Consider this example:

http://tidemo
http://tidemo/sites/collection1
http://tidemo/sites/collection2

Above are 3 separate site collections running from a single web application. Now what if you as a user, only have permission to access http://tidemo/sites/collection1?

As shown above, the master page will render the CSS link as

Can you see the issue with this? It will try and grab the CSS file from http://tidemo/style library, not http://tidemo/sites/collection1/style library. But your user account has no permission to http://tidemo at all. So the CSS is not found and the page is not styled.

Fortunately there are tokens that you can use to make sure there is a reference to the specific site collection. It is named, strangely enough, ~SiteCollection. So here is the amended master page source

[snip]

” runat=”server”/>
[snip]

Resulting in this output for our above example:

[snip]

[snip]

The problem is now solved. Note the path reflects the current site collection /sites/collection1.

So, now that we have tokens out of the way, we can quickly touch on the “Style Library” document library itself. As previously mentioned it is installed by the publishing feature and all CSS styles and associated files are stored here. Unlike the master page gallery, it only exists at the site collection level (because publishing is a site collection scoped feature). It is version enabled like the master page gallery but by default, does not have content approval enabled. It has been structured to handle multilingual sites via the use of subfolders for a given language and a language related token that is usable within master pages.

So, unless you have a really good reason, the CleverWorkarounds recommendation is to stick the style library created by the publishing feature. Add your custom styles to it using a naming convention that will ensure that future branding features by Microsoft or 3^rd parties will not inadvertently overwrite your own stuff.

As mentioned above, a key reason to stick with the default style library is the multilingual framework it provides, which we will touch on next.

Multilingual CSS considerations

Multilingual support is very important in the enterprise. It is common to have some unique CSS styling requirements for particular languages so the style library structure, in combination with some tokens enables you to achieve this in a clever way.

Let’s look at a snippet of the structure of Style library as it is created by the publishing feature. Below is a directory listing of the style library.

\Style Library\zz1_Blue.css

[snip]

\Style Library\Forms\Document
\Style Library\en-us\Core Styles
\Style Library\en-us\Core Styles\Tabs.css
\Style Library\en-us\Core Styles\Controls.css
\Style Library\en-us\Core Styles\rca.css
\Style Library\en-us\Core Styles\PageLayouts.css
\Style Library\en-us\Core Styles\zz2_EditMode.css
\Style Library\en-us\Core Styles\Vertical.css
\Style Library\en-us\Core Styles\SingleLevel.css
\Style Library\en-us\Core Styles\Band.css

[snip]

\Style Library\Images\blk_PageBackground.jpg
\Style Library\Images\blk_logo.jpg

Note, there is a folder called “en-us”, and within that are some additional styles. If you examine the sample master pages, you will see references to these styles in this format:

~language/Core Styles/Band.css%>” runat=”server”/>

~language/Core Styles/controls.css %>” runat=”server”/>

We now see two new tokens. ~SiteCollection which we have already seen and ~language. ~language is pretty obvious I think. It substitutes the current locale to create the path. Therefore, if you had to support an additional language in your branding, all you need do is create a folder in the Style library, named the same as the locale/language being used. SharePoint will create the path on the fly and render the language specific CSS file.

CleverWorkaround rating: Too easy!

Enough theory already! Let’s package up our branding.

Well.. as it turns out, I wrote an article on creating a feature some time back. I’ll regurgitate some of it here, but using the PIMPMYSHAREPOINT.MASTER example above.

All features live in a folder on the web front end server.

C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\FEATURES

To create a new feature, all you need to do is create a new folder under here. Until you activate the feature, this folder will have no effect on the system. Let’s call this feature folder “PimpMySharePoint”

C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\FEATURES\PimpMySharePoint

Inside this folder we place our master page, 3 CSS files and 3 images as shown below

So, now we need to do the glue that when the feature is activated after being installed, will copy these files into their correct locations in the site collection . We have to create 2 XML files that do this work.

The first XML file is always called FEATURE.XML.

Feature.XML

Now in real life, you will copy a FEATURE.XML from one of the many other features here and work off that. But in our case, we will just type it in. The content of FEATURE.XML is below:

Title=”Pimp my SharePoint”
Description=”This is a feature that adds a new sexy CSS”
Version=”1.0.0.0″
Scope=”Site”
xmlns=”http://schemas.microsoft.com/sharepoint/”>

So inside this XML file, we have a element and inside that an element. SharePoint examines this XML file when installing the feature.

The required parameters for the element are below (lifted straight from MSDN)

Attribute	Description
Description	Optional String. Returns a longer representation of what the Feature does.
Id	Required Text. Contains the globally unique identifier (GUID) for the Feature.
Scope	Required Text. Can contain one of the following values: Farm (farm), WebApplication (Web application), Site (site collection), Web (Web site).
Title	Optional Text. Returns the title of the Feature. Limited to 255 characters.
Version	Optional Text. Specifies a System.Version-compliant representation of the version of a Feature. This can be up to four numbers delimited by decimals that represent a version.

So, the first thing to do is generate a GUID. You can do this a number of ways, but I typically use an online generator like the one here to do it. My GUID from the online generator is: 01c34560-6561-11dc-8314-0800200c9a66. Feel free to use it for this example but you should substitute with your own.

The “Title” and “description” parameters should be plainly obvious and “version” is optional, but whack it in anyway. “Scope” is important, a feature can be activated at various points in the farm. “Site” means it is activated once per site collection. All sub-sites under this site collection can make use of the feature without having to activate it. This will become clear later.

Next we refer to an . This is a reference to another XML file that actually tells SharePoint what to do when this feature is activated on a site collection. (I have called the XML file PROVISIONEDFILES.XML but you can call it anything you like.

The Element Manifest File

Let’s take a closer look at the element manifest file called ProvisionedFiles.XML since it does all the grunt work of copying the files into the right locations on the site collection.

http://schemas.microsoft.com/sharepoint/”>

So as you can see in the above XML file, we have used an XML element called MODULE twice. One contains 1 FILE element – the master page. The other contains 7 FILE elements – one for each CSS and image file in the branding.

So what the heck is MODULE anyway? Well, it is one of several elements that you can use in an element manifest file to perform particular administrative installation actions. Here is list of the common things that a feature may install/create:

Content Types: Contains a definition of a SharePoint content type.
Content Type Binding: Actually applies a content type to a document library.
Control: Allows you to replace existing controls on the page, such as the search or navigation with your own custom control.
Custom Action: You can define custom actions such as add a new menu item in “Site Actions”.
Feature/Site Template Association: This allows you to bind a feature to a site template so that the feature is included in new sites based on that template.
Field: Contains a field, or column definition that can be reused in multiple lists.
Hide Custom Action: Opposite to “Custom Action”, where you want to hide menu items.
List Instance: Provisions a SharePoint site with a list which includes specific data.
List Template: A list definition or template, which defines a list that can be provisioned to a SharePoint site.
Module: Deploys files which are included when provisioning sites.
Receiver: Defines an event handler for a list, or document library
Workflow: Defines a workflow for a list, or document library.

So what do we have third from the bottom? Why it’s a “MODULE” element! What does it do? “Deploys files which are included when provisioning sites”. Eureka!

Now let’s examine the and its child element element in more detail.

Module Element	Description
Name	Required Text. Contains the name of the file set.
RootWebOnly	Optional Boolean. TRUE if the files specified in the module are installed only in the top-level Web site of the site collection.
Url	Optional Text. Specifies the virtual path of the folder in which to place the files when a site is instantiated. If Path is not specified, the value of Url is used for the physical path. Use the Url attribute to provision a folder through the Feature.

File Element	Description
IgnoreIfAlreadyExists	Optional Boolean. TRUE to provision the view even if the file already exists at the specified URL; otherwise, FALSE.
Type	Optional Text. Specifies that the file be cached in memory on the front-end Web server. Possible values include Ghostable and GhostableInLibrary. Both values specify that the file be cached, but GhostableInLibrary specifies that the file be cached as part of a list whose base type is Document Library.When changes are made, for example, to the home page through the UI, only the differences from the original page definition are stored in the database, while default.aspx is cached in memory along with the schema files. The HTML page that is displayed in the browser is constructed through the combined definition resulting from the original definition cached in memory and from changes stored in the database.

So, in CleverWorkarounds english, the section is specifying the location that any elements be copied to. For each file to be copied, there is a corresponding element. We discussed in the previous section on file locations, that master pages will reside in the _catalogs/masterpage library (the master page gallery). Styles will reside in the “Style Library” document library,

Since we have two locations, we have two entries for the master page gallery and style library.

So, according to the element manifest for our custom feature, we will copy the files:

PimpMySharePoint.CSS
PimpMintyFresh.CSS
PimpBlingGold.CSS
PimpGothicBlack.CSS
PimpMintyFreshBack.JPG
PimpBlingGold.JPG
PimpGothicBlack.JPG

To the Style Library and we will copy:

PimpMySharePoint.Master

To the master page gallery.

That’s it for the feature file. Let’s test that it works!

Installing the Feature

So here is our feature folder again with the 2 XML files described in the previous sections.

Installing the feature now is pretty easy. It is best done via opening up a command prompt on each SharePoint web front end server on the farm. Then we use the STSADM command to do the deed via the “STSADM –o installfeature” command. This command takes a couple of parameters.

Use either the -name or the -filename argument to select a feature.

Use -force to install the feature even if it is already installed and activated somewhere in the farm

When the -name parameter is specified, SharePoint knows to look in the TEMPLTE\FEATUIRES folder already, so you do not have to specify a full path. For example:

Testing the installation

Okay, so the feature is installed. Now what? Now we need to activate this feature on a site collection. Here is the “Style Library” of my test site. (Remember that this library will not exist unless the SharePoint Publishing Infrastructure feature has been installed). Note that at this time, there is no CSS files called PIMP*.CSS

So now let’s Activate the feature. Browse to Site Actions>Site Settings and from the Site Collection Administration menu, choose “Site Collection Features”. Lo’ and behold! We have our feature listed! Note the title and description is as per our FEATURE.XML file.

Click “Activate” to activate the feature (you can also do this on the command line via STSADM -o activatefeature command). Once it is marked as active, re-examine the style library. Woo freakin’ hoo! There are our CSS files!

And the master page gallery? YES! It’s there (amongst all the other stuff the publishing feature puts there).

Testing the Feature

In our example here, we can test this feature by choosing the new master page from the look and feel section of site settings.

Then, once we have chosen PIMPMYSHAREPOINT.MASTER, we can choose one of the theme CSS files to use with it in the same page as above, just further down.

Are we done then?

So if you have gotten this far, thanks (no really… thanks) for sticking with me. I know this is a hard slog, but trust me, it will save you some heartache.

Now if you are working on a single server farm, or a smallish farm, then you may well be done. Unfortunately, for many however, we are not done yet! (aw crap – you think after 4 really long winded articles I’d finally be finished but noooo.. SharePoint is a complex beast and there is still more to go in this area.)

So in the next article, I will delve into how you can improve this feature by having the master page automatically selected when it is activated, then how to go about upgrading a feature, some of the quirks and dare I say it, bugs, that currently exist around branding and packaging, as well as when and why a feature should be incorporated into a SharePoint solution.

Cheers

No Tags

SharePoint Branding – How CSS works with master pages – Part 3

admin — Sat, 13 Oct 2007 00:00:07 +0000

Welcome to the third article (or is it a manifesto?) in my series on SharePoint branding. In this article, we continue examining methods to incorporate CSS files into master pages for clever branding. In my first article of this topic, I discussed what I think is the main issue with SharePoint branding – APPLICATION.MASTER and CORE.CSS. The previous article to this one, examined 5 methods to deal with the trial and tribulations of APPLICATION.MASTER and CORE.CSS behavior. So, to recap where we got to, let’s re-examine the original scenario and then look at the summary of the 5 different several methods with their relative merits and issues.

The Scenario

Like many organizations, my client had an existing corporate branding standard that was used in a non SharePoint environment and naturally enough, they wanted their SharePoint site to look like this branding. This was for a fully featured intranet/extranet that utilized most of the MOSS2007 features such as

Document collaboration
Infopath Forms Services
Workflow
Enterprise Search
Excel services
Business Data Catalog
Custom web parts
Event Handlers

It was *not* a public site at all.

Initial investigation soon concluded that we would need a custom master page. DEFAULT.MASTER didn’t quite have the design flexibility that was required. In fact the branding requirements were actually closer to some of the built in master pages such as BLUEGLASS.MASTER, since this was for intranet purposes, particularly collaborative document management, those master pages are unsuitable.

Other major requirements included mandatory consistency of branding across the entire farm. This meant that we had to deal with the APPLICATION.MASTER issue. Additionally, different semi-autonomous divisions within the client’s organisation wanted to be able to modify the corporate brand in accordance with existing branding policy (mainly colours/skinning) while maintaining the existing structural look and feel.

Additionally, as well as the corporate branding, there was another, very different branding which was used as part of a communications plan for some organizational change stuff. This had a deliberately different look to the rest of the site, yet the web designer had been clever when this design was created. They were able to completely rebrand the look and feel of the additional branding just through additional CSS and not wholesale HTML structural changes.

So, really, we had two general classes of sites. ‘Standard’ corporate sites and the custom branded ‘Organisational Change’ site.

The type of MOSS environment this was to be applied to was a medium to large SharePoint farm with three web front end (WFE) servers, and there were several SharePoint web applications and site collections in the farm that needed this branding. Further down the track, there was to be other SharePoint farms in different offices around the world with localized language requirements.

The final requirement (the one that complicated things) was that many of the CORE.CSS styles needed to be overridden to ensure the branding was correct.

Summary of CSS methods

Method	Advantages	Disadvantages
SharePoint:CSSRegistration	- Easy to implement	- Does not overrides core.css - Does not work with _layout pages
Master Page Settings	- Easy to implement - Overrides core.css - Works on _layout pages	- Can only be used once - Has to be set up for each site
method	- Set in master page once - Overrides core.css	- Precludes "Master Page Settings" CSS override - Does not work with _layout pages
Michael’s webcontrol	- Set in master page once - Overrides core.css - Works nicely with "Master Page Settings" CSS override	- Does not work with _layout pages - core.css as the first CSS can be problematic
My webcontrol	- Set in master page once - Overrides core.css - Works nicely with "Master Page Settings" CSS override - core.css is not the first stylesheet in the list - allows choice as to what css overrides core.css	- Does not work with _layout pages

Now for many SharePoint logical architectures, these methods will likely work well. Unfortunately in my situation each had enough drawbacks that I kept looking. So next stop: SharePoint Themes.

Over-riding CSS – SharePoint Themes

In my humble opinion, when you examine themes, it smells a little like legacy WSS/SharePoint 2 functionality carried over and now adds to confusion rather than clarifies. This is purely a hunch of course, but given the way themes have to be installed, and their scope across the farm, suggests to me that it may become a legacy feature going forward.

Why do I think this? Well, the official purpose a SharePoint theme is for ‘skinning’ a site, but at the end of the day, a theme is just another CSS file, only implemented a different way. Being CSS, you can define any style you want here, not just the ones related to colour. Furthermore, the styles defined in themes can be used in any other other CSS files too.

Okay, so it is essentially another form of CSS file… then what is the difference between this and the other methods CSS I have outlined?

Well, for a start, theme CSS files live in a sub-folder of on the server:

C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\THEMES

So, this is a location on the web front end server/servers, whereas with the other methods, the CSS files reside inside a document library of a site collection. I believe that document library is a better choice because you have all those niceties like versioning, approvals and recycle bin, etc. If you have a farm of WFE servers, you would have to add your theme to each server and hope no mistake was made.

On top of being in every WFE server folder, just making a CSS file and dropping it in here is not enough either. Examining one of the pre-supplied themes shows that a theme consists of CSS files, an INF file, and of course, the images referred to by the styles. The two CSS files are called THEME.CSS and MOSSEXTENSION.CSS. (When you apply a theme to a site, MOSSextension.css is appended to the bottom of your theme.css)

The INF file is always the name of the theme folder, eg

\12\TEMPLATE\THEMES\CITRUS contains CITRUS.INF

So you create a folder, add the CSS, INF and images, and finally, you then have to tell SharePoint about it. This is done by modifying a single XML file called SPTHEMES.XML.

SPTHEMES.XML can be found in:

C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\LAYOUTS\1033

A typical entry will look like:

<Templates>
    <TemplateID>PimpMySharePointTemplateID>
    <DisplayName>Pimp meDisplayName>
    <Description>A pimped sharepointDescription>
    <Thumbnail>images/thpimp.gifThumbnail>
    <Preview>images/thvpimp.gifPreview>
templates>

So let’s look at an example.

I have taken a copy of the CLASSIC folder under THEMES, info a folder called PIMPMySharePoint. I’ve then renamed CLASSIC.INF to PIMPMYSHAREPOINT.INF and added this theme to SPTHEMES.XML.

I then run IISRESET and open up my site collection. Go to Site Actions->Site Settings and choose "Site Theme"

Now you should see your "Pimp SharePoint" theme listed

Click apply and re-examine the page. You will see that the look and feel of the site will have changed.

Now examine the HTML source in the browser. You will see something like

<link rel="stylesheet" type="text/css" href="/_layouts/1033/styles/controls.css?rev=EhwiQKSLiI%2F4dGDs6DyUdQ%3D%3D"/>
<link rel="stylesheet" type="text/css" href="/_layouts/1033/styles/HtmlEditorCustomStyles.css?rev=8SKxtNx33FmoDhbbfB27UA%3D%3D"/>
<link rel="stylesheet" type="text/css" href="/_layouts/1033/styles/HtmlEditorTableFormats.css?rev=guYGdUBUxQit03E2jhSdvA%3D%3D"/>
<link rel="stylesheet" type="text/css" href="/_layouts/1033/styles/core.css?rev=5msmprmeONfN6lJ3wtbAlA%3D%3D""/>
<link rel="stylesheet" type="text/css" id="onetidThemeCSS" href="/sites/ft1/_themes/PimpSharePoint/Pimp1011-65001.css?rev=12%2E0%2E0%2E6007"/>

Note that the theme (in bold) is rendered after core.css.

How did this happen?

You should already be familiar with SharePoint:CssLink and SharePoint:CssRegistration webcontrols via my previous articles. Behind the scenes to all of this, the theme is rendered via an additional control called the in the master page. Here is DEFAULT.MASTER source code that produced the above output

<Title ID=onetidTitle><asp:ContentPlaceHolder id=PlaceHolderPageTitle runat="server"/>Title>
<SharePoint:CssLink runat="server"/>
<SharePoint:Theme runat="server"/>

If you look carefully at the above source code, you will see that the only reason that the theme has overriding CORE.CSS is because the SharePoint:Theme control is listed after Sharepoint:CSS. If you reverse the order of the two controls, as expected the order of the theme is changed. In the example below, I took a copy of DEFAULT.MASTER and made the following modification:

<Title ID=onetidTitle><asp:ContentPlaceHolder id=PlaceHolderPageTitle runat="server"/>Title>
<SharePoint:Theme runat="server"/>
<SharePoint:CssLink runat="server"/>

and the resulting HTML is now reversed with CORE.CSS once again last.

<link rel="stylesheet" type="text/css" id="onetidThemeCSS" href="/sites/ft1/_themes/PimpSharePoint/Pimp1011-65001.css?rev=12%2E0%2E0%2E6007"/>
<link rel="stylesheet" type="text/css" href="/_layouts/1033/styles/controls.css?rev=EhwiQKSLiI%2F4dGDs6DyUdQ%3D%3D" />
<link rel="stylesheet" type="text/css" href="/_layouts/1033/styles/HtmlEditorCustomStyles.css?rev=8SKxtNx33FmoDhbbfB27UA%3D%3D" />
<link rel="stylesheet" type="text/css" href="/_layouts/1033/styles/HtmlEditorTableFormats.css?rev=guYGdUBUxQit03E2jhSdvA%3D%3D" />
<link rel="stylesheet" type="text/css" href="/_layouts/1033/styles/core.css?rev=5msmprmeONfN6lJ3wtbAlA%3D%3D" />

Thus, although you will read that themes are used to say, "re-skin the layout of a site", in reality, it is the order of the application of CSS files that determine what parts of a site a theme will modify. Put in a different way, you add whatever you like to the theme CSS files and it will act like any other CSS, except it gets rendered last by default.

Heather notes that themes have the same benefit as using "Master Page Settings" to override CORE.CSS. That is, they also apply to _layouts pages and affect APPLICATION.MASTER. The only reason that they work here is because the APPLICATION.MASTER master page used for _layout pages has the SharePoint: Theme webcontrol in its source code.

A gotcha with this method is that themes are per farm. Since they reside on the web front end server, my "Pimp Sharepoint" theme is available to any site in the farm. What’s more, if I modify the theme here, all sites are modified. This can be good but is equally going to catch you out as your SharePoint farm grows.

Another gotcha! Do not for a second assume that the SharePoint:Theme control is always included in master pages because it is not! Go and check the master pages that are installed by the "Office SharePoint Server Publishing Infrastructure" feature and you will see that none of them use the SharePoint:Theme webcontrol. Therefore, no matter what you put as your theme for sites based on publishing master pages, only the _layout pages (based on APPLICATION.MASTER) are affected by the theme CSS. (This to me reinforces my belief that themes are a legacy technology.)

Another gotcha! You will not like themes if you have a lot of sub-sites because you have to apply it at the site level for each site. Unlike the other methods described thus far, this method is not inheritable to sub-sites.

Yet another issue that makes this method a low cleverworkarounds rating, is that themes have to be installed on the web front end servers. In a large scale farm, there may be several WFE servers that need this set. There is no version control, version history, recycle bin, publishing approvals, and as a developer it means you have to deal with anal SharePoint infrastructure or governance Nazis who will not even talk to you unless you have packaged your work up as a solution.

Cleverworkaround Rating: Sucky

Overriding CSS – Master Page Settings with @import

This is a method that I considered but did not test, although I am sure that it will work (so I would be happy to hear from anyone who did). It actually needs to be used in combination with the "master page settings" method that I described in article 2. The idea here is based around strict naming conventions for CSS files.

Now remember my original scenario, I have a master page, and a corporate brand CSS that needs to override CORE.CSS (CSS number #1). But then I have additional CSS files that override the corporate brand CSS file depending on the site. Using the master page settings to specify a CSS file only deals with CSS number 1.

But my idea here is that the CSS to be specified in Master Page Settings (CSS number 1) , refers to one of more additional CSS via the @import directive. The names are strictly defined, so for example:

@import url(brandingoverridemintyfresh.css);

@import url(brandingoverrideorgchange.css);

So now, you have two extra CSS ‘placeholders’. If they do not exist in the site collection, they will not be used. But if you put a CSS file into the site collection, and give it one of the above names, you should in theory get the additional styles required.

This method seems relatively simple in the sense that it is all done in the CSS files, and the SharePoint GUI. However, since by default the CSS files reside in the site collection style library, adding or removing CSS files affect the entire site collection. This behavior can probably overridden with hard-coded or relative URL’s but it will not be great. Hard-coding anything is "not clever" for scalability and flexibility, and relative URL’s are difficult because site collections are not necessarily top level sites.

In addition, your CSS file can get ugly, with lots of @import references to files that do not exist which will confuse things later if governance around this is not well handled.

I won’t assign this a rating, given that I didn’t test it. But I can see it would have its uses in some circumstances. If someone wants to experiment with this I’m happy to link you, or add to this article.

My solution

Now despite the fact that I’ve in effect bagged themes earlier, the actual styles defined in the themes are some of the ones you are likely to be interested in, when performing a branding exercise. It is this fact that led me to my final solution that for me, had the best clever rating of all.

So let’s now examine our matrix so far with the addition of the themes method.

Method	Advantages	Disadvantages
SharePoint:CSSRegistration	- Easy to implement	- Does not override core.css - Does not work with _layout pages
Master Page Settings	- Easy to implement - Overrides core.css - Works on _layout pages	- Can only be used once - Has to be set up for each site
method	- Set in master page once - Overrides core.css	- Precludes "Master Page Settings" CSS override - Does not work with _layout pages
Michael’s webcontrol	- Set in master page once - Overrides core.css - Works nicely with "Master Page Settings" CSS override	- Does not work with _layout pages - core.css as the first CSS can be problematic
My webcontrol	- Set in master page once - Overrides core.css - Works nicely with "Master Page Settings" CSS override - core.css is not the first stylesheet in the list - allows choice as to what css overrides core.css	- Does not work with _layout pages
Custom Themes	- Easy to implement (GUI set) - Overrides core.css - Works on _layout pages	- Modifying the theme modifies all sites using it - Not inherited – has to be manually set for all sites - Installing and updating themes require farm administrator and manual configuration of WFE servers - Not all master pages will obey the theme

Over-riding CSS – The hybrid!

Now remember my original scenario, I have a master page, and a corporate brand CSS that needs to override CORE.CSS (CSS number 1). But then I have additional CSS files (let’s collectively call them CSS number 2), that override the corporate brand CSS file depending on the site. CSS number 2 assumes that CSS number 1 is also referenced. This keeps CSS number 2 smaller and more manageable. But the disadvantage is that as discussed, using the master page settings to specify a CSS file can only be used once and therefore only deals with CSS number 1.

But…what if we took all of the bits that needed to be overridden CORE.CSS and moved them to CSS number 2? Then CSS number 1 is left with styles that CORE.CSS does not interfere with.

CSS number 2 (remember there are potentially many of these) is a little bigger now, as it has some additional styles since now it has to deal with any CORE.CSS interference, however it is still relatively maintainable.

So then, we can do this… (…drumroll)

Have the generic branding (CSS number 1) added to the master page using the SharePoint:CSSRegistration method. Then any CSS number 2, can be specified by the ‘master page settings’ method.

So to illustrate, let’s take a look at the source code to our branded master page.

<SharePoint:CssLink runat="server"/>
 <SharePoint:CssRegistration name="<% $SPUrl:~SiteCollection/Style Library/~language/Core Styles/Band.css%>" runat="server"/>
  <SharePoint:CssRegistration name="<% $SPUrl:~sitecollection/Style Library/~language/Core Styles/controls.css %>" runat="server"/>
 <SharePoint:CssRegistration name="<% $SPUrl:~sitecollection/Style Library/zMyDefaultBrand.css %>" runat="server"/>
  <SharePoint:Theme runat="server"/>

So, looking at this code, you can see that we are using SharePoint:CssRegistration, to specify a CSS file called zMyDefaultBrand.css. Remember why I prepended it with a z? It’s because SharePoint:CssLink control renders CSS files in alphabetical order it will be rendered last by the CSSLink webcontrol, except for CORE.CSS of course.

You can also see that I left the SharePoint:Theme control in so it can be used if required.

So, since we have moved all the CORE.CSS overrides to CSS number 2, we have a default CSS file called MyTheme.css. This now goes hand in hand with zMyDefaultBrand.css and is set set via the "master page settings" screen.

So the rendered HTML code combines to this:

<link rel="stylesheet" type="text/css" href="/sites/pc/Style%20Library/en-US/Core%20Styles/Band.css" mce_href="/sites/pc/Style%20Library/en-US/Core%20Styles/Band.css"/>
<link rel="stylesheet" type="text/css" href="/sites/pc/Style%20Library/en-US/Core%20Styles/controls.css" mce_href="/sites/pc/Style%20Library/en-US/Core%20Styles/controls.css"/>
<link rel="stylesheet" type="text/css" href="/sites/pc/Style%20Library/zMyDefaultBrand.css" mce_href="/sites/pc/Style%20Library/zMyDefaultBrand.css"/>
<link rel="stylesheet" type="text/css" href="/sites/pc/_styles/core.css" mce_href="/sites/pc/_styles/core.css"/>
<link rel="stylesheet" type="text/css" href="/sites/pc/Style%20Library/MyTheme.css" mce_href="/sites/pc/Style%20Library/MyTheme.css"/>

Let’s look at the result and compare with our requirements. As you can see, CORE.CSS still beats zMyDefaultBrand.css but it is subsequently beaten by MyTheme.css, so we can override any CORE.CSS quirks.

Since MyTheme.CSS contains all of the look and feel styles that are usually defined in the SharePoint themes and CORE.CSS, the _layouts pages based on APPLICATION.MASTER get overridden nicely. By splitting the CSS we are able to define the global style in zMyDefault.css and the *default* CORE.CSS override in MyTheme.CSS

Since we are using master page override method, this is set on a per site basis and is inheritable from a parent site. Now our web designers can work their CSS magic to make additional MyTheme.css type files to offer flexible branding options such as MyThemeMintyFresh.CSS or MyThemeCorporateBrandB.CSS. Web administrators can pick the CSS file they want to use on a site by site basis giving complete flexibility.

Wohoo!

Cleverworkaround rating: Nice

Summary

So here is the final version of my table..

Method	Advantages	Disadvantages
SharePoint:CSSRegistration	- Easy to implement	- Does not override core.css - Does not work with _layout pages
Master Page Settings	- Easy to implement - Overrides core.css - Works on _layout pages	- Can only be used once - Has to be set up for each site
method	- Set in master page once - Overrides core.css	- Precludes "Master Page Settings" CSS override - Does not work with _layout pages
Michael’s webcontrol	- Set in master page once - Overrides core.css - Works nicely with "Master Page Settings" CSS override	- Does not work with _layout pages - core.css as the first CSS can be problematic
My webcontrol	- Set in master page once - Overrides core.css - Works nicely with "Master Page Settings" CSS override - core.css is not the first stylesheet in the list - allows choice as to what css overrides core.css	- Does not work with _layout pages
Custom Themes	- Easy to implement (GUI set) - Overrides core.css - Works on _layout pages	- Modifying the theme modifies all sites using it - Not inherited – has to be manually set for all sites - Installing and updating themes require farm administrator and manual configuration of WFE servers - Not all master pages will obey the theme
My Hybrid Method	- Easy to implement (GUI set) - Overrides core.css - Works on _layout pages	- master page setting is always specified

Next steps

I am a two finger typist, so after 3 articles you would think we are done. But nooooo, we still haven’t solved all of the issues. Next stop, we examine how to deploy this to the farm set-up in a nice, easy to maintain format. So we do some work on features, solutions, quirks (yeah there are quirks) and governance around it all.

No Tags

SharePoint Branding – How CSS works with master pages – Part 2

admin — Wed, 10 Oct 2007 19:33:39 +0000

Jeez if I had realised how long it would take to write these damn articles, I probably wouldn’t have started! In my first article of this topic, I discussed the theory behind master pages, the publishing feature, and what I think is the main issue with SharePoint branding – APPLICATION.MASTER and CORE.CSS. In this article I will now list a branding scenario that I had to deal with, and the various options you can use to deal with the challenges of APPLICATION.MASTER and CORE.CSS

The Scenario

This was for a fully featured intranet/extranet that utilized most of the MOSS2007 features such as

Document collaboration
Infopath Forms Services
Workflow
Enterprise Search
Excel services
Business Data Catalog
Custom web parts
Event Handlers

It was *not* a public site at all.

Other major requirements included mandatory consistency of branding across the entire farm. This meant that we had to deal with the APPLICATION.MASTER issue as described in my last post. Additionally, different semi-autonomous divisions within the client’s organisation wanted to be able to modify the corporate brand in accordance with existing branding policy (mainly colours/skinning) while maintaining the existing structural look and feel.

So, really, we had two general classes of sites. ‘Standard’ corporate sites and the custom branded ‘Organisational Change’ site.

The final requirement (the one that complicated things) was that many of the CORE.CSS styles needed to be overridden to ensure the branding was correct.

The Custom Master Page

The first decision to make is whether to stick to just CSS modifications to an existing master page, or to create a new master page. This post is based around a new master page, however the CSS methods I outline in this post are equally valid when using, say, DEFAULT.MASTER or one of the publishing master pages like BLUEBAND.MASTER.

So since we knew we had to use a custom master page, we had 3 choices in creating a new master page.

Make a copy of DEFAULT.MASTER and use that
Start with a completely blank master page
Make a copy of one of the publishing master pages like BLACKBAND.MASTER

I’ll actually deal with the third option first because we initially used it and then discounted it.

As previously mentioned, in our case BLUEGLASS.MASTER was the closest of the built in master pages to our branding needs but in the end we did not use it. Publishing master pages are actually somewhat simpler than the default.master page. Some web controls/placeholders have been modified/removed from publishing master pages, and if you use them for say, a document collaboration site, you will find quirks like:

Missing breadcrumb navigation in document libraries when browsing subfolders
Missing recycle bin link
Different navigational structure
Tree-view not being rendered despite being selected
Themes are ignored (I discuss this in detail in part 3)

Furthermore, I actually read not so long ago that it was recommended that these pages be generally used for internet facing sites which by definition tend to be publishing sites. (I’m trying to find the reference and as soon as I locate it I’ll paste here), but Tyler’s post offers some hints where he talks of custom CSS and navigation out of the box.

A blank master page is potentially a great option, either the MSDN one that everyone seems to hate or Heather’s, that the general population seems to like. Ultimately flexibility, of course, as it means that you can code up the look and feel from scratch. Unless you are a world class web designer and have a great understanding of ASP.NET, it may not be worth the time and budget (especially for an internal facing site).

So, we chose to simply make a copy of default.master because we actually did not have to change that much to achieve our ends. Yes it is complex and fiddly, but it is the out of the box master page that works with SharePoint, so using it as a base is a pretty safe bet. The main issue you need to watch out for when doing this, is related to the publishing feature.

So, for the purposes of this article, our new master page will be referred to as PIMPMYSHAREPOINT.MASTER – and we have to get our custom CSS styles into this.

Over-riding CSS – SharePoint:CSSRegistration

We took a look at SharePoint:CssRegistration and its brother SharePoint:CssLink in part 1, but I think it’s worth a recap.

SharePoint:CssRegistration defines a CSS file and Sharepoint:CssLink is the control that actually renders the SharePoint:CssRegistration styles as well as CORE.CSS.

[snip]

[snip]

And the result is…

[snip]

[snip]

As discussed in part 1, CORE.CSS, has been rendered, despite the fact that it is not explicitly defined. What’s more, CORE.CSS is always listed last.

Ah! But remember our requirement above? Our custom styles need to override styles in CORE.CSS! GONG! This isn’t going to do it for us.

Cleverworkaround Rating: Useless for me

Over-riding CSS – Master Page Settings

So we look at the next most obvious way to defeat this CORE.CSS issue. On a MOSS07 site with the "Office SharePoint Server Publishing Infrastructure" site collection feature enabled, we have the means to add a custom CSS to a master page via the GUI. It can be found in Site Settings on any site. Navigate to look and feel and choose "Master Page".

Scroll to the bottom of this page and you will see the CSS override settings.

From here, you can choose a custom CSS file to use. In this example we have chosen pimpmysharepoint.css which was uploaded to the style library for this site collection. Let’s examine the HTML output once pimpmysharepoint.css has been selected.

Aha! We have overridden CORE.CSS – nice! Given that we have not modified the master page itself, we can conclude that SharePoint:CssLink will render the "alternate CSS URL" last. In addition, we have solved the APPLICATION.MASTER problem. Hands up who can tell me why ? The reason is that APPLICATION.MASTER uses SharePoint:CssLink as well, so it will render this CSS in _layout pages derived from that master page.

Furthermore, we did it with no coding or custom work, and it can be inherited or forced out to all subsites from this one. WOHOO!

So? Have we found our clever workaround? No we have NOT. DOH! We have a workaround, but I do not believe that it’s clever yet!

Remember my requirements. We had a corporate brand that required CORE.CSS override for a few styles. In addition, we have the ‘organizational change’ branding CSS that overrides the corporate branding CSS. In addition, even within corporate branding we had CSS overrides for individual departments too.

So what is our problem then?

Using this method, we can only override once! Once you set this alternate CSS, that’s it. Thus, if I was to use this method, I would have to maintain several large custom CSS files, one for each branding scenario. Given that 80% of the actual styles are consistent between them, I prefer a method where the common stuff is kept common, rather than risk being fragmented over time with changes to one of the CSS files not being propagated to others.

I’m sure many of you would be okay with this, and for certain clients, I would be too. However, call me anal if you want but I wanted to find a better way.

CleverWorkaround Rating: Close, but no cigar!

Over-Riding CSS – Static CSS Link

Now, given that SharePoint:CssLink control renders stylesheet links at runtime, what is stopping us simply adding a static CSS link in the master page? The source code below illustrates the idea.

[snip]

[snip]

This works on the premise that 80% of your branding (the stuff that CORE.CSS doesn’t screw with) is in PIMPMYSHAREPOINT.CSS. The other 20% that needs to override CORE.CSS is in ANOTHERCSS.CSS.

So, now I have embedded a static link into the master page. Before we go on to assess its cleverness, can you see my mistake?

Imagine, that you have 3 site collections named:

That static link, will always try and use the style library for the top site collection, even for the bottom two site collections. But what if the users do not have permission to the top site collection? Will the CSS render? Probably not as access to it would be denied.

Here is the adjusted source to fix this – using a token to render the correct site collection URL.

[snip]

[snip]

>

See what I have done (in bold)? I have placed the rendered link into the master page source. I have used the $SPURL:~SiteCollection token though which at runtime gets replaced with the path to the site collection. (In the example below the site collection was called "/sites/nopub").

So let’s examine the HTML output of this.

[snip]

[snip]

Wohoo! We have our custom styles after CORE.CSS. What’s more, we can add as many entries as we like here. Although not shown above, I could have one with the 80% of common styles and another with the 20% of custom ones.

So have we found our branding utopia? No – hell no!

One of the disadvantages with this method is that if your is placed AFTER SharePoint:CssLink, then it will also trump your "alternate CSS URL" setting described in the "master page setting" method. This is because the alternate CSS URL is rendered by SharePoint:CssLink. Placing your static link before SharePoint:CssLink is utterly pointless, because all of the CSS files specified by SharePoint:CssRegistration will trump the entry. The whole point here was to override CORE.CSS.

If that wasn’t bad enough, the clincher is that _layout pages, based on APPLICATION.MASTER master page, will not have this static link anyway. Therefore, your branding is inconsistent for _layout pages and in fact is likely WORSE because it will apply the 20% customizations of ANOTHERCSS.CSS but the other 80% of PIMPMYSHAREPOINT.CSS common styles will be missing.

CleverWorkaround Rating: Pretty damn crappy actually !

So, what can we try next?

Over-riding CSS – Mike’s method

Now this method I was very, very impressed with (and cursed that I did not think of it myself). Mike came up with a novel way to solve the CORE.CSS problem. He created his own asp.net control that REPLACES SharePoint:CssLink. He has inherited the CSSLink class and modified the rendered output to move CORE.CSS from last to first. Ingenious!

So, to implement this, you need to compile it to a DLL in visual studio. You need to copy the DLL into the global assemble cache, and then mark the web control as safe. This is done by making a modification to the section of the XML file, WEB.CONFIG of the web application that is going to render this control.

[snip]

Then, in the custom master page, you have to tell SharePoint how to find the DLL. It is called ‘declaring the assembly’. Here is Mike’s example:

<%@ Register Tagprefix="PublishingEnhancements" Namespace="MichaelHofer.SharePoint.PublishingEnhancements" Assembly="MichaelHofer.SharePoint.PublishingEnhancements, Version=1.1.0.0, Culture=neutral, PublicKeyToken=7ce575c89ea427a4" %>

And now, you delete the reference to in the master page and use Mike’s control.

Now, let’s examine the output when using this method.

[snip]

[snip]

So, CORE.CSS is now moved to the top and the world is a happy place! Or is it?

I had one problem with this method. Moving CORE.CSS unexpectedly changed the look of my branding. Then I realized the problem. Now CORE.CSS was being overwritten by every other style, and this was causing unforeseen side effects.

One other DOH problem. APPLICATION.MASTER will not reflect this change – so it has the same issue as the method.

Despite this, I am going to give Mike a high cleverworkaround rating for this solution, but I am going to have to take off one point because he did not package it up into a solution Mike will probably think this is terribly unfair, but on my SharePoint large farms with multiple WFE servers, if it is not a solution, it doesn’t go into production! (That’s the topic of part 4 of this series of articles).

CleverWorkaround Rating: Flawed genius – respect, man !

Over-riding CSS Files – My method

Inspired by Mike’s cleverness, I came up with an idea to improve his control. I dusted off VS2005 and added a public property called DefaultCSS. This holds the value of a CSS file I am interested in.

private string CSS;
public virtual string DefaultCSS
{
    get
    {
        return CSS;
    }
    set
    {
        CSS = value;
    }
}

Next I changed the render method, to swap the value stored in this property with CORE.CSS

protected override void Render(System.Web.UI.HtmlTextWriter output)
{
    // Let base render the stylesheets
    StringWriter sw = new StringWriter();
    base.Render(new HtmlTextWriter(sw));
    string renderedOutput = sw.ToString();
    if (this.CSS == null) {
        output.Write(renderedOutput);
    }
    else
    {
        // Split the styleSheets into an array
        string[] styleSheets = renderedOutput.Split(new char[] { ‘\n’ }, StringSplitOptions.RemoveEmptyEntries);
        if (styleSheets.Length == 0) {
            output.Write(renderedOutput);
        }
        else
        // Find reference of core and CSS property
        {
            int CSSRef = new int();
            int CoreRef = new int();
            for (int i = 0; i < styleSheets.Length; i++) {
                if (styleSheets[i].Contains(this.CSS)) {
                    CSSRef = i;
                }
                else if (styleSheets[i].Contains("core.css")) {
                    CoreRef = i;
                }
                else {
                    styleSheets[i] = styleSheets[i] + "\n";
                }
            }
            // Now swap those elements
            string tmp = styleSheets[CSSRef];
            styleSheets[CSSRef] = styleSheets[CoreRef] + "\n";
            styleSheets[CoreRef] = tmp + "\n";
            output.Write(string.Concat(styleSheets));}}
        }
    }
}

So, as with Mike’s control, I compiled it to a DLL and copied it into global assemble cache (GAC), and then marked the web control as safe in web.config.

Then, in the master page, I added a reference to my DLL.

<%@ Register Tagprefix="PublishingEnhancements" Namespace="cleverworkarounds.SharePoint.PublishingEnhancements" Assembly=" cleverworkarounds.SharePoint.PublishingEnhancements, Version=1.1.0.0, Culture=neutral, PublicKeyToken=7ce575c89ea427a4" %>

And now, you delete the reference to in the master page and use my version of the control. (Don’t forget to add the DefaultCSS property!).

I then packaged this up as part of my branding feature/solution (more on this in part 4) and then deployed with success. Now let’s examine the output when using this method.

[snip]

[snip]

So now, only ANOTHERCSS.CSS has been swapped with CORE.CSS. PIMPMYSHAREPOINT.CSS is rendered prior to both, but the key here is CORE.CSS is not rendered last!

So, was I a genius? Was this the clever workaround? Can I give myself a high clever rating?

Unfortunately not. Both Mike’s method and my BRO (blatant rip off) of his method fail to deal with the _layouts/APPLICATION.MASTER issue. In addition, this method requires the most customization. We need to add a DLL to the GAC, declare it in the master page, as well as tell the various SharePoint web applications that the control is safe to use.

If you do all this manually on a single server WFE farm, you can probably get away with this, but on a medium to large scale farm, it should be packaged up as a solution before being deployed.

CleverWorkaround Rating: Was a worthwhile exercise

So … let’s take a breath and recap on the 5 methods discussed so far and list their relative merits and disadvantages.

Method	Advantages	Disadvantages
SharePoint:CSSRegistration	- Easy to implement	- Does not overrides core.css - Does not work with _layout pages
Master Page Settings	- Easy to implement - Overrides core.css - Works on _layout pages	- Can only be used once - Has to be set up for each site
method	- Set in master page once - Overrides core.css	- Precludes "Master Page Settings" CSS override - Does not work with _layout pages
Michael’s webcontrol	- Set in master page once - Overrides core.css - Works nicely with "Master Page Settings" CSS override	- Does not work with _layout pages - core.css as the first CSS can be problematic
My webcontrol	- Set in master page once - Overrides core.css - Works nicely with "Master Page Settings" CSS override - core.css is not the first stylesheet in the list - allows choice as to what css overrides core.css	- Does not work with _layout pages

Now for many SharePoint logical architectures, these methods will likely work very well (Okay… maybe not the method). I hope that some people will find that one of these options solves their respective issues. Unfortunately in my situation each had enough drawbacks that I kept looking.

So, in part 3 of this series of articles, I will explain some more options, and explain the method that eventually worked the best for me.

No Tags

SharePoint Branding – How CSS works with master pages – Part 1

admin — Mon, 08 Oct 2007 05:04:31 +0000

This is version 2 of this article, after I went and accidentally blew away my first masterpiece that took literally days to write. If this has ever happened to you, don’t you hate it, that your second version is never as good as your first?

Quick Links: [Part 1, Part 2, Part 3, Part 4, Part 5, Part 6, Part 7]

Anyway, this is (attempt 2 of) part 1 of a series of articles that cover SharePoint branding in some detail. Kudos has to be given Heather Solomon especially for her wonderful site and articles on this subject (and author of the book to your left . In Addition, Andrew Connell and Mike have done some great work that helped me in this area.

So, SharePoint branding was the catalyst behind my deciding to make a blog and call it cleverworkarounds. The whole experience at times made me want to change careers, but I ultimately got there. I would go down one path, only to be stumped by a problem, and think I have the solution, only to find another quirk that needed another workaround. So the aim of cleverworkarounds is to determine the least dodgy way to implement branding of a SharePoint installation. No doubt people will disagree with the conclusions I’ve reached, but that’s expected since the cleverness of a workaround really depends on your needs.

So this series of articles will cover a few issues. First some basic master page theory, then I will talk about the difference between branding in WSS3 (the freebie version) and MOSS07 (the pricey one). I will then take you through the quirks of CSS and master pages. Subsequent articles will get into the details of branding techniques and finally finish off by covering the governance issues surrounding branding.

Master Page theory

This is a large topic in itself, but I will try and cover it quickly. Heather has written the definitive explanation for master pages so I’m trying here to cover the bits I want to cover without rehashing her great work. Suffice to say that the technology is actually part of ASP.NET and SharePoint simply leverages this (no point reinventing the wheel after all). Generally, most aspx pages in a SharePoint site will be derived from a Page Layout (content) page that itself, refers to a master page. Below is the MSDN diagram illustrating the concept.

MSDN has a good definition: "A master page contains references to elements that you can share across multiple pages in an Office SharePoint Server 2007 site, such as navigation, search controls, logon controls, and banner images. A master page can also contain the cascading style sheet (CSS) and ECMAScript (JScript, JavaScript) references that define the overall look and feel of your site. Commonly, every site—and therefore every page—in your site collection uses the same master page to present a consistent user experience across the entire site collection. Depending on your needs, you can use a different master page for one or for all of the sites in your site hierarchy to distinguish the various areas of your portal."

To illustrate this idea, below I have pasted the very top line in a resulting page "DEFAULT.ASPX" from a basic SharePoint site.

<%@ Page language="C#" MasterPageFile="~masterurl/default.master"
Inherits="Microsoft.SharePoint.WebPartPages.WebPartPage,Microsoft.SharePoint,Version=12.0.0.0,
Culture=neutral,PublicKeyToken=71e9bce111e9429c" meta:webpartpageexpansion="full"
meta:progid="SharePoint.WebPartPage.Document" %>

Note the reference to the token ~masterurl/default.master in the first line. This is a special token that represents the currently used master page. (I will drill down further on this in a few moments).

A master page, like DEFAULT.MASTER, will almost always refer to one or more CSS files to style the site. Below I have pasted some of the HTML browser output from the very same DEFAULT.ASPX that I referred to above.

<link rel="stylesheet" type="text/css" href="/_layouts/1033/styles/core.css?
rev=5msmprmeONfN6lJ3wtbAlA%3D%3D"/>

So in the example above, any ASPX page that uses DEFAULT.MASTER, refers to a CSS file called CORE.CSS.

Thus, SharePoint branding usually means either:

Using the default master page and simply overriding the built in CSS styles with your own
Creating a new master page and then overriding the built in CSS styles with your own.

So let’s drill down a little further, by looking at another master page and compare it with DEFAULT.MASTER. MOSS does come with some other master pages we can examine, but depending on your site template, you may have to activate the publishing feature. If you wondering what a feature is, check this post, and then come back

So let’s activate the publishing feature and see what happens.

WSS, MOSS and the Publishing Feature

This article is primarily written around MOSS07 and not WSS3, but WSS3 is worth a quick discussion. WSS can be branded using the techniques I outline here, but if you are being paid to brand a SharePoint site/farm, it is very likely you are using MOSS.

The reason for this, is that WSS3 does not have available a site collection feature called "Office SharePoint Server Publishing Infrastructure". It is this feature that gives you all the tools you need to manage branding easily from just the web browser, as well as provide some sample master pages and different styles to learn from.

Almost all branding articles I have read assume this feature is installed and activated, but it is not always active for a site collection, depending on the site template used to create the site collection. You will find it under "Site Collection Features" in the "Site Actions" -> "Site Settings" screen.

So if you cannot find this feature listed, you are probably using WSS3. Sorry, but you are going to have a more fiddly time because you have to change your master page using SharePoint Designer (Kathy has written a nice overview here). But to get a quick sense of the idea, re-examine the reference to the master page token below..

<%@ Page language="C#" MasterPageFile="~masterurl/default.master"

In WSS, this refers to what SharePoint designer calls the "Default master page". Below, I show where I have taken a copy of DEFAULT.MASTER and called it PIMPMYSHAREPOINT.MASTER and set it as the default master page. Note that when I right click on PIMPMYSHAREPOINT.MASTER I have an option to set this as the default master page.

So now, when SharePoint loads pages on this site, the token "~masterurl/default.master" is replaced at run time by the default master page set above – "pimpmysharepoint.master".

Of course, if you have MOSS2007 and enable the publishing feature, you have a much easier method to change the master page for a site that does not involve SharePoint designer. So let’s enable this site collection feature and see what happens.

First up, (note below what a site collection looks like without this publishing infrastructure feature activated), you have a master page gallery link, but under "look and feel", there are no options related to choosing any other master pages.

If you open the site up in SharePoint designer, you will also see a basic SharePoint structure. Below shows a SharePoint site collection created using the blank SharePoint site template.

So now let’s activate the site collection feature "Office SharePoint Server Publishing Infrastructure" and re-examine the above site. Note the change in options, particularly in relation to "Look and Feel". We now have a link for choosing which master page to use. That saves you having to fiddle with SharePoint Designer, doesn’t it?

It is when you look at the site collection in SharePoint Designer though, that you see the significant changes which have been made. There are a lot more goodies there now in the form of Lists, Document Libraries and Workflows. Thus, the publishing feature does a lot more than simply add a link to choose a master page. Penny has a great, detailed description of the additional resources installed by enabling this feature

So, now let’s choose a different master page. Under "Master Page Settings" in the "Look and Feel" section of site administration, you will see a selection of example master pages that come with the feature.

Now, at this point, I will throw you a little theory. With WSS, I explained how you can use SharePoint designer to change the master page to set the default master page. But MOSS gives you the nice method of being able to do this via the administration pages for a site collection. Both methods look in the same place – The master page gallery.

When you provision a site collection the system creates a master page gallery that contains all the master pages and page layouts for that site collection. The master page gallery is stored at the location /_catalogs/masterpages. It is a standard document library and as a result has version history, recycle bin support, approval workflow and all of the other document management goodies you get with SharePoint. This is great, since it makes it easy to roll back if an update to a master page file goes horribly wrong. No matter how many sub sites you make in the site collection, they will all be able to access the master page library via the link to /_catalogs/masterpages.

Below is the content of the master page gallery when the publishing feature has been enabled.

So, too easy then. Any web designer should be able to crank out their design app of choice, drop it into the master page gallery and shoot out a master page in minutes right? … Riiiiggghht?

Well…yes, they can, but there are two major issues that cause a lot of grief with branding, CORE.CSS and APPLICATION.MASTER. The next section describes this.

CORE.CSS

So a quick recap. When you create a SharePoint site collection, even if using the blank site template, a document library is created to store master pages. It is referred by the path of _catalogs/masterpage and is called the "master page gallery". The actual master page used, is a site based property set either via Sharepoint Designer (WSS3) or site administration (MOSS07). The master page almost always defaults to DEFAULT.MASTER (although site templates can actually specify another). DEFAULT.MASTER refers to a file called CORE.CSS. Thus, any web pages that use this template will always use CORE.CSS when processing styles.

Recap over: Now lets dig a bit more into CSS files in SharePoint!

The best way to understand how CSS is handled actually is to look at one of the sample master pages, for example blackglass.master that comes with the publishing feature. Since it significantly changes the look and feel of a site when applied, we know that CSS modifications have been made. If you go to the master page gallery of your publishing enabled site (http:///catalogs/masterpage), you will be able to download this master page and check out the source code in notepad or any other HTML designer. I have pasted the important bit below:

<head runat="server"> 
[snip] 
    <Sharepoint:CssLink runat="server" /> 
     
    <SharePoint:CssRegistration name="<% $SPUrl:~SiteCollection/Style Library/~language/Core Styles/Band.css%>" runat="server"/> 
    <SharePoint:CssRegistration name="<% $SPUrl:~sitecollection/Style Library/~language/Core Styles/controls.css %>" runat="server"/> 
    <SharePoint:CssRegistration name="<% $SPUrl:~SiteCollection/Style Library/zz1_black.css%>" runat="server"/> 
[snip] 
head>

Allow me to introduce you to two webcontrols. SharePoint:CssLink and SharePoint:CssRegistration

SharePoint:CssLink and SharePoint:CssRegistration

SharePoint:CssRegistration defines a CSS file – simple as that. If you look closely at the example however, you will notice that like the reference to a master page, there are tokens here that the system replaces at runtime. Let’s examine one further, looking at the source code and then what is rendered in the browser for an example site:

"<% $SPUrl:~SiteCollection/Style Library/~language/Core Styles/Band.css%>" runat="server"/>

Rendered as:

<link rel="stylesheet" type="text/css" href="/sites/nopub/Style%20Library/en-US/Core%20Styles/Band.css">

Sharepoint:CssLink is the control that actually renders the styles. So, for every style defined by a SharePoint:CssRegistration, SharePoint:CssLink will process all of the runtime tokens like ~language and render the CSS files. Let’s now look at the input again for blackband.master and the output

"server"> 
[snip] 
"server" / 
 
"<% $SPUrl:~SiteCollection/Style Library/~language/Core Styles/Band.css%>" runat="server"/> 
"<% $SPUrl:~sitecollection/Style Library/~language/Core Styles/controls.css %>" runat="server"/> 
"<% $SPUrl:~SiteCollection/Style Library/zz1_black.css%>" runat="server"/> 
[snip]

And the result is…

<head> 
[snip] 
<link rel="stylesheet" type="text/css" href="/sites/nopub/Style%20Library/en-US/Core%20Styles/Band.css"/> 
<link rel="stylesheet" type="text/css" href="/sites/nopub/Style%20Library/en-US/Core%20Styles/controls.css"/> 
<link rel="stylesheet" type="text/css" href="/sites/nopub/Style%20Library/zz1_black.css"/> 
<link rel="stylesheet" type="text/css" href="/_layouts/1033/styles/core.css?rev=5msmprmeONfN6lJ3wtbAlA%3D%3D"/> 
[snip] 
head>

What do you notice here? There were only 3 registered CSS files in the master page. However, 4 CSS files were rendered to the browser. CORE.CSS, you will notice, has been rendered, despite the fact that it is not explicitly defined. What’s more, (and this is the important bit), CORE.CSS is always listed last.

This behaviour is not always a problem, but in many circumstances it can be. Imagine that you have your own overridden styles for example, pimpmysharepoint.master, refers to a style called pimpmysharepoint.css. The source code would look like this.

"server" / 
 
"<% $SPUrl:~SiteCollection/Style Library/pimpmysharepoint.css%>" runat="server"/>

And the output is..

<head> 
[snip] 
<link rel="stylesheet" type="text/css" href="/sites/nopub/Style%20Library/pimpmysharepoint.css"/> 
<link rel="stylesheet" type="text/css" href="/_layouts/1033/styles/core.css?rev=5msmprmeONfN6lJ3wtbAlA%3D%3D"/> 
[snip] 
head>

So CORE.CSS (which is a rather large file with a LOT of styles in it), will override my custom styles.

Here is another quirk with SharePoint:CssRegistration. Not only does it render CORE.CSS last, but it renders the other styles in alphabetical order. So even if I changed the order of the SharePoint:CssRegistration entries in the source, they will always render in alphabetical order. (I assume this is why Microsoft chose to name a style as zz1_black.css to ensure it rendered second last).

For example, with the CssRegistration order changed in the source..

"server"> 
[snip] 
"server" / 
 
"<% $SPUrl:~SiteCollection/Style Library/zz1_black.css%>" runat="server"/> 
"<% $SPUrl:~sitecollection/Style Library/~language/Core Styles/controls.css %>" runat="server"/> 
"<% $SPUrl:~SiteCollection/Style Library/~language/Core Styles/Band.css%>" runat="server"/> 
[snip]

And the result is still rendered the same way..

<head> 
[snip] 
<link rel="stylesheet" type="text/css" href="/sites/nopub/Style%20Library/en-US/Core%20Styles/Band.css"/> 
<link rel="stylesheet" type="text/css" href="/sites/nopub/Style%20Library/en-US/Core%20Styles/controls.css"/> 
<link rel="stylesheet" type="text/css" href="/sites/nopub/Style%20Library/zz1_black.css"/> 
<link rel="stylesheet" type="text/css" href="/_layouts/1033/styles/core.css?rev=5msmprmeONfN6lJ3wtbAlA%3D%3D"/> 
[snip] 
head>

So, the gist of the issue here, is that you do not always necessarily want CORE.CSS to be rendered last.

The last thing to say here, is to credit Heather Solomon for actually sitting down and producing a CSS reference chart for CORE.CSS, so you can easily see just how much of the look and feel of SharePoint it controls. Often you will want to override some of the styles in CORE.CSS, but clearly, the SharePoint:CssLink webcontrol will not allow you to.

APPLICATION.MASTER

So far, we have talked about DEFAULT.MASTER, as well as the master pages that are installed by the "Office SharePoint Server Publishing Infrastructure" feature. They all reside in the document library called the master page gallery at /_catalogs/masterpage.

But guess what? There is another master page used in SharePoint sites and this one does not live in the master page gallery. Some of the pages use another master page called APPLICATION.MASTER. All affected pages are references by the _layout entry in the URL. Some of the more visible components of a SharePoint site that are affected includes:

View all site content
Version History or a document or list
Workflow settings of a document library
Recycle Bin
Search results

You will notice that if you try all of the above options, you will be referred to a URL that has a path of _layouts.

_layouts is a directory that is common to all sites and site collections of a SharePoint web application. This is because _layouts is an IIS virtual directory that points to a location on the server.

The physical location on the server that _layouts refers to is generally C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\12\template\layouts

Now you may have realized the issue with APPLICATION.MASTER. It will not have a reference to any custom CSS files. Let’s check the source code of APPLICATION.MASTER

[snip]

So, based on what we have learned about SharePoint:CssLink, we know that APPLICATION.MASTER is only ever going to render CORE.CSS. Therefore, any custom CSS files used in custom master pages will never be referenced for _layout pages that use APPLICATION.MASTER. This can easily be demonstrated. Below is a blank site collection with the publishing feature enabled. I have changed the master page to blackband.master in "Site Actions" -> "Site Settings".

But now when we click on the "documents" link, which is basically "view all site content" you will see we no longer have the blankband branding. Instead it looks like the default branding again.

You will also notice above, the telltale "_layout" reference in the URL which tells you that this page has been rendered from APPLICATION.MASTER.

So these two issues alone can be an annoyance, when you combine them, it can really be a pain in the butt. In Part 2 of this set of articles, we will examine the branding scenario that started me on this journey, and then examine various approaches to SharePoint branding, to work around these two issues.

Thanks for reading!

No Tags

A simple example of a SharePoint “feature”

admin — Mon, 08 Oct 2007 05:00:06 +0000

If you check my introductory post, I discussed the concept of SharePoint features in a real world scenario. In this post I actually show an example of features from end to end, to illustrate that scenario.

So, first to recap the scenario, slightly simplified from my other post: A webdesigner has a new CSS file that is the new corporate branding standard. They must package it up as a ‘feature’. A misunderstood sysadmin nazi installs the feature onto the SharePoint farm once only, then sends a mail to the 35 site collection owners advising them to activate the "branding feature" on their sites. Each site collection owner who does so has the identical configuration modified so it is all nice and consistent.

Now also before we start, this demo requires the "Office SharePoint Server Publishing Infrastructure" feature to be enabled. If this is not enabled, the "Style Library" document library that we rely on, will not exist.

Step 1: Create the Feature

Our web designer of course has a development box so they can’t kill production. On this box they navigate to the

C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\FEATURES

and create a new folder called CustomBranding

C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\FEATURES\CustomBranding

Inside this folder we place our CSS file (in this case, called CustomBrand.CSS) and we create a file called FEATURE.XML.

Now in real life, you will copy a FEATURE.XML from one of the many other features here and work off that. But in our case, we will just type it in. The contents of FEATURE.XML is this:

Description="This is a feature that adds a new sexy CSS"
Version="1.0.0.0″
Scope="Site"
xmlns="http://schemas.microsoft.com/sharepoint/">

So we have a element and inside that an element. The required parameters for the element are below (lifted straight from MSDN)

Attribute		Description
Description		Optional String. Returns a longer representation of what the Feature does.
Id		Required Text. Contains the globally unique identifier (GUID) for the Feature.
Scope		Required Text. Can contain one of the following values: Farm (farm), WebApplication (Web application), Site (site collection), Web (Web site).
Title		Optional Text. Returns the title of the Feature. Limited to 255 characters.
Version		Optional Text. Specifies a System.Version-compliant representation of the version of a Feature. This can be up to four numbers delimited by decimals that represent a version.

So the first thing to do is generate a GUID. You can do this a number of ways, but I typically use an online generator like the one here to do it.

My GUID from the online generator is: 01c34560-6561-11dc-8314-0800200c9a66. Feel free to use it for this example but you should substitute with your own.

Title and description parameters should be plainly obvious and version is optional, but whack it in anyway.

Scope is important, a feature can be activated at various points in the farm. "Site" means it is activated once per site collection. All sub-sites under this site collection can make use of the feature without having to activate it. This will become clear later.

Next we refer to an . This is a reference to another XML file that actually tells Sharepoint what to do (provisionedfiles.xml). In our case, it is going to tell SharePoint to upload the CustomBrand.CSS file to the site collection style library.

Let’s take a look.

http://schemas.microsoft.com/sharepoint/">

In this file, the top-level Elements element defines the elements comprising the Feature. In my previous post, I outlined a table of elements that can be used to install SharePoint features.

Content Types: Contains a definition of a SharePoint content type.
Content Type Binding: Actually applies a content type to a document library.
Control: Allows you to replace existing controls on the page, such as the search or navigation with your own custom control.
Custom Action: You can define custom actions such as add a new menu item in "Site Actions".
Feature/Site Template Association: This allows you to bind a feature to a site template so that the feature is included in new sites based on that template.
Field: Contains a field, or column definition that can be reused in multiple lists.
Hide Custom Action: Opposite to "Custom Action", where you want to hide menu items.
List Instance: Provisions a SharePoint site with a list which includes specific data.
List Template: A list definition or template, which defines a list that can be provisioned to a SharePoint site.
Module: Deploys files which are included when provisioning sites.
Receiver: Defines an event handler for a list, or document library
Workflow: Defines a workflow for a list, or document library.

So as you can see in the above XML file, we have used the MODULE element to install 1 single file. Let’s examine the and element in detail.

Module Attribute	Description
Name	Required Text. Contains the name of the file set.
RootWebOnly	Optional Boolean. TRUE if the files specified in the module are installed only in the top-level Web site of the site collection.
Url	Optional Text. Specifies the virtual path of the folder in which to place the files when a site is instantiated. If Path is not specified, the value of Url is used for the physical path. Use the Url attribute to provision a folder through the Feature.

File Attribute	Description
IgnoreIfAlreadyExists	Optional Boolean. TRUE to provision the view even if the file aready exists at the specified URL; otherwise, FALSE.
Type	Optional Text. Specifies that the file be cached in memory on the front-end Web server. Possible values include Ghostable and GhostableInLibrary. Both values specify that the file be cached, but GhostableInLibrary specifies that the file be cached as part of a list whose base type is Document Library.When changes are made, for example, to the home page through the UI, only the differences from the original page definition are stored in the database, while default.aspx is cached in memory along with the schema files. The HTML page that is displayed in the browser is constructed through the combined definition resulting from the original definition cached in memory and from changes stored in the database.

So, the module section is specifying where any elements be copied to. We are going to copy this to the document library called "Style Library" in the root web site for the site collection.

Step 2. Installing and testing the Feature

Now that our web developer has created the feature, they test it on their development SharePoint server. Open command prompt and execute the STSADM -installfeature command. When the -name parameter is specified, SharePoint knows to look in the TEMPLTE\FEATUIRES folder already, so you do not have to specify a full path.

Step 3. Test the feature

Okay, so the feature is installed. Now what? Now we need to activate this feature on a site collection. Here is the "Style Library" of my test site. (Remember that this library will not exist unless the SharePoint Publishing Infrastructure feature has been installed). Note that at this time, there is no CSS file called CUSTOMBRAND.CSS

So now let’s Activate the feature. Browse to Site Actions>Site Settings and from the Site Collection Administration menu, choose "Site Collection Features". Lo and behold! We have our feature listed! Note the title and description is as per our FEATURE.XML file.

Click "Activate" to activate the feature (you can also do this on the command line via STSADM -o activatefeature command). Once it is marked as active, re-examine the style library. Woo freakin hoo! There is our CSS file!

Step 5. Test and deploy the Feature

In our example here, we can test this feature, by choosing to use this new CSS file in the master page settings of any site within the site collection. The Site Collection administrator navigates to site settings->look and feel->master page settings and specifies the CSS file override as shown below.

By clicking on the "Browse" button, they can select the CSS file from the style library in the site collection.

This highlights the relationship between the web designer and the farm, site collection and site owners. In a large production farm the sequence would look something like this.

The developer creates and tests the feature
The developer hands the tested and approved feature to the the SharePoint farm administrator
The SharePoint farm administrator copies this feature into the FEATURES folder on the web front end servers on the farm and notifies the site collection administrators that the feature has been installed
Each site collection administrator activates the feature and informs the site owners that the feature is now available.
Each site owner optinally chooses to use this new CSS installed by the feature.

Summing Up

I hope that you found this article useful. Now you are going to totally hate me, because now I am going to tell you that features are only half of the solution to SharePoint customisation. "What is the other half"? you may ask. Well the other half of the solution is "solutions" … don’t you just love generic terminology!

No Tags