The Razor Mediator for Tridion – in practice

In this article, I’m going to tell you about how we used the Razor mediator for Tridion to achieve cleaner and more maintainable templating on a recent project for one of Indivirtual’s customers. This is a useful technique, which will be attractive to many Tridion developers. How does that fit with a real life development project, and what challenges did we have to overcome? Read on…

What’s it all about? – Mediator – schmediator

If you’ve spent more than a couple of years doing technical Tridion work, you’ll remember that for a long time, templating of web sites was done using VBScript and the Tridion Object Model (TOM). The choice was limited: you used VBScript, (or perhaps in theory, JavaScript). Component templates could also be written in XSLT.

Then with the 5.3 release, Tridion unveiled a new templating engine. This was motivated by their long-term plans to move from Microsoft’s COM+ platform to the .NET framework. Various other parts of the system had already been re-written in .NET, but the existing templating engine was closely dependent on the COM+ technologies, so replacing it required a whole new architecture. VBScript wouldn’t be a long-term option anymore, so they had to select a new templating language. The new language would have to be widely acceptable to web developers, and backwards compatibility was essential, so they would have to keep the ability to execute old-style VBScript templates.

Quite a technical challenge, you may think, and you’d be right. They solved it by abstracting the templating engine out into a separate piece of software, which could be configured as a plug-in. The Tridion Content Manager would still store the content and the templates, but this new pluggable element would “understand” the template’s instructions for rendering the content. For each one that you configured, you’d get another templating language.

These plug-in components were called “Mediators” (perhaps with a nod in the direction of the Gang of Four’s design pattern of that name), and Tridion release 5.3 shipped with several: to start with you had three that could execute COM+ templates for backwards compatibility, then you also had four mediators for the new pipeline model that was introduced. One of these was for the Dreamweaver templating syntax, but I’ll come to that in a minute.

The pipeline

“So what’s this pipeline?” That’s what you were about to ask, right? Well instead of just replacing the old model, SDL Tridion R&D had looked at the fundamentals of the templating activity, and realised that in practice there were often several different groups of people involved. People like web developers were more comfortable and productive dealing with templates that were a direct representation of the HTML, but you also needed other programmers taking care of some other tasks. Ideally, they could ensure that the data was prepared in a way that could easily be consumed directly from an HTML template. To achieve this, the new style templates were composed of a list of “template building blocks” that would each be executed in turn, allowing each building block to manipulate the data to be used by the following building block. Towards the end of this pipeline would be the real “templating” building block that laid out the HTML. Programmers would prepare the data using “C# fragment” building blocks, or “Assembly” building blocks, and HTML specialists would use “Dreamweaver” building blocks to lay out complete or partial pages. (The fourth of the new mediators was for “compound” building blocks, which allow you to group the other kinds together into re-usable sub-pipelines.)

But what if I don’t like Dreamweaver syntax?

Tridion had needed to choose a suitable templating syntax to get everyone started with the new approach. They had chosen the mark-up used by Adobe’s popular Dreamweaver web editing tool. This had the benefits of being familiar to many people, and of being a tried-and-tested approach. You could even use WEBDAV to work directly with your Tridion templates from Dreamweaver, (although this never became really popular as far as I can tell).

Dreamweaver syntax is great if you’re working with Dreamweaver, but the templates very quickly stop looking like HTML. The looping and conditional constructs are written as HTML comments, which can be a bit verbose: I’ve lifted this rather extreme example from Tridion Practice

In particular, you have to imagine what this is like if you aren’t actually using Dreamweaver, but editing the templates by hand, which is probably the commonest case.

OK – I get it. Perhaps XSLT would be better

So, if that example of Dreamweaver syntax makes your eyes hurt, you’ll be very happy to hear that when SDL Tridion built their new templating system, they realised that while Dreamweaver syntax was a good pragmatic choice for the moment, it wouldn’t be too long before people wanted other things. As they had already had to design a pluggable architecture, it made sense to expose the mechanism as a public API. This meant that it was possible for people to implement a mediator for their templating language of choice, and it wasn’t long before some people in and around SDL Tridion professional services had made an XSLT mediator. This became popular, in part because it had more possibilities for wiring up and deploying helper libraries and functions. Even so, it takes a special kind of person to spend large parts of the day staring at templates like this:

Yes – OK – I’m making a point, but I’m sure you see what I mean.

The trouble is that, try as we might to separate coding and templating, the coding always creeps back into the templating layer. A simple loop rapidly becomes a nested loop, and so forth. If we resign ourselves to a certain amount of coding constructs in our HTML templates (and I would certainly advocate keeping this to an absolute minimum) then, the less verbose the code is, the better. XSLT, it turns out, becomes highly verbose as soon as you even want to do something as simple as invoke a function. This leads to you extracting your functions to separate building blocks, and pretty soon, if you want to figure out how things work, you need to have five editing windows open, which is no fun at all.

Enter Razor – a modern HTML templating language

So what can we do about it? Well it turns out that to create the View part of Model-View-Controller style web sites in ASP.NET, you have very similar issues. After all – you are templating-out HTML based on data that’s getting handed to you by some engine; the only difference is that you’re doing it in the web application. ASP.NET supports pluggable view engines, of which one of the most popular is Razor. The essence of Razor templating is that you can use a @ character to introduce C# coding constructs into your HTML. The engine is smart enough to guess (pretty well) when you’re writing C# and when it’s HTML, even though one is mixed through the other.

Seeing the potential benefits, Alex Klock (an ex-Indivirtual programmer now working in the US) used the Razor view engine to create the Razor Mediator For Tridion. He released this as an open source project, and it is now used at several Tridion implementations around the world.

Here’s a sample from the project documentation. Perhaps a real-life example would be a bit more complex, but you can still see how the logic for looping and accessing Tridion items is embedded fairly painlessly in the HTML.

Choosing to use the Razor Mediator at Indivirtual

Implementing such a mediator is quite a bit of work. Although the native Razor engine can parse your template and distinguish the coding constructs from the literal output, it’s not much good unless you can extract data from your components and other items in the templating pipeline. Beyond that, in addition to being able to execute loops and conditionals, you also need an expression language that gives you meaningful access to the items in Tridion. Like I said: a fair amount of work – I just had a quick check, and the Razor Mediator For Tridion has well over a thousand lines of code. Enough that writing your own would be a significant commitment.

When we began development for the new Noordzeeloket website for the Dutch Ministry of Infrastructure and the Environment, we were starting with a new installation of SDL Tridion 2011 and all the content for the site was going to be freshly produced. We wanted to make the most of this clean start, and this meant also taking a look at how the technology had moved on since the previous VBScript implementation on an older version of Tridion.

After looking at the possibilities, using Razor templating looked very attractive. The clean syntax would give us an expressive way of writing templates that would be very well suited to this kind of project. We needed to consider the pros and cons of introducing an open-source library: if for some reason it didn’t work, we couldn’t call on SDL Tridion support. So we downloaded the code and read through it and realised that if necessary we could maintain it ourselves. It’s licensed under GNU GPL v2, which would mean we could do anything we needed to. Of course, we’d also have the support of the very active Tridion community, for example at tridion.stackexchange.com. Based on this, we went ahead and based our design on using the Razor Mediator.

How it worked in practice.

Once we began the templating work, it was clear that we’d made a good choice. We had one or two queries about how to use the syntax correctly, but the community around ASP.NET MVC is also very active, and we could easily find answers on the Internet.

From the beginning, we interacted directly with other contributors. On more or less the first day, I reported a minor issue with the documentation, and it was fixed almost the next day, this time by another ex-Indivirtual Tridion specialist: Robert Curlette, who is also actively using the mediator in his work. (Often in the Tridion community, you get the feeling that everyone knows everyone else, but this almost seemed like stretching co-incidence too far!)
Of course, it’s never all plain sailing, and not long after, we discovered that one of our templates was using the mediator in an unusual way, which exposed an issue with the mediator caching some values too aggressively. We fixed it locally and moved on with our work. We also submitted our fix as a patch, and shortly afterwards it was incorporated in the next release.

Technical Challenges

Things went pretty well until we were preparing to roll out to the production server. During performance tests, it became apparent that under load when publishing, we could see a memory leak. We weren’t prepared to release the project to the customer without getting this fixed, so we had to do something about it. Memory leaks are always difficult to pinpoint, and at first we weren’t sure where the problem lay. It could have been in our own code, in the mediator, or in SDL Tridion. We began with a careful code-review of our templates, and at the same time we were working with SDL Tridion support and professional services to eliminate any issues on their side. In parallel, one of our developers, Andreas Johansson was looking at the mediator code. He found an issue with the caching mechanism that would cause a leak. We fixed this, and made the fix available publicly on a branch of the code repository while we went back to testing.

Just as we were about to breathe a sigh of relief, we got the first results back from testing. There was still a problem. After looking at it again, we were convinced that our fix for Andreas’ issue was solid. So there was a second issue, and in fact much more severe than the one we’d just fixed. Back to the drawing board….

This time, it took more than a code review to find the problem. We ended up having to set up memory monitoring on a loaded system and examine which objects were in memory. The mediator is built using the .NET framework, which has automatic garbage collection, so any unused objects should have automatically been removed. The challenge was to find out why this wasn’t happening, and by the time we were finished, we’d learned quite a lot more about using low level debugging tools like WINDBG and SOS. It felt like quite a triumph to eventually figure it out.

During all this, the rest of the razor mediator community was supporting us as we made progress. Alex had been in touch via Skype to offer his help, even though he was leaving the next day for his honeymoon. As soon as we had a fix, again we made it available on the repository, and then Robert popped up offering to do some independent testing.

From our own testing, we were able to establish that the fix was solid, and in due course, we were able to release the project for production use.

Conclusions

This whole experience has shown us very clearly not only that it is possible to use open-source projects in our work, but that it works well even at this small scale. (Obviously, we routinely use libraries from large-scale projects at Apache and elsewhere, but that’s different.) We’ll certainly use the Razor mediator in future work, with the confidence that there is a solid community and that we are part of it. Both Andreas and I are now committers on the project, and if necessary, we’ll work with the other contributors to make the mediator even better.