This post is a write-down of my experiences building a XML/XSLT driven simple CMS system. In it I will show you the required technologies, my approaches and my solutions to problems I've encountered. You'll need a solid understanding of XML at least, understanding of Ant and XSLT helps a lot, too.

This post contains tons of XML and I tried my best to format it in a readable way — in fact I've spent hours to get everything nicely on the screen.

Requirements to the CMS

I had several objectives when I built my system:

• All mundane and repetitive tasks should be automated, including thumbnail generation, creation of a global navigation, synchronizing with a live site
• Flexible enough to support new "content types" and new views
• Versionable with Git, Subversion or other SCMs
• Creation of output artifacts should be a single command

Technologies

The most prominent and important technology I used is XSLT 2.0. If you don't know what XSLT is, here is XSLT in a nutshell.

XSLT stands for eXtensible Stylesheet Language Transformations. What it does is surprisingly simple. It takes a piece of XML as input (aka source tree or input tree), applies some transformations on it and outputs a new piece of XML. Sounds simple in theory, however in practice it is usually somewhat more complicated because XSLT is a functional language and sometimes requires you to solve problems backwards and don't even get me started on XML namespaces...

Traditionally you'd have one input XML file, one XSL stylesheet and accordingly one single XML output file. However with the new xsl:result-document I can suddenly output into several files.

As I'm using XSLT the next technology used is XML of course. Not much to say about this except that it is involved in pretty much every step. To bind everything together I'm using Apache Ant, an incredibly flexible tool. Interestingly enough Ant uses XML files for its build files which comes in handy later on. Also it solves one of my requirements: it is just plain text and therefor versionable.

Last there is image manipulation. I've experimented a bit with the Ant image tasks that use JAI to perform manipulation but quickly dropped that approach as this task won't even let you specify a quality parameter for image manipulations. I've ended up using an old friend: ImageMagick. ImageMagick is an amazing toolkit of versatile command line tools to modify images. It allows to modify images in many different ways from resizing to color correction or combining them.

Basic Structure

The basic structure of an XML/XSLT driven CMS contains one or more XML files that contain the "raw" data for the website, XSLT to transform it into XHTML and assets. More on assets later.

The XML Part

The XML file used in my project is a very simple one. It defines "pages" that get translated into real HTML pages. Each page has a section called contents which in turn contain the actual page contents. Let's have a look at a short sample:

Well, so far nothing impressive. Actually it looks like more work compared to typing out the actual pages themselves. But behold, here comes the stylesheet to actually turn the above XML into nice websites (XHTML):

Now it get's more interesting. Let's dissect what the above XSLT does. The blocks in line 10 to 12 are a template that matches the root level element in the source XML tree. All it does is to call the next matching stylesheets which are in lines 14 to 19. This template does exactly the same and passes on. Then we reach line 18 with the template matching page elements.

Line 18 defines a variable called filename which is prefilled with with the filename attribute from the XML page element. The next line sports the so much praised (at least by me) xsl:result-document element. If you read the line it gets clear very fast that it should output a new HTML file (format="html" href="$filename"), nicely formatted (indent="yes") and with the appropriate DOCTYPE declaration. The  next lines are just an HTML boilerplate with head and content type. Please note that this is a very minimalistic example. Usually you would include stylesheets, JavaScript includes and other additional headers there. For simplicity they are omitted.

Lines 28 to 31 output a new title tag populated with the title attribute from our source attribute. Convenient. The CMS is starting to take shape.

And finally lines 33 to 35 will call another template lines 41 to 46 which just copies the HTML into the output document.

So far so good. What have we achieved? The stylesheet creates a new page based on boilerplate HTML - which can be arbitrarily complex with CSS stylesheets, JavaScript and more - and pre-fills the title and the actual body. Now let's add more functionality. Every good website needs a navigation. We can achieve that easily by adding another template that matches all page elements. We add a few new lines to the boilerplate HTML:

Looks simple enough. This will output a new DIV, fill it with a unordered list and calls another template.  The interesting part is the select attribute: it tells the XSLT processor to select all root level page elements. Now let's have a look at how the called template looks like:

The XSLT processor will translate this into global navigation of our site. All top level pages will be listed with the correct title and the correct filename.

The Ant Part

Now that we have the stylesheets and the input XML files in place, we'll need an elegant way to transform the whole site with on simple command. As discussed earlier Ant is a good choice for this. I won't delve into the actual ANT buildfile as it is pretty straightforward. What I want to show is how to use XSLT to generate ANT buildfiles from other XML. This is actually a pretty powerful technique as I can custom tailor ANT files to whatever need I have. In this particular example I want to show how to create image thumbnails.

Here is what we have. In our input XML file, we reference images. For those images, let's say, product shots, we have the originals lying in some location in the filesystem. Those images need to be scaled down to a high res view (800×600) and to a thumbnail (128×128). We could do that with an ANT pathmatcher, but that would just take all the images it can find, not just the referenced ones. Bad and slow. And how do we keep the build directory free of old and unused pictures then?

What we'll do instead is we'll take the input XML file, create a XSLT stylesheet that will grab all the image references and put them into a custom ANT build file which in turn calls an image manipulation program (ImageMagick) to scale down the pictures. There's a few other goodies in here too, e.g. automatic file name cleanup. Here is the images.xsl:

Google Sitemaps

Most people that have used Google's Webmaster Tools know about the sitemap. No need to write them manually any more, you can easily use the XML representation and a XSLT stylesheet to generate it for you:

Issues

So with all the technologies in place, I ran into some issues but all of them could be solved quickly. I'm listing them here hoping they'll help other people.

XSLT 2.0 with Ant

This one was most annoying. Per default Ant has an xslt-task which allows you to transform XML but it is limited to XSLT 1.0. If you read the documentation you'll find out that you can plug in different XSLT processors but you are still quite limited. If you want to use XSLT 2.0 with Ant get the amazing Saxon processor and use their Ant task which is a bit hidden on their page. Get it from the Sourceforge download site. This task lets you leverage the full functionality of XSLT 2.0 including the xsl:result-document.

All you have to do to get it working is to copy the required JARs into the classpath, declare the custom task and use it:

Now you can use the saxon-xslt task:

XML Namespaces in HTML

This was a tricky one. The problem was that in my custom XML I had snippets of HTML which I wanted to mirror into the output documents. I used the xsl:copy-of function which basically did what it was supposed to. It copied the (X)HTML over but by doing so, it had to adjust the namespaces for the XML. The input document had no namespace declarations at all and the output document was bound to the XHTML namespace. So the processor did exactly what it is supposed to: it added null namespace  declarations to the copied elements which looked like this:

Not a problem per se but unfortunately invalid XHTML. The solution to this problem is surprisingly simple: Add namespace declarations to the input document:

The above lines will put the input document per default into the XHTML namespace and everything else in my own, personal namespace. Regular (X)HTML markup however does not get any namespace prefixes, so it will be put into the XHTML namespace:

Conclusion

The one big problem I still have with this system is that it does not support hierarchical pages yet. But if the need arises it could be added without too much effort. Another moose with the system is that it still requires editing XML which is neither user-friendly nor easy for non technical users. But one could easily create a Flex or AIR app to modify and edit those files. Thanks to Flex' really good XML support it should not be hard to do that. I could even think of a Grails Webapp generating the XML for this (using the brilliant XML markup builder).

In general it is a really powerful and flexible system. As I am running this on a UNIX system I can harness all the tools and goodies that are there. Ant and Java give me whatever power and libraries I need. So I can steer this thing in whichever direction I want.

If you have any questions feel free to comment below or drop me an email.

So, what's the idea behind this script? Everybody that uses Liquibase (if you are not, check out my blog post about what Liquibase is and how to use it) knows how painful it is to update your changelog.xml. Liquibase already gives you a great tool to start with, the db-diff command. However, it is hardcoded to diff the current environment's database against the test database. This is annoying as you'll have to modify your datasources and keep the database schema updated manually. But fear not, here is my (surprisingly) easy solution.

I've created a simple script (or rather, I took the db-diff script and hacked it), which I've called incremental DB diff (all the other cool names are already taken...) and what it does is the following:

1. update the schema in the db-diff (or whatever you call it) database using the changelog.xml
2. diff the database of the current environment against this database and output the diff as Liquibase XML

So, how is this a good thing? Easy: this little script will automatically create a target database to diff against using the changelog.xml which is good, as the changelog.xml represents your last migration status. And as it uses a separate database it doesn't influence the test database.

After running the script just put the output in the changelog.xml and you're done.

All you have to do to use this is to drop the file into your /scripts/ directory, create a new database and an according datasource entry for the environment "dbdiff" like this:

	dbdiff {
		dataSource {
			driverClassName = "com.mysql.jdbc.Driver"
			dbCreate = "create-drop"
			url = "jdbc:mysql://localhost/foo_dbdiff"
			username = "foo"
			password = "bar"
		}
	}

Download DbDiffIncremental.groovy. Drop me a mail or a comment if you have questions.

It took me some time to figure it out, hopefully I can save you from going through all this.

The Flex web tier compiler usually gives me this error:

Error: Could not resolve <namespace:Component> to a component implementation.

 <namespace:Component/>

error during compilation Could not resolve <namespace:Component> to a component implementation.

Initial research confirmed what I thought, this error is caused by a mismatch between a XML namespace declaration and the actual location of a component. However the location and the namespace declaration looked right and the issue occurred only after I had moved the questionable component into a separate module.

After two painful hours I realized that the Flex webtier compiler, as configured with GraniteDS, resolves namespaces relative to modules, not relative to the source folder. D'oh!

The solution I came up with was simple, might be naïve though. I figured that if resolution is relative to the Module and not to the source folder, there might be no such source folder as I would expect it. A quick look into the flex-config.xml found in <GRAILS_PROJ>/web-app/WEB-INF/flex/flex-config.xml confirmed this:

<!-- List of path elements that form the roots of ActionScript class hierarchies. -->
 <!-- not set -->
 <!--
 <source-path>
 <path-element>string</path-element>
 </source-path>
 -->

So there is no explicit source path set. So I changed it so it would point to <GRAILS_PROJ>/grails-app/views/flex:

<!-- List of path elements that form the roots of ActionScript class hierarchies. -->
 <!-- not set -->
 <source-path>
 <path-element>../../../grails-app/views/flex</path-element>
 </source-path>

Voilá - it works. However, as mentioned earlier, this might be a very limited solution, but for now it works.

Heute habe ich auch endlich mal die Bilder von meinem Handy heruntergeladen und da ein paar schöne Schmankerl aus den letzten Monaten dabei sind, habe ich sie hier hochgeladen. Enjoy.

Meine Mailbox, Facebook und Lokalisten quillt über vor lieben Geburtstagsgrüßen. Vielen vielen lieben Dank an alle!

Nächste Woche Freitag geht es weiter zurück nach München. Das Programm ist voll. Ich will Lily München und ein paar Sehenswürdigkeiten in Bayern zeigen, Freunde besuchen und natürlich ein wenig Zeit mit meiner Familie verbringen.

Bis denn.

Am Freitag vor zwei Wochen ist Lily's Hund Tiger nach einem Unfall von uns gegangen. RIP Tiger. :'(

Nun aber zu besseren Nachrichten. Den heutigen Samstag haben Lily und ich auf Toronto Island verbracht. Habt ihr euch gefragt woher diese atemberaubenden Bilder von der Toronto Skyline kommen? Ja genau, von Toronto Island. Man hat die gesamte Skyline im Blick. Aber seht selbst...

Auf Toronto Island haben wir ein einem Volleyballturnier zu wohltätige Zwecken teilgenommen. An dieser Stelle sollte ich wohl anmerken das ich seit 2003 nicht mehr Volleyball gespielt habe. Aber das war ok nachdem wir in der Anfängerliga waren. Und keines der Teams war wirklich besser als wir. Oder eigentlich doch, denn irgendwie haben wir jedes Spiel bis auf zwei - einmal weil die andere Mannschaft nicht da war und einmal war ein unentschieden - verloren haben. Macht nix, hat Spaß gemacht. Außerdem haben wir so viele Hunde gesehen. Von Huskeys so groß wie ein Kalb bis zu Golden Retrievern und Black Labs so ziemlich alles.

Später gings dann zum 1000 Tastes of Toronto Festival am Queens Quay, so eine Art kulinarischer Jahrmarkt. So ziemlich jedes bessere Restaurant in Toronto war mit einem Stand vertreten. Die Bilder sprechen für sich...

Und zu allerletzt: Ich komme im Juli über das Wochenende 4. und 5. nach Deutschland. Ich bin nur ein paar Tage da aber ich hoffe es ist genug Zeit euch alle wiederzusehen.