CleverWorkarounds » Features

SharePoint development/deployment governance…

admin — Tue, 27 May 2008 16:01:22 +0000

My home-town compatriot Jeremy Thake has hit onto a governance topic that I think will turn into a very popular series once he is done with it (in committing to writing it, he will be a busy boy indeed for a while I suspect ).

He has written a post on current methods and common issues of deployment of SharePoint customisations from dev to staging to prod, with particular reference to the current pain associated with iterative development and deployment.

The state of play in this area out in SharePoint land is not the best, due to a wide variety of factors and Jeremy sums it up very well.

Certainly, there are some extremely annoying architectural quirks. Back when I did the branding series I encountered some, but Jeremy has hit some nastier ones than what I found.

Anyway, take a look at his post – its a good read.

No Tags

Why do SharePoint Projects Fail – Part 6

admin — Sun, 11 May 2008 14:16:07 +0000

Hi again and welcome to part 6 of my series on the factors of why SharePoint projects fail. Joel Oleson’s write-up a while back gave me 5 minutes of fame, but like any contestant on Big Brother, I’ve had my time in the limelight, been voted out of the house (as in Joel’s front page) and I’m back to being an ordinary citizen again.

If you have followed events thus far, I covered off some wicked problem theory, before delving into the bigger ticket items that contribute to SharePoint project failure. In the last post, we pointed our virtual microscope at the infrastructure aspects that can cause a SharePoint problem to go off the rails.

Now we turn our magnifying glass onto application development issues and therefore application developers. Ah, what fun you can have with application developer stereotyping, eh! A strange breed indeed they are. As a group they have had a significant contribution to the bitter and twisted individual that I am today.

The CleverWorkarounds tequila shot rating is back!

for a project manager in denial

for the rest of us!

Leave us sensitive developers alone already!

Oh please.. I could make insultingly broad, sweeping generalisations about developers to make people laugh, but you guys hate each-other more than you do the rest of us! So any insult that I come up with will be water off a duck’s back and you will no doubt have a good come-back insult loaded up and ready to shoot me down

Case in point? Go and read this hilarious post by Mark Pilgrim – an oldie but a real goodie. Warning: there is profanity there. I’d dearly like to repeat it here because it’s pure gold, but I wear a suit now and I am supposed to sound all "impressive and wise". Got to keep up appearances

Mark’s post is mandatory reading for anyone following this series. Stop now and read! (It’s cool – I’ll wait for you).

** cue elevator music **

All done? Excellent. Let’s move on!

Mark is the sort of developer who would be worth his weight in gold. What is great about the above post is that it is actually an excellent example of the social complexity of projects and why it is so incredibly challenging to get a project team (stakeholders and user reference group included) to see a common version of the truth. Although Mark nails his fellow developers to the wall here, an equally witty project manager, information worker or senior executive could write the same sort of post for their discipline area.

In common with what I said during the infrastructure oriented post, a lot of application development issues are simply a manifestation of wicked problems that have not been recognised earlier. Although everything I have outlined in posts 1-4 is where you will find your root causes, in an organisation with a low maturity level the project team likely has been largely oblivious to the warning signs up until this point. Suddenly once we are cutting code, problems start to become apparent and it’s all those damn developers fault of course!

So once again, for the rest of this post we have to do a suspension of belief. In part 5 we went to Homer Simpson’s land of chocolate. So for this post, how about we can all pretend that we live in a world where teenyboppers do not exist and therefore people’s minds haven’t turned to jelly from being bombarded by crap music – so let’s blame Britney Spears for 99% of project failures.

In the world without Britney Spears

In this world, the stakeholders all agree with each-other. They have a tacit and deep understanding of the organisation’s vision, strategy and exactly how that strategy is to be executed. Therefore, they have clearly and unambiguously articulated this vision to the project team. This information in turn has been understood at all levels by the project team and after much investigation, soul searching and deep analysis, the entire team agrees completely that SharePoint is the perfect fit.

After reading all of the insightful information in the CleverworkArounds’ "Learn to speak to your CFO" series , a project management plan has been put together and agreed upon and signed off by all stakeholders. Scope, constraints and assumptions are reasonable and clear. A work breakdown structure has been developed and signed off with well developed budget and accurate, confident estimates.

What could possibly go wrong?

Thinking your developers are developers

Jeremy Thake wrote about "organisational responsibility" recently, and my new "homie" Joel made his feelings known when he wrote about the folly of "Thinking your developers are administrators". This needs to be analysed further however. I prefer to use the title "Thinking your developers are developers". The world is rife with what one would term "bad programming". The term is something of a misnomer though. I work with a great free WCM system called Joomla, and it has a devoted community of developers writing add-on modules for a dizzying array of options. Most are very well written, but some of these modules I have hacked away at the source and quite frankly they are pretty bad (and coming from a part time developer like me, that’s saying something).

Wishing your developers are admins?

That term "bad programming" is misleading and potentially unfair, because bad programming can contain tight, readable code that would satisfy industry standard conventions. In actual fact I’m not really all that fussed about the source code unless it’s *monumentally* stupid. Instead it is all about the thought process that went into the development. Here is a real world example from my past of what I mean.

A system developed by a former employer of mine relied extensively on DNS aliases, that our customers had to add into their DNS. So when our application looked for its "server", it queried DNS for that alias. I suggested that this was not a good idea, and we would be much better served via a registry setting that could override this, centrally controlled via group policy in Active Directory. The suggestion was met with general disinterest until some time later, we had an install at a site with several physical locations.There would be a server at each location, but the customer’s Active Directory set-up was a single DNS namespace. Thus we could only add a DNS alias for 1 server, yet we had several sites where servers resided. The system couldn’t handle the fact that a DNS can spread over multiple sites.

One quickly convened meeting later and suddenly the penny dropped on the logic of my suggestion. (But it took a real world emergency for that to happen). The next problem was the developers immediately chose the wrong location for registry key. Microsoft have a guide that tells you *where* in the registry to place your modification and they didn’t know there were recommendations and didn’t think to check for such a recommendation. Fortunately I caught that one in time and got it sorted.

That example highlights that "bad programming" was actually more like lack of awareness of important external considerations. I named the title of this section, "Wishing your developers are admins", more for the example that I cited than a statement of fact. Certainly, infrastructure administrators are very crap coders, (despite what they think of their efforts). But they do have a greater affinity for integration oriented governance issues than their pure development counterparts because of the nature of their role.

Sniggering infrastructure people who are feeling superior now should stop and take note. Experience has shown me time and time again that greater awareness about governance and integration rarely translates to actually running their environment to the ideals they espouse however .

Read my Choose Your Own Adventure post for a more offbeat and sarcastic take on that issue.

Planting wicked seeds..

In part 5, I had a section entitled "Infrastructure and Product Skills", and I suggested that a lack of product awareness and skills among infrastructure designers did not always manifest themselves into pain and suffering until later down the track. In the application development discipline, this is even more of a problem, and the remainder of this post focuses pretty much on this area, since if things do go down this road, it is simply going to end up being one of the root causes of the next, even more wicked problem to try and solve.

The impact of a bad design decision today can in particular have far reaching consequences into the future. Microsoft have this problem at a level that would blow your mind if you have been around long enough know your history (and your security . Remember than in 1973, what Rittel said of wicked problems: "There is no immediate and no ultimate test of a solution to a wicked problem", and by that he meant any solution, post implementation will generate "waves of consequences" that may yield utterly undesirable repercussions which outweigh the intended advantages.

The thoroughly depressing thing about that statement is the implication that a wicked problem can arise from the unexpected aftermath of a perfectly innocent "non wicked" problem!

So let’s see where SharePoint and the systems it relies upon makes life hard for developers and can blow out projects.

The obvious way is usually the dumb way

I am going to start by showing you some C# code. Non programmers, don’t be scared, it’s not too bad and in honour of Ms Spears I have kept the theme going. It is opening a SharePoint list programmatically, looking for anything with a title of "Oops I did it again" and if it matches that term, informs you that you must "Wash your mouth out!".

foreach (SPListItem item in list.Items)


{

if (item.Title == "Oops I did it again") {

console.Writeline("Wash your mouth out!");

}

}

{

font-size: small;

color: black;

font-family: consolas, “Courier New”, courier, monospace;

background-color: #ffffff;

/*white-space: pre;*/

}

.csharpcode pre { margin: 0em; }

.csharpcode .rem { color: #008000; }

.csharpcode .kwrd { color: #0000ff; }

.csharpcode .str { color: #006080; }

.csharpcode .op { color: #0000c0; }

.csharpcode .preproc { color: #cc6633; }

.csharpcode .asp { background-color: #ffff00; }

.csharpcode .html { color: #800000; }

.csharpcode .attr { color: #ff0000; }

.csharpcode .alt

{

background-color: #f4f4f4;

width: 100%;

margin: 0em;

}

.csharpcode .lnum { color: #606060; }

Easy enough – aren’t lists sooo easy to work with! Let’s just say you used this sort of logic in a web part that displays only list items that have "Oops" in the title. A few minutes later, you have coded and tested the web part, and it works a treat. Into the change control it goes, and into production it finds itself.

Fast forward 4 weeks and now the list has 400 items in it. Now a refresh of the page containing your web part is taking 10 seconds and getting worse. Naturally ‘the network’ must be the problem, right? Of course it’s not. In this example every list item is being enumerated and a comparison is made. This is well documented as the most inefficient way to query a list.

Putting on my old Cisco hat for a second, I am going to repeat an oft said mantra that people who know me will have heard many times over the years and what all self respecting Cisco nerds know. It’s not the %$^%$ network alright! It’s never been the network, it’s your $%%$ code!

You think the example above is made up? It’s not! On one SharePoint project where I was the information architect, a developer from a well respected Australian integrator did exactly what I described above, and proceeded to blame the infrastructure, the architecture, the network – basically anything that wasn’t their component. Of course, their development environment only had 10 items in the list and thus it seemed fine to them!

If you go back to my real-world example of the DNS/Registry issue, it was a design decision that was probably given half a thought at best, only to turn out to be a major constraint down the track. My SharePoint specific example above shows that for an inexperienced developer, even a "hello-world" style example is potentially a landmine just waiting for you to innocently step on. The issue is that, to the uninitiated, the SharePoint ecosystem has even more virtual land mines to avoid than being Lindsay Lohan’s publicist.

Simply put, if you do not have a broad depth of knowledge that can only come from time, pain and experience, you are inevitably going to get blown up time and time again. What’s that old saying? There are old SharePoint developers, and there are bold SharePoint developers, but there are never any old-bold SharePoint developers

If I listed all of the examples that I could think of, this post would get out of hand, so instead, Jeremy Thake sent me his diigo link that aggregates blog posts tagged with "SharePoint and performance". That should give you some idea of what developers are getting themselves into.

Junk DNA

John Kominetz wrote a great blog post that is highly relevent to this discussion. It has nothing to do with SharePoint in the slightest, yet if you substituted the word "Documentum" with "SharePoint" we would all be nodding our heads in collective agreement. It examines Documentum, a product that was already a mature player in the ECM space way before SharePoint had even made it to a little red box on a Redmond whiteboard.

Kominetz looks at Documentum’s heritage and describes it in terms akin to a living organism. He makes the observation that its "genome" has evolved over many years and carries with it plenty of junk DNA and "evolutionary dead ends". This is completely unavoidable, despite what any idealistic whinger about "bloatware" would like to believe. Another Joel (are all Joel’s in this world clever?), has a blog that is mandatory reading for anyone who is prone to making idealistic statements about security, bloat or complexity. I urge you to read his "Martian Headsets", "Architecture Astronaut" (where he picks on Groove ), as well as his "Things you should never do" posts. Joel is a wise man, indeed.

Quick history lesson for the uninitiated. SharePoint actually started as SharePoint Team Services (STS) and actually used the file system as the content store. (And I predict they will eventually go back to it too but that’s another story). Next Microsoft trotted out SharePoint Portal Server (SPS) where some bright spark thought that the Exchange "web storage system" (information store) would make a lovely document repository (probably because of the replication potential). Over the next couple of years there must have been a big ugly turf war between the Exchange storage team and the SQL team because, lo’ and behold, with SharePoint Portal Server 2003, SQL Server was now the document store. In this major architectural change, we actually lost some functionality. In addition to this, the 2003 version leveraged the recently released .NET Framework, and provided a richer object model and platform for SharePoint to sit on (although then it was not a completely cohesive fit).

Roll on 2007 and we have a slew of new technologies and features, too many to name. And just to make it more interesting, Microsoft decided to change terminology (again) as ASP.NET was leveraged much more heavily. Thus, "webs" and "areas" are gone. But their evolutionary signature remains. Whether it’s the SDK, the choose-your-own-adventure Technet documentation, blogs or even the STSADM command, it is very easy to spend a lot of time going down the completely wrong path in the quest for a solution to a problem because you get mired in junk DNA. Worse still, you get there, realise you solved the problem the ‘old’ way, say "stuff it" and deliver it as-is.

Web Parts are a great case in point. There are actually two types of web parts in the object model. The one that was introduced with SharePoint 2003 and the one that comes with ASP.NET 2.0 (which SharePoint 2007 uses). When I was writing my hide control web part, almost all the technet examples as well as blogs on the subject did not make it clear which type of web part and the distinction between them. It turned out of course I was using the right web part class, but following the wrong online documentation. A couple of XML irregularities had be scratching my head for hours.

Infrastructure, security and governance awareness (again)

I sort of covered this at a high level in the "Wishing your developers are admins" section and it’s been said before on many blogs that SharePoint blurs the lines between developer and administrator. Both sides have to shift ground (as do project managers and stakeholders too). Administrators really need to gain more development competencies and visa versa. I won’t spend too much time reinforcing what has already been said, but always remember this: Despite all the advances in Windows 200x, IIS, SQL Server, fancy multi-layered security, richer object model via ASP.NET Version x and the like, every developer has it in his/her power to render even a tightly managed SharePoint farm a train wreck. A lack of a simple null-check can render a site un-viewable. Choosing the wrong way to execute a query on content can chew excessive amounts of CPU and memory, an ill-thought design decision can cause a good idea to be lost in the frustration of the user experience. When it all comes down to it, it is the end user acceptance, adoption and evangelism that determines whether a project has been a success or failure.

But it goes beyond performance. What about security considerations? As developers, do you stop and ask yourself whether your chosen course of action has implications on security? What is your definition of security anyway? (Because it is just as much about smart, re-usable design as it is about using passwords with non alphanumeric characters in them – google "the CIA triad").

A major problem area I have seen that has manifested itself in project management time frames is the difference between the development and production environments. SharePoint development environments tend to have a short shelf-life due to the amount of crap you have to install, remove, reinstall, etc. Therefore, they are best served via a single Windows 2003 Virtual Machine with Office 2007, Visual Studio 2005, SharePoint Designer, Reporting Services, SQL Server and all of the other associated paraphernalia. Give each developer their own so they don’t kill each-other

Without question, it is exceedingly likely that the developer is an administrator of their VM, and those that have a low security acumen tend to hit problems when they migrate their solution to the test or production environment. SharePoint has that many service accounts, application pools, web applications, site permissions, GAC DLL’s, .Net Trust levels, web.configs, etc that it is very easy for something to break into the transition to production.

Remember, everything works when you run it all as the administrator! You will not get much sympathy from your bitter and twisted infrastructure architect if you complain about it.

Project managers and stakeholders need to also be held to account here, as developers routinely cut corners when faced with unrealistic deadlines based on poor assumptions. But don’t worry developers, I’ll nail their asses in part 7!

Solutions and Features

The next two topics have caused me real-world pain. I had an argument with a developer a while back who felt extremely inconvenienced by my audacity to mandate that their web parts, DLL’s and web.config modifications be packaged up as a solution that activates the functionality via a feature.

But to be fair to the developer, if they have a low governance acumen, their point of view is completely understandable. SharePoint application development governance takes time to learn and is often not accounted for in project planning phases. Tools like STSDEV have gone a long way to improving the situation, but at the end of the day, developers who hate all the additional governance overhead associated with SharePoint are buck-passing risk to a place where it is ill afforded.

Branding…

Don’t get me started! (I’m drinking a scotch as I write this so please forgive the vitriol )

I’ll come back to branding in part 7 of this series, because to be fair, the developers are beholden to stakeholders who obsess over the location of a pixel. In many SharePoint scenarios (not all) this is mis-focused because their success criteria is not how good it looks, but how much the organisation has gained in bottom line.

But from a developer’s perspective, this is another area where I see serious abuse. My entire branding series came from the experience of having to clean up after a "consultant" who decided he did not have to research into the techniques to customise SharePoint in a sustainable, governable way. He completely butchered the _layouts files with no backup or consideration to the implications of future service packs or updates and ignored built in features like the site collection style library. Instead he reinvented his own solution. As I mentioned in the previous section, I asked him to package his work up into a solution for ease of deployment and rollback and I was met with resistance and tension.

The whole concept of ‘CleverWorkarounds’, comes from the pragmatic acceptance that hacks are a part of life. You can’t avoid them, and sometimes you are forced to resort to them. But there is a huge difference between a workaround and a ‘clever workaround’. Most of the various hacks and workarounds that I describe in the more technically focused articles of this blog (like the JavaScript stuff) always come from the philosophical perspective of leaving a environment where the next administrator or developer doesn’t curse your name for eternity.

Miscellaneous considerations…

Jeez, branding got me riled up – I guess the scars are still fresh on that one!

No-one can know everything. Everyone has governance deficiencies in one way or another. I remember in 2003, a shattered project manager came into my office. A client meeting had gone very badly, blown up in his face in fact. He came to me and his classic line to me was "All I did was tell them to modify their Active Directory schema!". If you know Active Directory, you would know what sort of landmine he just stepped on. It’s like telling Mr T. that his "bling" really brings out his feminine side!

Thus, the branding hacks manifest themselves in other areas too. Pretty much any time you delve into the guts of the 12 Hive (tech guys and devs know what I’m referring to here), you have to be very mindful of governance, security and re-use. Ask yourself this question

Does the change I am making have any chance of being undone or unduly affected by a future patch or service pack?

Is the answer is yes, then stop and get some advice!

Developers in general get frustrated with their project managers. The PM’s nag, don’t have a deep enough understanding of the intricacies and nuances of application development and set unreasonable deadlines based on what you see as incomplete requirements and assumptions. However, as I have said in the second post, their world is just as frustrating as yours. Shared understanding this is the key to dealing with it.

So, if your project manager gets upset because their deadlines stretch because you feel some more research is required to determine the best course of action, tell them to read this series from start to finish (whenever it finishes). Chances are they will be squirming with embarrassment way before they have even gotten to this post.

At the end of the day, it is in both your collective interest to keep the stakeholders happy and ensure that the project is successful.

Conclusion

This post covered a lot of material, and I appreciate you sticking with me. Judging from the reaction from Joel’s endorsement of the series, it also seems to have tapped into a common vein of frustration felt by many IT professionals all around the world.

The next post will round off the "people" aspects with an examination of the stakeholder and project sponsor and senior management perspective. Like the developer and infrastructure post, the key is to recognise that their perspective of the world is just as valid as yours, and just as much as you see them misinformed and contributing to a wicked problem scenario, you need to accept the fact that you do not have the full picture either.

Having said that, they get paid way more than we do and therefore that makes them fair game for some serious nailing to the wall Roll on part 7!

No Tags

"Guru of governance?"

admin — Thu, 03 Apr 2008 14:44:49 +0000

My old mate from employers yonder, Mike Stringfellow is one of those developers who always liked to take a step back and think through the bigger picture implications of various design/coding decisions. It’s just a pity that at that particular company we worked at, he was in the minority. (Not helped by some unbelievably poor executive level management wacky views of reality).

So I became one of those bitter and twisted anal infrastructure guys who always seemed to default to "No", when asked a question. (Usually "no" was the right answer nonetheless). I was told by another colleague that some of the (web) developers were scared of me… but Mike at least understood why

He recently blogged the idea of using features to modify web.config file of a web application. After all, the SharePoint SDK offers the WebConfigModifications property (of the SPWebApplication) class. He suggested that as a governance nazi I might have issues with this idea. As it turns out I do, but only for you developers that have been slack-arsed and not done your homework!

My first question was "Does this apply to all web applications across the SharePoint farm?". Mike swore on his mother’s grave that it did (okay, in reality he said "yep"), so at least the modification is consistent (and consistency = less costly governance). So far so good…

So there is a big, big tick. (Programmers who wonder why I abuse them when they start a sentence with, "Just edit web.config…", should really go back to their true calling and instead ask pertinent questions like "do you want fries with that?"

So the next question is the squirmy one. Features are applied at 4 scope levels. Farm, Web Application, Site Collection or Site. So here is the spot test:

Which scope level do you think this feature should be applied at?

If you said "Site" or "Site Collection", go to the back of the class, you weenie! You are the sort of developer who made me bitter and twisted! The answer is of course, the Web Application scope!

Web.config is the configuration file for an ASP.NET web application. A web application can host one or more site collections. Do not assume that just because you are a site collection administrator, that you have administrative access to the web application hosting your site collection!

If you set the scope of this feature at the site collection level, you are basically allowing a site collection administrator to make a change that affects all other site collections in the web application. Uh – does the site collection administrator have access to other site collections? Probably not, so why the hell would you allow them to perform a task that impacts on site collections they have no access to? You don’t – it breaks the security model.

On your dev box, this will likely work fine, because your likely running everything as administrator anyway (double weenie!), but I suspect that in production it probably will break unless your IT guys have poorly configured your farm (triple weenies).

What a weenie filled world we live in…

Anyway, Ted Pattison is definitely not a weenie. He has blogged on this topic also and has shown in suitable detail, how to write a web application scoped feature (nice blog BTW Ted you’re definite blogroll material).

I’m going to lift one image from Ted’s blog, just to show you where web application features are enabled. You may have guessed already, that since we shouldn’t do this at a site collection administrator level, that it is done in SharePoint Central Administration by a user who has farm-level permissions or permissions for the target Web Application. (Best to stick with a farm administrator in general, I believe).

Below is the sample screen-shot from central admin, showing how you can pick a web application and then activate a feature for it.

So thanks Mike, I’ll leave all that XML serialisation stuff to you – as I only barely got my head around that in the JavaScript series. So long as it’s web application scope you can do what you like…

No Tags

More SharePoint Branding – Customisation using JavaScript – Part 6

admin — Wed, 12 Mar 2008 13:09:39 +0000

God help me, I’m up to part 6 of series about a technology I dislike and still going. For those of you that have just joined us, then you might want to go back to the very beginning of this series where I used JavaScript to improve the SharePoint user experience. Since then, I’ve been trying to pick a path through the thorny maze of what you could term, ‘sustainable customisation’.

By that, I mean something that hopefully will not cause you grief and heartache the next time a service pack is applied!

So no mood for jokes this time – I want to get this over with so let’s get straight to it and finish this thing!

So where are we at?

Part 1 looked at how we can use JavaScript to deal with the issue of hiding form elements from the user in lists and document libraries.
Part 2 examined some of the issues with the part 1 JavaScript hacks and wrapped it into a web part using the content editor web part.
Part 3 then examined the various issues of adding this new web part to certain SharePoint pages (NewForm.aspx, EditForm.aspx and DispForm.aspx). I also covered using SharePoint Audience targeting to make the hiding/unhiding of form elements personalised to particular groups of users.
Part 4 started to address a couple of remaining usability issues, and introduced ‘proper’ web-part development using Visual Studio and STSDEV. I created a project to perform the same functionality in part 3, but would not requiring the user to have any JavaScript knowledge or experience.
Part 5 then used STSDEV to create a solution package that allowed easy debugging, deployment and updating of the web part developed in part 4.

So what could we possibly have left to cover? Basically this article will revisit the web part code and make some functionality improvements and then I will cover off some remaining quirks/issues that you should be aware of.

[Quick Navigation: Part 1, Part 2, Part 3, Part 4, Part 5 and Part 6]

Code Enhancement 1 – Debug Breakpoint

One thing that can be annoying when using this web part is debugging. A small typo in the list of columns to hide and the functionality can break and be difficult to troubleshoot. I have two enhancements that improve this situation.

The first is very simple. If you add a line like this in your JavaScript code

debugger;

When script debugging is enabled on your browser, a number of 3rd party debug tools such as Microsoft Script Debugger, Microsoft Script Editor, Visual Studio.Net and Venkman will treat this as a breakpoint and allow you to step through the code and perform client side debugging. This is handy of course, so wouldn’t it be nice for the web part to have a property that enables a breakpoint?

The code for this is insanely easy. We define a boolean property in our web part that optionally outputs the line ‘debugger;’ just before the rest of our code runs. Using the XML Serialisation as described in Part 5, we can expose this property as a checkbox in the web part properties when used in SharePoint.

Below is a code sample of the property and its use.

private bool _breakpoint;

// Create a custom category in the property sheet.
[Category("Custom Properties")]
[Personalizable(PersonalizationScope.Shared)]
[WebDisplayName("Enable Breakpoint?")]
[WebDescription("Add's breakpoints to Javascript code for script debuggers")]
[WebBrowsable(true)]
[XmlElement(ElementName = "BreakPoint")]
public bool BreakPoint {
    get
    {
        return _breakpoint;
    }
    set
    {
        _breakpoint = value;
    }
 }

In the render method, where applicable, we then add this line

if (_breakpoint)
{
      output.WriteLine("   debugger;");
}

So after rebuilding and redeploying this project using STSDEV, the web part properties now reflect this new property.

Check the “Enable BreakPoint” box and click okay. If your browser has script debugging enabled (found in Internet Options/Advanced tab in IE), you will be prompted to launch a debugger then the breakpoint is executed. Below you can see both the IE property page that controls script debugging and the prompt to debug the page when Visual Studio is installed.

Choose a new Instance of Visual Studio and you will then be able to see and step through the JavaScript code as shown below

Code Enhancement 2 – Debug Log Window

Sometimes, you will not have the benefit of being able to use a JavaScript debugger and you need a simpler method to display debug information. How about we add a debug log window that can conditionally be invoked when it is enabled in the web part properties?

Fortunately for us, Bret Taylor has done the hard work for us with a complete JavaScript debug log function.

So in JavaScript code, we can for example, add a line like:

log("This is log message ");

So once again, we can set this as a boolean property. If the property is set to true, the webpart can write the JavaScript log function to the browser and then call that function at various places in the rest of our code.

Below is a code sample of the property and its use

private bool _DebugLogWindow;

[Category("Custom Properties")]
[DefaultValue(false)]
[Personalizable(PersonalizationScope.Shared)]
[WebDisplayName("Use Debug Log Window?")]
[WebDescription("Select to set value to True.")]
[WebBrowsable(true)]
[XmlElement(ElementName = "DebugLogWindow")]
// The accessor for this property.
public bool DebugLogWindow
{
    get
    {
        return _DebugLogWindow;
    }
    set
    {
        _DebugLogWindow = value;
    }
}

The next section of code outputs the log function itself. I know this looks ugly but thats what you get when using one programming language to write the code of another.

if (_DebugLogWindow)
{
    output.WriteLine(@"function log(message) {");
    output.WriteLine(@"if (!log.window_ || log.window_.closed) { ");
    output.WriteLine(@"   var win = window.open("""", null, ""width=400,height=200,"" + ");
    output.WriteLine(@"   ""scrollbars=yes,resizable=yes,status=no,"" + ");
    output.WriteLine(@"   ""location=no,menubar=no,toolbar=no""); ");
    output.WriteLine(@"   if (!win) return; ");
    output.WriteLine(@"        var doc = win.document; ");
    output.WriteLine(@"        doc.write(""Debug Log"" +");
    output.WriteLine(@"        """"); ");
    output.WriteLine(@"   doc.close(); ");
    output.WriteLine(@"   log.window_ = win; ");
    output.WriteLine(@"   }");
    output.WriteLine(@"   var logLine = log.window_.document.createElement(""div""); ");
    output.WriteLine(@"   logLine.appendChild(log.window_.document.createTextNode(message)); ");
    output.WriteLine(@"   log.window_.document.body.appendChild(logLine); ");
    output.WriteLine(@"}");
 }

So all we need now is to invoke this function in sections of code where debug output would be useful. For example:

if (_DebugLogWindow)
{
     output.WriteLine("    log(\"We have " + _fieldlist.Length + " fields to hide \" ); ");
}

So let’s rebuild and redeploy these changes and see the effect.

The screen grab below shows the result of enabling this setting. We now have a second browser window spawned that logs to the screen all information passed to the log() function.

Code Enhancement 3 – Hide Control by ID

I cannot take the credit for this enhancement. I originally packaged up an early version of the web part for Jeremy Thake, a former colleague of mine to test on his environment before I published part 5 of this series. He in return sent me back another JavaScript function to hide based on HTML element ID’s.

Way back in Part 1, I described the JavaScript built-in method getElementsByTagName. Jeremy is using the function getElementByID. This function works on the assumption that HTML elements are assigned an optional ID attribute. e.g

<div id="CleverWorkarounds1"
     style="position:absolute; width:500px; height:150px; visibility: visible">
some DIV tag
div>

If you look in SharePoint HTML source, you will see that this is the case.Take for example this particularly feral HTML element for the CLOSE button.

<input type="button" name="ctl00$m$g_100fd177_99ab_4755_a1d3_f064360d4317$ctl00$toolBarTbltop$RightRptControls$ctl02$ctl00$diidIOGoBack"
   value="Close"
   id="ctl00_m_g_100fd177_99ab_4755_a1d3_f064360d4317_ctl00_toolBarTbltop_RightRptControls_ctl02_ctl00_diidIOGoBack"
   class="ms-ButtonHeightWidth" target="_self"
 />

So this button can be referenced by the following ID.:

document.getElementById('ctl00_m_g_100fd177_99ab_4755_a1d3_f064360d4317_ctl00_toolBarTbltop_RightRptControls_ctl02_ctl00_diidIOGoBack').style.display="none";

Below is a code sample of the property and its use

private string _HideFieldByIdList;

// Create a custom category in the property sheet.
[Category("Custom Properties")]
[Personalizable(PersonalizationScope.Shared)]
[WebDisplayName("List of HTML element IDs to hide on this page")]
[WebDescription("Comma delimited list of HTML element IDs to hide on this page")]
[WebBrowsable(true)]
[XmlElement(ElementName = "HideFieldByIdList")]
public string HideFieldByIdList
{
    get
    {
        return _HideFieldByIdList;
    }
    set
    {
        _HideFieldByIdList = value;
    }
}

Next up, we have the function written by Jeremy (along with some debug log lines added by me)

if (HideFieldByIdList != null || HideFieldByIdList != "")
{
     if (_DebugLogWindow)
    {
        output.WriteLine("    log(\"Calling function hideFieldsById\" ); ");
    }
    output.WriteLine();
    output.WriteLine("function hideFieldsById() { ");
    _fieldlist = HideFieldByIdList.Split(',');
    if (_fieldlist != null)   {
        for (int i = 0; i < _fieldlist.Length; i++)
        {
            if (_fieldlist[i] != "")
            {
                if (_DebugLogWindow)
                {
                     output.WriteLine("    log(\"Looking for ID " + _fieldlist[i] + "\" ); ");
                }
                 output.WriteLine("document.getElementById('" + _fieldlist[i] + "').style.display=\"none\";");
             }
         }
    }
    output.WriteLine(" }");
    output.WriteLine();
}

So let’s test this! Redeploy the project and let’s hide the Close button on DispForm.aspx

Before screen-shot!

Add the ID of the “Close” button

After screen-shot! Wohoo!

Quirks and Issues

We are almost home after 6 posts in this series! No more coding for now as I think we have demonstrated enough of this idea. You can see how this can be used and extended quite easily.

There are a couple of minor points that I think are worth pointing out. One issue I covered back in my first branding series. If you deactivate this feature, the web part will not be removed from the web part library.

“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!”

So now that we know that the web part will not be deleted, let’s see what happens when we modify it. Here is the web part as it was installed by the STSDEV solution.

Now let’s do a flashback and modify WebPart.XML in our Visual Studio Project. I have modified the Title property to “CleverWorkArounds Hide Column1 Web Part”

xml version="1.0" encoding="utf-8"?>

<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
  <Module Name="CleverWorkAroundsHideFields" List="113" Url="_catalogs/wp" Path="WebParts" RootWebOnly="True">
    <File Url="CleverWorkAroundsHideFields.webpart" Type="GhostableInLibrary">
      <Property Name="Group" Value="CleverWorkArounds" />
      <Property Name="Description" Value="Web part to selectively hide columns via JavaScript"/>
      <Property Name="Title" Value="CleverWorkArounds Hide Column1 Web Part"/>
    File>
  Module>
Elements>

So let’s redeploy the solution, and even manually deactivate and reactivate the feature as well. When we re-examine the web part in the gallery, the change is not reflected.

Another inconsistency (although not a major one), is that the “Description” property is ignored completely. If you look at the Webpart.XML screen-shot above, you will notice I have set the Description property to “Property Name=”Description” Value=”Web part to selectively hide columns via JavaScript“.

But look at the web part properties above. The description is “A demo Web Part created by stsdev”.

I assume this is a bug with STSDEV, but in any event, its pretty minor and I can live with it.

Conclusion

Well gawddammit, I am finally done with JavaScript! But to round off this series, let’s summarise what we have achieved.

No programming skills necessary
No unghosting of Web Part pages
Easy debug logging
Leverage audience based content delivery
Eliminated the requirement for SharePoint Designer
Packaged up the functionality into an easy to deploy solution

I am well pleased, and I hope that you found some useful nuggets of information in this post.

I still hate JavaScript, but at least here we are using it in a sustainable customisation manner.

Bye for now

Paul

No Tags

More SharePoint Branding – Customisation using Javascript – Part 5

admin — Sun, 09 Mar 2008 11:24:01 +0000

Hello and welcome to part 5 of another epic CleverWorkArounds blog post.

If you think I write a lot on my blog, you should see my documentation and training material! I seem to be rare insofar as I actually like to write documentation and can churn out reasonable quality pretty fast. So if you need your scary SharePoint farm/infrastructure audited and fully documented, you know who to call!

Anyhow, here is the current state of play.

Part 1 of this series looked at how we can use JavaScript to deal with the common request of hiding form elements from the user in lists and document libraries. We looked at a Microsoft documented method, then a better, more flexible method.
Part 2 wrapped this JavaScript code into a web part which has been loaded into the SharePoint web part gallery.
Part 3 then examined the trials and tribulations of getting this new web part added to certain SharePoint pages (NewForm.aspx, EditForm.aspx and DispForm.aspx), and then with a few simple edits, use this web part to hide form fields as desired. Finally, I demonstrated the power of combining this with SharePoint Audiences targeting functionality to make the hiding/unhiding of form elements personalised to particular groups of users.
Part 4 introduced Visual Studio and STSDEV. I created a project to perform the same functionality in part 3, but not requiring any JavaScript knowledge or experience. By the end of part 4 I had a STSDEV project that compiled with no errors.

And now we are onto Part 5 where we turn our attention to the packaging and deployment of our web part. As you are about to see, STSDEV makes this a very quick and painless experience. If you aren’t convinced of the merits of STSDEV and the SharePoint solution framework by the time you finish this article, then I don’t know what will convince you.

[Quick Navigation: Part 1, Part 2, Part 3, Part 4 and Part 6]

So, for those of you that want to see the complete source code for an easy cut and paste into your own project, I have listed it below.

using System;
using System.Web;
using System.Web.UI;
using System.Web.UI.WebControls;
using System.Web.UI.WebControls.WebParts;         

using System.Xml.Serialization;
using System.ComponentModel;         

namespace CleverWorkAroundsHideFields {         

  [XmlRoot(Namespace = "CleverWorkAroundsHideFields")]
  public class CleverWorkAroundsHideFields : WebPart {         

      private string _HideFieldList;
      private string[] _fieldlist;         

      // Create a custom category in the property sheet.
      [Category("Custom Properties")]
      [Personalizable(PersonalizationScope.Shared)]
      [WebDisplayName("List of columns to hide on this page")]
      [WebDescription("Comma delimited list of columns to hide on this page")]
      [WebBrowsable(true)]
      [XmlElement(ElementName = "HideFieldList")]
      public string HideFieldList
      {
          get
          {
              return _HideFieldList;
          }
          set
          {
              _HideFieldList = value;
          }
      }         

      protected override void Render(HtmlTextWriter output)
      {         

          // Now lets extract the list of fields from the web part properties
          if (HideFieldList != null)
          {
              _fieldlist = HideFieldList.Split(',');         

              // javascript inside C# - ugh 
              // I know this looks ugly on account of the escaped quotes. 
              // First section is the findacontrol function         

              output.WriteLine();
              output.WriteLine(@"");
          } // if
      } // method         

   }
}

Now, let’s focus back on our STSDEV generated Visual Studio solution and make a couple of changes, to properly package up our code.

Edit 1: Feature.XML

You will find Feature.XML under RootFiles\TEMPLATE\Features\CleverWorkAroundsHideFields

In this example, I have modified the Title, Description and ImageUrl attributes of the element of Feature.xml to give more meaningful, friendly descriptive text. The default image has been renamed to macgyver.jpg and you will soon see why

<Feature
  Id="8C39BCDB-9361-4412-950C-5ADE30AFF14E"
  Title="CleverWorkArounds: JavaScript Hidden Column Manager"
  Description="This SharePoint solution can be used to hide columns from DispForm.apsx, EditFormaspx, NewForm.aspx as well as custom web part pages. (http://www.cleverworkarounds.com)"
  Version="1.0.0.0"
  Scope="Site"
  Hidden="false"
  ImageUrl="CleverWorkAroundsHideFields\macgyver.jpg" xmlns="http://schemas.microsoft.com/sharepoint/">
  <ElementManifests>
    <ElementManifest
      Location="WebParts.xml" />
    <ElementFile
      Location="WebParts\CleverWorkAroundsHideFields.webpart" />
      ElementManifests>
Feature>

Edit 2. Custom Icon Image

I decided that if I am going to create a SharePoint Feature with an icon, I’d have to use something that captures the very essence of the “clever workaround”. When you think about it, can it be anybody but MacGyver?

[if you see a broken image above then your IT staff are being anal and blocking YouTube - sorry]

Ahhh- the memories.. *ahem*, focus Paul – back to the post.

So, I have a small picture of MacGyver called oddly enough, MacGyver.jpg. I have placed this file into the RootFiles\TEMPLATE\IMAGES folder in my STSDEV project as shown below.

Now in Visual Studio, I have added this image to the project.

As you can see below, now macgyver.jpg is listed along with the default STSDEV image. You can delete the default image AfricanPith32.gif as we will not be needing it.

Edit 3. WebParts.XML

You will find WebParts.XML under RootFiles\TEMPLATE\Features\CleverWorkAroundsHideFields

In this example, I have modified the element of WebParts.XML, modified the property element named “Group”, as well as added in a Description and Title property also. This XML file uses the directive to put our web part into the web part gallery for any site collection where the feature is activated.

<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
  <Module Name="CleverWorkAroundsHideFields" List="113" Url="_catalogs/wp" Path="WebParts" RootWebOnly="True">
    <File Url="CleverWorkAroundsHideFields.webpart" Type="GhostableInLibrary">
      <Property Name="Group" Value="CleverWorkArounds" />
      <Property Name="Description" Value="Web part to selectively hide columns via JavaScript"/>
      <Property Name="Title" Value="CleverWorkArounds Hide Column Web Part"/>
    File>
  Module>
Elements>

Let’s build it!

Right! If you have made it this far, then let’s do a final build using “DebugBuild” configuration. If it all compiles, we are ready to test a deployment to our development server.

Now you will get to see why STSDEV is such a damn useful tool. In the drop down window shown below, choose “DebugDeploy” as the build option, and then press F6 or build the solution via the “Build” menu.

Below is the output of the build. Look closely at the annotated output below. The web part has been packaged up into a SharePoint solution, the solution has been added to the SharePoint solution store and then activated for all web applications. (look mum, no hands!)

—— Build started: Project: CleverWorkAroundsHideFields, Configuration: DebugDeploy Any CPU ——
c:\WINDOWS\Microsoft.NET\Framework\v2.0.50727\Csc.exe /noconfig /nowarn:1701,1702 /reference:”C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\12\ISAPI\Microsoft.SharePoint.dll” /reference:c:\WINDOWS\Microsoft.NET\Framework\v2.0.50727\System.dll /reference:c:\WINDOWS\Microsoft.NET\Framework\v2.0.50727\System.Web.dll /reference:c:\WINDOWS\Microsoft.NET\Framework\v2.0.50727\System.Xml.dll /keyfile:KeyFile.snk /out:obj\DebugDeploy\CleverWorkAroundsHideFields.dll

*** The above output is the command used by Visual Studio to compile the web part DLL.

Compile complete — 0 errors, 0 warnings
CleverWorkAroundsHideFields -> C:\VSPROJ\CleverWorkArounds\CleverWorkAroundsHideFields\bin\Debug\CleverWorkAroundsHideFields.dll
Refreshing Deployment Files…
“C:\Program Files\Common Files\stsdev.exe” /refresh CleverWorkAroundsHideFields C:\VSPROJ\CleverWorkArounds\CleverWorkAroundsHideFields\

*** STSDEV now runs and updates some of the other files in the solution required to deploy this web part (completely hands off for the developer which is great)

STSDEV – Simple Tools for SharePoint Developers
Refreshing Solution Package Files
Current Solution Name:
Current Solution Directory:
Refreshing deployment files…
Rebuilding DeploymentFiles\manifest.xml
Rebuilding DeploymentFiles\SolutionPackage.ddf
Deleting Solution Package File…
Building Solution Package (Debug Version)
“C:\Windows\System32\makecab.exe” /F DeploymentFiles\SolutionPackage.ddf /D CabinetNameTemplate=CleverWorkAroundsHideFields.wsp
Microsoft (R) Cabinet Maker – Version 5.2.3790.0
Copyright (c) Microsoft Corporation. All rights reserved..

Parsing directives
Parsing directives (DeploymentFiles\SolutionPackage.ddf: 1 lines)
20,812 bytes in 6 files
Executing directives
0.00% – manifest.xml (1 of 6)
0.00% – CleverWorkAroundsHideFields.dll (2 of 6)
0.00% – CleverWorkAroundsHideFields\feature.xml (3 of 6)
0.00% – CleverWorkAroundsHideFields\WebParts.xml (4 of 6)
0.00% – CleverWorkAroundsHideFields\WebParts\CleverWorkAroundsHideFields.webpart (5 of 6)
0.00% – IMAGES\CleverWorkAroundsHideFields\macgyver.jpg (6 of 6)
100.00% [flushing current folder]
Total files:              6
Bytes before:        20,812
Bytes after:          4,955
After/Before:            23.81% compression
Time:                     0.02 seconds ( 0 hr 0 min 0.02 sec)
Throughput:            1354.95 Kb/second

*** STSDEV now builds the web part and supporting files into a SharePoint solution (WSP) file called CleverWorkAroundsHideFields.wsp

Installing Solution…
“C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\bin\stsadm.exe” -o addsolution -filename DeploymentFiles\CleverWorkAroundsHideFields.wsp

Operation completed successfully.

*** Now we use the SharePoint Admin tool STSADM to add the solution file CleverWorkAroundsHideFields.wsp to the SharePoint solution store. This creates a SharePoint timer job to actually perform this task.

“C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\bin\stsadm.exe” -o execadmsvcjobs

Executing .
Operation completed successfully.

*** Now we have forced SharePoint to execute all outstanding timer jobs, thereby forcing the solution to be added to the store

Deploying Solution…
“C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\bin\stsadm.exe” -o deploysolution -name CleverWorkAroundsHideFields.wsp -immediate -allowgacdeployment -allcontenturls

Timer job successfully created.

“C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\bin\stsadm.exe” -o execadmsvcjobs

Executing .
Executing solution-deployment-cleverworkaroundshidefields.wsp-0.
The solution-deployment-cleverworkaroundshidefields.wsp-0 job completed successfully, but could not be properly cleaned up. This job may execute again on this server.
Operation completed successfully.

*** These last two steps activated the uploaded solution using STSADM and then once again, executed all outstanding timer jobs. Note that in our example here, the final timer jobs had an error.

Verifying Successful Deployment

We can verify what the above log is telling us by navigating to Solution Management in SharePoint Central Administration. So let’s take a look! As reported in this log, there was an error. Note the cleverworkaroundshidefields.wsp status in in an “Error State”

Error? Oh no! What to do?

So for some reason, we have had a deployment error. So let’s retract this solution from SharePoint and perform an IISReset.

This action can be performed within Visual Studio thanks the the STSDEV functionality. Change the build type to a “DebugRetract” and press F6 or perform a build via the “Build” menu.

This time the log is much simpler, because we are not actually compiling our code this time. Instead, we are running the STSADM commands to retract this problematic solution.

—— Build started: Project: CleverWorkAroundsHideFields, Configuration: DebugRetract
“C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\bin\stsadm.exe” -o retractsolution -name CleverWorkAroundsHideFields.wsp -immediate -allcontenturls

Timer job successfully created.

“C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\bin\stsadm.exe” -o execadmsvcjobs

Executing .
Executing solution-deployment-cleverworkaroundshidefields.wsp-0.
Operation completed successfully.

========== Build: 1 succeeded or up-to-date, 0 failed, 0 skipped ==========

So now I perform an IISReset, and then attempt to redeploy the solution again.

For the sake of readability, I have omitted most of the build log this time.

—— Build started: Project: CleverWorkAroundsHideFields, Configuration: DebugDeploy

[snip lots of log output]

Executing .
Executing solution-deployment-cleverworkaroundshidefields.wsp-0.
Operation completed successfully.

Done building project “CleverWorkAroundsHideFields.csproj”.
========== Build: 1 succeeded or up-to-date, 0 failed, 0 skipped ==========

This time we do not have any warning messages in the Visual Studio build log. So let’s confirm via SharePoint Central Admin.

Great! So now we have successfully deployed the solution, the site collection administrator for this web application can activate the feature

Governance Interlude

I think at this time it is very important to reinforce why packaging up code into solutions is such a mandatory governance requirement. In the above example, we had a problem with the deployment of the web part. It may have been an issue with the DLL in the GAC, changes made to web.config files for each web application, or a variety of other reasons. The point is, I was able to roll back to a known good state and start over!

I’ve said it before, but any developer who rolls their eyes at me when I tell them that their work has to be packaged up as a solution, obviously is not serious about governance.

Activating the Feature

So, now that our solution has been installed and deployed to each web application, we now have a site collection feature to activate. This feature will copy our web part into the Web Part Gallery for the site collection and thereby make it available for use.

So as a site collection owner, we navigate to “Site Actions” and “Modify All Site Settings”. Choose the option “Site Collection Features”, and you will see the results of our work in all its glory! Wahoo!

So don’t just sit there! Activate the sucker!

Testing the new web part

For this example, I am going to use the same demo site and list that I used in part 1 of this series.

The site is http://tidemo/tftp and the list to try this on is the IT Assets list. I have navigated to the IT Assets list, and opened the entry for the first item in the list (ABCRTR01)

Using the ToolPaneView hack described in Part 3, open DispForm.aspx in page-edit mode as shown below.

Click on the Main web part zone and add a new web part. You will see CleverWorkArounds as a web part group, listing our web part. (For reference, Feature.XML is the file where name and description information is set)

‘

Add our web part to the page and then click on “Modify Shared Web Part” to being up the properties screen. This is where we get to see if you did all the XML serialisation code from Part 4 properly!!

If you see the screen below, it has all worked a treat! You now have a custom web part property asking you to list the columns to hide. The below-right image shows this web part property filled in with the “Purchase Date” and “IP Address” columns listed.

Click OK and let’s see the result! Wohoo! Fields hidden!

Conclusion

So, after 5 long winded blog posts, what have we achieved? Going back over the goals they were:

Allow hidden fields based on identity/audience
Avoid use of SharePoint Designer
Avoid customisations to the form pages that unghosted the pages from the site definition
Avoid the need for site administrators/designers to have to dabble in javascript code
Packaged up the web part into an easily deployable/retractable solution

CleverWorkAround Rating: Awesome!

Phew! Are we done yet? It seems like I have been typing these JavaScript articles for a freakin eternity! Alas no, I’m *still* not done!

I have an additional enhancement to make to this web part, and I also want to alert to you a couple of issues I had with this whole process.

So a Part 6 is in the works, but for now, I think its time for a well deserved beer! Your shout?

regards

Paul

No Tags

More SharePoint Branding – Customisation using JavaScript – Part 4

admin — Sun, 09 Mar 2008 06:46:19 +0000

Hi there. As I write this post, the media are telling me that the stock market is stuffed, the US economy is going to the dogs and banks are writing down billions from sub-prime excess. I dare not check my online broker, road traffic this morning was abysmal, I was late, brought in the wrong laptop and left an important DVD at home.

Could it get any worse? Who knows, but it sounds like the sort of day to re-visit JavaScript and get frustrated with writing a web part for the first time.

So to recap on our journey thus far..

Part 1 of this series looked at how we can use JavaScript to deal with the common request of hiding form elements from the user in lists and document libraries. It looked at a Microsoft documented method, then a better, more flexible method.
Part 2 wrapped this JavaScript code into a web part which has been loaded into the SharePoint web part gallery.
Part 3 then examined the trials and tribulations of getting this new web part added to certain SharePoint pages (NewForm.aspx, EditForm.aspx and DispForm.aspx), and then with a few simple edits, use this web part to hide form fields as desired. Finally, I demonstrated the power of combining this with SharePoint Audiences targeting functionality to make the hiding/unhiding of form elements personalised to particular groups of users.

All in all a pretty clever workaround so far if I say so myself.

My original goals for this JavaScript was to find an effective, easily repeatable way to customise SharePoint form pages by hiding fields or form elements when we need to. Specifically:

Allow hidden fields based on identity/audience
Avoid use of SharePoint Designer
Avoid customisations to the form pages that unghosted the pages from the site definition

We achieved these goals in part three, but was I satisfied? No. The quest for more clever workarounds always goes on!

[Quick Navigation: Part 1, Part 2, Part 3, Part 5 and Part 6]

So the way I am going to structure this post is to pitch it to part-time or junior developers. If you are an experienced software engineer, this article is not going to trouble you.

Coffee rating:

Remaining Issues

One thing I was unhappy about with the web part in part three was that JavaScript still had to be edited when using the web part on a page. I wanted to take the programming completely out of the equation. Additionally, it was about time I got off my butt and learned to code a web part anyway. I’d previously blogged about the wonderful STSDEV, and decided I’d better put my money where my mouth and actually use it before I start mandating that others do.

So the first part of this post is examining STSDEV, and the joyous fun I had with my first ever web part with it, then I will get onto the first part of the coding.

The Web Part Requirements

So what are we planning to do here? Basically it is pretty simple. The JavaScript code that hides the columns from a page looks like this.

If you look closely at the above example, you will see that we have two lines that are repeated for every field we wish to hide.

control = findacontrol(“Device Type”);
control.parentNode.parentNode.style.display=“none”;

So, how about we make a web part that accepts a custom property that allows the user to list all of the fields to be hidden, and the web part can generate the complete JavaScript code for each of them to be hidden from view. This screen-shot shows the basic idea.

Note that we have listed three columns in the web part properties separated by a comma. Thus the page containing this web part would hide the existence of any of these columns.

Enter STSDEV (Take 1)

So first up, I grabbed STSDEV from its codeplex home. I installed it and ran the EXE to receive the initial screen.

On my first attempt, I created the solution in my default visual studio projects folder (C:\Documents and Settings\Paul\My Documents\Visual Studio 2005\Projects\CleverWorkarounds)

STSDEV happily accepted this and created my solution, which I opened with Visual Studio 2005 and accepted the obligatory warning as shown. But that’s cool – we trust those nice STSDEV guys!

I won’t spend too much time going into the solution created for the web part project because you can watch the videos that explain it much better anyway. But I will draw your attention to the fact that two sample web parts are included in the solution, CustomWebpart1.cs and CustomWebpart2.cs. We will rename and modify these later but first I need you to be aware of one ‘gotcha’ that I encountered.

In Visual Studio try and compile this project as it is. Make sure that the build type is set to DebugBuild and press F6 or choose “Build Solution” from the “Build” menu. Uh-oh, I got a runtime error with STSDEV… Bummer

This had me going for a while, because at first I had made changes to the solution before I attempted a build. So I spent some time thinking it was my changes that were the root of the issue. All it turned out to be was the spaces in the path to my project.

C:\Documents^ ^and^ ^Settings\Paul\My^ ^Documents\Visual^ ^Studio^ ^2005\Projects\CleverWorkarounds

Enter STSDEV (Take 2)

This time, I’ve created the project with the parent directory parameter being a path with no spaces…

C:\VSPROJ\CleverWorkarounds

Follow all the steps as per take 1 and try and compile the solution. Good – no nasty runtime burps this time.

Customising the Solution

So we have to now take this generic visual studio solution and make our changes. This consists of deleting stuff that we don’t need, renaming our class and updating references to the class name. Later we will customise the build/deploy process too. If you have experience with STSDEV or this seems too straightforward for me to blog about, then skip to the next section, otherwise read on for more detail of my specific example.

The first step is to customise our generic web part solution to our needs. We will delete CustomWebPart2.cs and rename CustomWebPart1.cs to CleverWorkaroundsHideFields.cs. When you perform the rename, you will ask if you want all project references to be renamed also. Makes sense doesn’t it?

This dialog box should not be interpreted as modifying any hardcoded references to the old file name of CustomWebPart1.cs. You will still have to do some search/replace work.

Additionally, there are two .webpart files that go with the two default class files and you have to rename/delete these as well. They can be found in the solution under RootFiles\TEMPLATE\FEATURES\CleverWorkAroundsHideFields\WebParts.

Delete CustomWebPart2.webpart and rename CustomWebpart1.webpart to CleverWorkAroundsHideFields.webpart.

Below is the result of both changes (.cs files and .webpart files)

Okay, so now this solution comes with xml files, solution files and all the other paraphernalia associated with getting a web part bundled up and installed to a farm. Now we have to delete all references to the deleted web part called CustomWebPart2 and update the references to CustomWebPart1 to CleverWorkAroundsHideFields.

Using the FIND/REPLACE tool, the entire project can be adjusted very quickly

The above operation takes care of the renaming of CustomWebPart1 in one single operation. But with CustomWebPart2 we are deleting references, so it takes a little finer surgery.

Here are the results of the *find* for CustomWebPart2.webpart

Find all "CustomWebpart2", Subfolders, Find Results 1, "Entire Solution"
DeploymentFiles\SolutionPackage.ddf(25):RootFiles\TEMPLATE\FEATURES\CleverWorkAroundsHideFields\WebParts\CustomWebPart2.webpart
RootFiles\TEMPLATE\FEATURES\CleverWorkAroundsHideFields\feature.xml(17):      Location="WebParts\CustomWebPart2.webpart" />
RootFiles\TEMPLATE\FEATURES\CleverWorkAroundsHideFields\WebParts.xml(8):    "CustomWebPart2.webpart" Type="GhostableInLibrary">
Matching lines: 3    Matching files: 3    Total files searched: 9

You will find references to CustomWebPart2 in

SolutionPackage.ddf under DeploymentFiles
feature.xml under RootFiles\TEMPLATE\FEATUTES\CleverWorkAroundsHideFields
WebParts.xml under RootFiles\TEMPLATE\FEATUTES\CleverWorkAroundsHideFields

Using visual studio, open up each of these files and adjust the references. So for example in SolutionPackage.ddf I changed from:

;*** add files for CleverWorkAroundsHideFields\WebParts feature
.Set DestinationDir=CleverWorkAroundsHideFields\WebParts
RootFiles\TEMPLATE\FEATURES\CleverWorkAroundsHideFields\WebParts\CleverWorkAroundsHideFields.webpart
RootFiles\TEMPLATE\FEATURES\CleverWorkAroundsHideFields\WebParts\CustomWebPart2.webpart

Now if you are thinking to yourself, what is FEATURE.XML and Solutionpackage.DDF anyway? Then I am afraid that you have some homework to do! If you are going to code anything for SharePoint, you need to understand the concepts of features and how they are used with the solution framework. Seriously, if you are blindly editing the files using this post as a guide, then you are only going to get yourself into trouble later.

For the rest of you, finish off the renames and removals of the default class names and then try and rebuild the solution. If it all builds, you can move onto the next step of actual coding the thing.Once we finish coding, you will see pretty quickly how useful and time saving STSDEV really is.

Coding the Web Part – Part 1

So, now we open up CleverWorkAroundsHideFields.cs and add our code. The first step is to add references to additional libraries that this web part will use.

using System.ComponentModel;
using System.Xml.Serialization;

What are these and what do they do? Without going into loving detail, these namespaces allow you to use XML serialisation. I had not previously coded much ASP.NET stuff, so XML serialisation took me a little getting used to. But the basic idea is this.

XML Serialisation Interlude

If you have an object instantiated from a class, with a bunch of properties set to different values, how to you send those properties to another remote object of the same class? What if it is two separate web server or web applications?

XML serialisation allows you to set properties for the object that are then stored behind the scenes as XML (this is the serialisation part). The other end gets the XML (over HTTP) and deserialises it back to the native properties for the destination object. Lo and behold, we have copied the state of one object to another object.

Now think of the code that this saves when the other end simply has to call a deserialise method and all of the properties of the object are auto-magically filled in.

Now in SharePoint, web part properties have to be persisted. When you visit a page, the look and feel of the web part is determined partly by web part properties set by the site designer. Those settings are retrieved from the SharePoint database. So when those properties are first set by the administrator (i.e change the title or appearance of a web part), SharePoint serialises all of those properties to XML and that XML is stored into the database. When the page is then later loaded by a user, a web part object is created, and then the XML properties are deserialised back to the object properties so it can appear how it is supposed to.

Make sense? I hope so because that’s all I’m saying about it! If you are still cofused, try this article.

Coding the Web Part – Part 2

So having added the two references to the XML Serialaisation and System.ComponentModel namespace, you should have the following code.

using System;
using System.Web;
using System.Web.UI;
using System.Web.UI.WebControls;
using System.Web.UI.WebControls.WebParts;
using System.Xml.Serialization;
using System.ComponentModel;

Make sure that there is no reference to a namespace called Microsoft.SharePoint.WebPartPages. There are actually two different web part classes available, one designed for SharePoint 2003 and the more recent one being part of ASP.NET version 2. (System.Web.UI.WebControls.Webparts).

MSDN and Microsoft code samples have a lot to answer for here! Most code samples for web parts with custom properties are based on the legacy web part class, and things have changed between old and new, especially when it comes to XML serialised properties. I wasted a lot of time here because of this!

The next step is to delete the default code in the web part class. Find the following code and delete it.

protected override void CreateChildControls() {
  Label lblHello = new Label();
  lblHello.Text = "Hello";
  Controls.Add(lblHello);
}

Serialsed XML parameters are in square brackets around sections of c# code. These are .NET attributes and tell the XML serializer where the various members of this object will appear in the XML and what they will be named. Without these, serialization cannot take place.

So the first serialised parameter is defined in between the namespace and the class itself.

namespace CleverWorkAroundsHideFields {
   [XmlRoot(Namespace = "CleverWorkAroundsHideFields")]
   public class CleverWorkAroundsHideFields : WebPart {
   }
}

Now if we serialised the code into XML now it would look like this

<CleverWorkAroundsHideFields>
CleverWorkAroundsHideFields>

Exciting eh? So let’s now add some web part properties and serialise them as well. First up the properties of this class. If you check the section of this post titled “Web part Requirements”, I stated that the web part should accept a custom property that allows the user to list all of the fields to be hidden. So below is the property that will store this list of fields. It is about as simple as a class property can be (just store a string with a get and set method).

private string _HideFieldList; 

public string HideFieldList
{
   get
   {
      return _HideFieldList;
   }
   set
   {
      _HideFieldList = value;
   }
}

Now I need to add the parameters for XML serialsation. The above raw C# code above now changes to:

public class CleverWorkAroundsHideFields : WebPart { 

   private string _HideFieldList; 

   // Create a custom category in the property sheet.
   [Category("Custom Properties")]
   [Personalizable(PersonalizationScope.Shared)]
   [WebDisplayName("List of columns to hide on this page")]
   [WebDescription("Comma delimited list of columns to hide on this page")]
   [WebBrowsable(true)]
   [XmlElement(ElementName = "HideFieldList")] 

   public string HideFieldList
   {
      get
      {
         return _HideFieldList;
      }
      set
      {
         _HideFieldList = value;
      }
   }
}

I haven’t serialised this into XML, but you can see how all of the properties in square brackets would form an XML document describing the properties. if I did, it would look something akin to:

<CleverWorkAroundsHideFields>
<Category>Custom PropertiesCategory>
<WebDisplayName>List of columns to hide on this pageWebDisplayName>
<WebDescription>Comma delimited list of columns to hide on this pageWebDescription>
<WebBrowsable>TrueWebBrowsable>
<XmlElement ElementName="HideFieldList">
CleverWorkAroundsHideFields>

So now SharePoint has this in its database. When this webpart is rendered, the XML similar to above is retrieved and deserialised back to our WebPart class.

At this point it is a good idea to build the solution to ensure that you have no syntax errors or namespace issues. If you have trouble getting to this point, its best you not go any further until the project builds correctly.

Now where did I get these XML parameter values from? Go to the MSDN documentation for the System.Web.UI.WebControls.WebParts namespace and you will find all of the available properties buried there. (Either that or cheat like me and find out via here)

Coding the Web Part – Part 3

So now let’s write the code to render the JavaScript output. This is basically C# code to create the JavaScript that will render in the browser. The code is simple enough, we have looked at it in the last posts. But creating the JavaScript inside C# code makes it look worse than it really is.

First up, we need a new array variable called _fieldlist to store the individual fields (remember they come as a comma delimited list so we will split them to their individual names).

private string[] _fieldlist;

protected override void Render(HtmlTextWriter output)
{   // Now lets extract the list of fields from the web part properties
   if (HideFieldList != null)
   {
      _fieldlist = HideFieldList.Split(',');
      // javascript inside C# - ugh    
      // I know this looks ugly on account of the escaped quotes.    
      // First section is the findacontrol function
      output.WriteLine();
      output.WriteLine(@"");
   } // if
} // method

The only section of code above that is of real interest is in the JavaScript hideFields() function. Here we loop for each field supplied in the list, and construct the code. So for example, if HideFieldList contained “Column A,Column B”, the generated JavaScript code would be:

control = findacontrol("Column A");
control.parentNode.parentNode.style.display="none"
control = findacontrol("Column B");
control.parentNode.parentNode.style.display="none"

Please be careful cutting and pasting this code! Quotes seem to get screwed up sometimes.

Conclusion (let’s have a break)

Once again, this post is starting to get a little long. So I’ll stop now and let you have a breather. In part 5 of this series, we will do an initial build of this solution, which will demonstrate how useful STSDEV is at speedy packaging and deployment. I’ll show you how to package up a nice, re-usable solution, and be able to test and debug quickly and painlessly.

Until then, bye for now

Paul

No Tags

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

Finally – clever filtered lookups!

admin — Mon, 05 Nov 2007 22:24:24 +0000

Pretty much since I started with MOSS2007 (and back in the pre 2007 days too), I’ve required smarter drop down choices for my columns. Basically, I needed a secondary drop down list filtered based on the choice from a primary drop down list – the whole category/sub category thing. Seems amazing to me that it is not available out of the box.

On my to-do list was to write a detailed post critiquing all the workarounds out there (such as Patrick’s Javascript method and Dattard’s designer work) and rate their cleverness – as per the branding series.

But why bother now? Fellow aussies and clever guys at DataCogs Infomation Technology have provided the best workaround yet via two well coded custom field controls , all packaged up into a solution – too damn easy!

http://datacogs.com/datablogs/archive/2007/08/26/641.aspx

This for me is the mother of all clever workarounds. It is a snap to install and activate and source code is provided. What’s more, the primary/secondary lists can be on different sites. How good is that!

So, thanks, fellas, you have saved me writing a long blog post

CleverWorkarounds Rating: Pure Genius

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.

and

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