Wednesday, August 21, 2013

The page template mistake

How to recognise it and how to avoid it

This blog post is part 2 in a series on “Creating good Sitecore solutions”. You will find part 1; “How do I create a good Sitecore solution?” here.

Getting more, for less. Or even for free.

Having decided to create a good Sitecore solution, or even just “a Sitecore solution”, there is one thing you need to get right that adds more “good Sitecore value” to your solution above all other things you could be doing.

And the best thing about it is; it will (should) not add any costs to your implementation. If the practices lined out here are followed from the start, my own personal experience has shown me that your implementation time is not increased. In fact I would argue, following these guidelines will bring your overall implementation time down more than anything. And from whichever side of the table you are on – buying or selling a Sitecore solution – time will be money.

I will explain this in more detail, as I go along.

The problem with (most) Sitecore implementations.

In my first post in this series, I hinted that a very large majority of Sitecore solutions I come across in may day to day work were, to some extent, not entirely “fit for duty”. While some of the shortcomings can be put down to just this – the solutions were never truly designed to be good Sitecore solutions to begin with; the decision to to so was just plain never made. Most of them have a very fundamental architectural shortcoming in common. And this particular shortcoming – more than anything else – will nothing short of completely rule out pretty much any DMS scenario you can think of. Right then and there – one glitch, if you will, in the way these solutions were architected – and you can forget about the (in my view) most important set of features in Sitecore or possibly any CMS platform on the market today.

Before I go on, and step up high and mighty on my soapbox – let me be the first to admit this. Up until just a few years ago, I was happily designing and implementing Sitecore solutions following these same – faulty, as this post should demonstrate – practices and guidelines.

It wasn’t until around the beginning of 2012 and having just gone through a greenfield Sitecore 6.5 implementation that it dawned on me; the way I was perceiving and approaching basic Sitecore information architecture was just – well plain wrong. I recall asking on LinkedIn “Have you built a site yet, truly "true" to the changes in the 6.5 platform?” (Sitecore MVP group, for those who have access) – asking if anyone else had revisited the way they implemented Sitecore solutions following the release of Sitecore 6.5. It created a bit of debate, but nothing too ground shaking.

I was under the mistaken impression at the time, that it was Sitecore 6.5 and DMS that brought on these changes. Having mulled over this ever since, I now know that I was wrong. I know now that the way one is supposed to be implementing and architecting Sitecore for the solutions to end up “DMS ready” and being well on the way to becoming a “good Sitecore solution” dates back at least as far as Sitecore version 5. It might even be sooner, but I have little to no experience with Sitecore versions pre-dating version 5.

If you are still with me here, I think it’s about time I unveil what I believe to be at the core of the problem, in the way I was designing Sitecore solutions – and the problem in the vast majority of less than ideal Sitecore solutions I come across today.

The problem is: “Page Templates”

Yes indeed. Bear with me, and allow me to explain.

Having worked my way through I don’t know how many Sitecore releases dating as “far” back as Sitecore (the earliest I have on record) and all the way up through to version 7 – it wasn’t until Sitecore 6.5 that Sitecore brought on a truly serious alternative offering to the ever popular “Sitecore Content Editor”. In fact the Sitecore Content Editor is so widely used that most people probably don’t even realise, this is just one content editor interface in Sitecore. To most I would bet; this editor IS “Sitecore”.

A quick re-cap. Sitecore 5 and version 6s prior to 6.5 did offer alternative interfaces. As far as I can tell however, nobody really used them. I practically never came across any implementations were these played any active role. You had to implement for these alternatives specifically (sc:Dot anyone?) and in my personal view they just plain didn’t work very well. In essence you had to do a fair amount of extra (key word here) development effort to support anything but the Sitecore Content Editor. And as I’ve already argued – time equals money – so it doesn’t get done. Only in the rarest of circumstances.

Along came 6.4 and in particular 6.5 – and changed all that. For the first time – at least for me – could one switch to this “new” Sitecore user interface (which is, in fact, not new at all) and see the site one was building become truly interactive. Without doing much if anything at all, to support it. Alright so there is a few things to consider, but I consider these insignificant in the grand scheme of things.

All of a sudden, teaching clients to do their work in the Page Editor became a viable option. And in many (most) cases a very strong alternative to the Sitecore Content Editor. I mean the Sitecore Content Editor is fine, if you’re working on Page Templates – marketing people will get that, and manage fine to go in and alter some headlines, swap out a few pictures and even add a few new pages (based on Page Templates) to the site. Not much more than that however, not in my experience.

The Page Editor, however, allows so much more than that. Following just the standard Sitecore implementation guidelines – the Page Editor allows the content editor to work with the very fabric of the page. Swapping out components, personalising components, M/V testing them with alternating content. And while all of these possibilities are also present in the Sitecore Content Editor, the Page Editor beats it by miles in terms of overall user experience for the average non-developer user.

And here’s the thing. Swapping out components, M/V testing components on a page, personalising components on a page. None of this – none of it – fits into the mindset of a “Page Template”. Your page has become a dynamic entity, something to be shaped and molded into nothing short of the “Perfect personalised user experience for your site visitors” – this is the way of the Digital Marketing Future. We’re going to the Moon and all that ;-)

The fact of the matter is; if you perceive each page on your site as something that fits the static nature of a Sitecore template – keep in mind, these can only be created by developers, and once a template has been set for an item it stays with the item forever. Or at least until you forcibly decide to change it. Also keep in mind, a template for “Page A” will also be the same template for any other pages of the same type as “Page A”. You can’t have the template holding X fields here, and Y fields there. Sitecore just isn’t designed for that (yet, I hope).

To overcome this, Sitecore uses Datasources. I think this was recently dubbed “Related Content” in a recent Sitecore release, but I’m going hardline and stick with the original term. “Feeding” your component with a Datasource is the way you instruct it to “go get your content from this place over here, don’t look at the page you happen to be sitting on”. None of this means anything to the Page Editor – it just shows (and allows edits of) the content from where ever it was sourced – whereas you need to jump around between items in the Sitecore Content Editor to achieve the same (reference: section 4.2.1 of the Content Authors Reference and Cookbook for Sitecore 6.6).

For both personalisation and M/V testing to work – your components must be able to be datasourced. No if’s, no buts'.

And this is it. This just doesn’t happen (much) in most solutions I visit. I, as most of the Sitecore developer community, implement the general term component as an ASP.NET User Control or the up-and-coming MVC alternatives. Sitecore also supports other types of components, most notably the “XSL Rendering” type of component. For a variety of reasons, this component type is being ruled out everywhere – performance reasons, lack of familiarity with the XSLT syntax among the developer base – the reasons are many. Rightfully so, I might add. It’s a relic from a time where Sitecore seemed to be designed on the idea, that the Sitecore data structure should be represented in abstract as one big XML Document – and transformed for multiple purposes by the up and coming XSLT technology. While Sitecore still supports this notion, the product is moving more and more away from this line of thinking.

So. When writing components in ones language of choice – I guess c# is the dominant choice these days, and working with a user base that exclusively accesses Sitecore through one common interface – the Sitecore Content Editor – you set yourself up for The Page Template Mistake.

The Page Template Mistake

While going through all the motions of setting up Page Insert options for your users, you would probably also be considering what fields to present to your users on each of these “pages” they can insert. If you’re doing this well, you will break down your Data Templates into smaller bits, so as to make them easily available for re-use across different Page Templates. So you’ll isolate your “Page Header” and “Sub Heading” fields into one Data Template – and then have some or most of your Page Templates inherit from this one, as well as any other Data Templates that the particular Page Type will support.

As the site evolves you shape and mold your Data Template structure, to make the best use possible of the common fields across pages.

You’ll begin to implement components – like a common “Left Menu” component for example – and have these traverse through your Page Items based on Page Templates – outputting a nice and nested logical representation of your site. The site visitor clicks elements on the menu, and navigates to a new page. The story repeats itself.

Eventually you’re done. The site launches, editors make the last minute changes to headers, round off corners of the images and changes a few icons to the Cornflower Blue. Everyone is happy.

Everyone is happy, that is, until 3 days into the launch and your pesky content editors decides to try out some of this “fancy M/V testing that we’ve heard so much about”.

You’ve just made The Page Template Mistake. Don’t worry though matey, so have I and so have we all.

You will find, that once the content editors start moving stuff around, adding YouTube Video Player Component onto the “Contact Us” page – you’re in trouble. Sure you can go; “oh we’re sorry. We didn’t make it so that this component can work on that page” but really all you’re doing at this stage is making up excuses and adding a healthy dose of CYA. I know I did.

If all your considerations when designing your page and template structure was focused around the Sitecore Content Editor (and it is an EASY trap to fall into – you DO do all of the designing and “architecting” in this very editor) – chances are slim to none that you have all the dynamics in place to allow the kind of flexibility the Page Editor truly inspires.

M/V testing?  “Uhm sure…” (muttered on the phone while desperately scrambling to add a few template Insert Options to the solution and hoping it will work).

Ever been there?

Fortunately there’s an easy way to avoid it. Not an easy fix, mind you, refactoring your solution AFTER the fact is going to be a fairly extensive job. Avoiding this problem however, adds no cost to your solution implementation AND puts you on the road to delivering a “good Sitecore solution”.

The Data Template solution

If you look closely in the Sitecore documentation, you will find the term Data Template everywhere when speaking of content and data structures. In fact I don’t recall anywhere within official Sitecore documentation seeing the term “Page Template” mentioned. I could be wrong though, there is a vast amount of cookbooks dealing with these topics. Here’s a tip:

Don’t think Data Template, think “Component Template”.

Because that’s what you should be doing.

When going through the site designs, part of that process is identifying “Components” that has to be built for the site to be completed. You do this already – regardless of whether you’re thinking in terms of Page Templates or not. Each of these components will have a certain number of Sitecore fields supporting them. It will be the obvious ones; “Image Heading”, “Image”, “Subtitle”, “Citation” and so on – we all know how these look and work. There will (should) also be the more subtle ones like “Banner Rotation Delay”, “Allow Fullscreen” and so on. You won’t necessarily recognise all of these at the get-go, but don’t worry. These can be added as you go along with the implementation. Make sure you do, though. Things like “Banner Rotation Delay” are perfect candidates for M/V testing. Try it, you’ll probably be as surprised as I was about the difference it can make.

This is what should be defining your Component Template. A Component Template for a Component – this makes perfect sense. Name them by convention; a “YouTube Video Template” matching the “YouTube Video” component. This makes sense. To you and to your content editors alike. While configuring each component in Sitecore, make sure you configure the components Datasource Template to point to your corresponding Component Template – and you’re already more than half way on your pursuit of the “good Sitecore solution”.

Forget about Page Templates at this stage. You can do them at the end. At the very end of the project, I’m serious. Keep working your way through components and if you’re fortunate enough, get your team of developers started on implementing them right away. If not, start doing them yourself. Just make sure that the implementation of these components follow one of the most basic of rules:

Make sure the component respects it’s data source.

Mine didn’t. Not until that epiphany I had with Sitecore 6.5. As so many others, I implement my components as a Sitecore “Sublayout” (essentially an ASP.NET User Control) – and I would frequently sport code such as the following (not literally – the example code is ghastly, but am making a different point):

if ( Sitecore.Context.Item[“show in menu”] == “1” )
    litMenu.Text += “<li>” + Sitecore.Context.Item[“menu title”] + “</li>

Right up there on The Page Template Mistake, page 1, subheading “Sitecore.Context.Item”. Don’t use it. Well don’t use it in general, there are obviously cases where it is perfectly acceptable to go visit Sitecore.Context.Item.

What you need is something to the effect of (pseudocode, this post is already long enough without me diving in to a long technical explanation. I will do a follow-up post with concrete code examples to follow this one, I promise):

IF this_component HAS DEFINED Datasource
    SET $ActionItem TO Datasource
    SET $ActionItem TO Sitecore.Context.Item

And then have all the component implementation respect draw its data exclusively from $ActionItem.

That’s all there is to it. Really. And since you’re ignoring Page Templates for now, testing and verification of the implemented components becomes very easy. Developers will be forced to add their components to “blank canvasses” as they go along and Datasource them to their items based on the respective Component Templates.

This is not new. This is not something “clever” I am making up, or a “clever idea I just had”. No my faithful reader – this principle sits at the very foundation of Sitecore presentation architecture. This behaviour has been expected from the very beginning (of Sitecore 5, maybe sooner) from every Component.

This is $sc_item versus $sc_contentitem in your (no longer used) XSLT renderings; one of the first types of components you could implement in Sitecore. Also known as a “Rendering” – a term still being broadly used today to cover most anything used to output content. I prefer the Page Editor term Component.

$sc_item would behave exactly like the pseudocode above.

A rendering can retrieve data from its data source item. The $sc_item variable represents the data source item for an XSL rendering. If the developer does not specify a data source item for a rendering, the default data source item is the context item, and $sc_item and $sc_currentitem are the same item. – Presentation Component XSL Reference section 3.2.1.

And while I have found little to no documentation in Sitecore actually specifically instructing you to be designing Component Templates in the manner I describe, I can tell you this much: If you want to support all the DMS goodness that everyone is talking about these days – this is the first step.

Forget about Page Templates; think Component Templates.

Do this from the start, and your solution will come into existence, ready and waiting to be M/V tested, personalised and whatnot. At no extra cost. Creating your information architecture in this manner from the ground up will add no extra time to your project. In fact I have found that it subtracts slightly from the implementation time.

And on that note, I think it’s time I step down from my soapbox. I will follow-up this post with a more technically to-the-point post explaining and demonstrating how an information architecture can come into place, following these principles. Also a few pointers to how your components can easily adapt these principles and finally; “what DO we do with Page Templates then?”.

Until then.


Kyle Heon said...

Mark, I'm enjoying this series and looking forward to the next one with concrete examples. What I'm interested in learning more about is how Page Editor can best be implemented into a Sitecore based application (and I do mean application) where everything is protected by a third-party authentication (think single sign-on). We have an application where the entire interface is derived by data stored external to Sitecore and have struggled to get the Page Editor to work effectively given these limitations. Would love to hear your thoughts on this.

Unknown said...

Excellent post Mark! I had a similar epiphany around components when DMS was released. Most of what I was building was not "datasource-friendly" unfortunately. I have a feeling a majority of "veteran" Sitecore developers found themselves in the same boat.

One question though - do you think providing an effective/efficient author experience in the Content Editor somewhat "forces" (not sure that's the best word) developers to think within/use the "page template" paradigm?

For example, when using Page Editor, all your components are easily added to a page-level item via the item presentation details. However, to add those same components to a page-level item via the Content Editor would require mucking around in the presentation details dialogs - which most content authors probably won't do (unless you use something like the module in described in this blog post:

While I completely agree that ensuring components are datasource/Page Editor friendly is the best approach, I am curious to hear how other devs mesh the Page Editor/Content Editor experience.

Mark Cassidy said...

@Kyle: Not entirely sure what it is you are trying to accomplish. Third party authentication can be tied into Sitecore using things such as bespoke Membership Providers and the like. However having the Sitecore Page Editor work exclusively with non-Sitecore content would not be easily achieveable - it would be theoretically possible through things such as bespoke Data Providers perhaps.

Mark Cassidy said...

@Unknown: I do believe that in focusing on the Content Editor and the usability of it, one is likely to make the Page Template Mistake. While perhaps subtle, this is one of the points I was tying to make. I also believe however, that one can approach the IA using Component Templates and still achieve good Content Editor usability - my next post in the series will try and exemplify that.

Jan said...

Confirmed: Refactoring after the site is finished is expensive. Do we all do this mistake first?

Mark Ursino said...

Wow, what a long one here!

I pretty much agree with this stuff. I really started getting into datasourced components back in 6.2 when we wanted to re-use "modules" on various pages. Since then we have some standards that make sense:

* Have a base class (like the sublayout parameter helper) that wraps access to the datasource and if one is not set, uses the context item. This handles the logic question and your sublayouts always call the DataSource property regardless.

* The page template mistake is only partially a mistake. For example, certain pages maybe not be merely "brochure-ware" and may integrate with other systems. Having specific page types for this may be necessary for your logic.

* Know your audience and requirements: if they will only ever really use Page Editor, then componentize the hell out of everything you can! If they need to decently support content editor too without making it difficult to assign data modules, you may need to think about where you need to give...

* Global information (e.g. header and footer) cannot really be componentized too well unless you use standard values on a very low level "base page" template to assign the same header and footer data source items to all pages. I typically instead just define a predefined structure in a global area to support the header and footer.

Mark Cassidy said...

@Mark, I'm with you completely. The next post in the series only got longer I'm afraid - some things just can't be expressed briefly if done right.

I've done what you do; creating global structures to solve the obvious problems a pure "datasource or context item" approach presents. I no longer do however, I just don't find it to be neither necessary nor convenient any longer.

As for what to do with page templates, I'll be sharing my thoughts on that in my next post in the series.

Thank you so much for the feedback however, it is really appreciated.

Anonymous said...

I really love the idea of component architecture, but how do you convince a client that the project is progressing on time if you don't have any Pages (templates) to display early on.

I'm thinking mainly about my experiences with Digital Agencies as they tend to want to see the roof on the house before you have dug the foundations.

Then again I guess the aim of “Creating good Sitecore solutions” are never of interest to a digital agency, Or tis this just me being cynical.