A 12-hour driving trip from Brisbane to Sydney can sometimes shield the driver from the side-view windows – with only one thought in mind; to get to the destination. Take a break, the journey is every bit as good as the destination.
Symphony is soon reaching version 1.8. It’s over two years old and it’s been around its fair share of blocks. Symphonians now expect more features, greater stability and fewer bugs. The Symphony team is every bit as committed to these but because of it, we sometimes lose sight of existing features that need a little bit of tender, love and care. Each of the members in the Symphony development team have their own pet peeve with the system that we vow to one day fix. In this article, I will illustrate one of my pet peeves.
So a clutch is called paper towel and the steering wheel is Bono?
Very early in Symphony’s development we came up with the idea of reusable XSLT code snippets called Utilities. A feature along the same line is Masters, which are also reusable XSLT code. In retrospect, the implementation of these features are a little odd. To include an Utility or Master in a page, you select the ones you want associated to a page. When the appropriate page is called, PHP will inject the selected Utility and Master code into the XSLT document. This sounds logical, doesn’t it? Well, not really.
As our main development rule, we strive to keep the templating layer in Symphony as transparent as we can possibly make it. Developers with prior XSLT knowledge should able to understand and integrate their knowledge into Symphony without having to troll through documentation. It’s not quite the case at the moment. Data sources, events, Utilities and Masters are all Symphony specific functions and terminology. From the XSLT developer’s point of view, all they are concerned about is XML, XSLT and XPath. Worse still are the XSLT beginners trying to grasp the idea of both Symphony and XSLT at the same time. They are often confused by the mix of these terminology. Where Symphony ends and XSLT starts can be a very daunting learning exercise, and this is a counter-definition of what a “transparent layer” means.
Utilities and Masters are specific terms in Symphony but to an XSLT developer, they are simply XSLT documents. I don’t actually mind the use of these Symphony terms. It’s convenient to ask other Symphonians in the community: “can someone post a date formatting Utility?” or “I think my Master for outputting a CSV file isn’t working”. However, when Symphony go so far as creating specific inclusion methods and dedicated user interface elements for these, it’s no longer simply defining these terms as characteristics, it’s now actually classifying them. Users no longer identify them as what they truly are but something else entirely. This brings me to the the next issue.
It’s got cruise control, use it
As we have just established, the process of including Utilities and Masters into a page is done by PHP hijacking the result of the source XSLT document and inserting them between the <xsl:stylesheet> element. It goes without contention that hijacking is bad. To a developer with XSLT background, this occurrence is both unexpected and just plain weird - nobody likes their source document snatched and modified.
The reason why it’s a particular pet peeve of mine is that XSLT already have instructions for this occasion. It’s called <xsl:import> and <xsl:include>. In fact these XSLT instructions are far more powerful than Symphony’s current method.
<xsl:import> acts similarly to Object Oriented Programming principal of class inheritance. It even allows multiple inheritance. The beauty of functional-based languages are that there are no discernible differences between single inheritance and multiple inheritance. Function overloading, inheritance and higher-order functions are simply in the genes of XSLT.
So why did we go with the method we have now? The below describes 3 reasons:
- To include an Utility via the
<xsl:include>method, the target document must be a valid XSLT stylesheet. i.e. complete with the<xsl:stylesheet>element. Currently, Utilities are just<xsl:template>snippets. - Including external files have the potential (I say this without proof or research) to be less efficient than having all the code inside a single document. I’m basing this off our experience with the highly inefficient
document()function. - Portability. The current method inserts all associated Utilities and Master in an XSLT page so going to
?debugwill yield a single complete XSLT document.
Looking back, the above reasons are not legitimate issues. Regarding the first point, my fear was that having Utilities as full-fledged XSLT documents could seem complicated for some. However, it’s apparent now that having this voodoo-crazy-body-snatching-magic is equally as complicated for someone new to wrap their head around. Plus, if someone is to learn the system, it’s much better for them to learn it the proper way with <xsl:include>.
Regarding the second point, I have yet to do some serious benchmarking with the heavy use of <xsl:include> and <xsl:import>. This should prove to be an interesting exercise. My prediction is that if the included XSLT document is local, the instantiation of the XSLT document should be equally as fast, with only a slight increase in overhead.
The third and last concern is actually very interesting. I’ve once thought that being able to go to ?debug to see my fully working, self-contained XSLT document is a good thing. Whilst it’s good in some cases, it completely overshadows the point of reusability. This concept is parallel to CSS in HTML. Currently, Utilities and Masters are like inline CSS whilst the idea of using <xsl:include> and <xsl:import> are like external CSS. The point of abstracting code to external file is to allow common reusable elements to be edited once and applied globally. Further more, this external XSLT document would be self-contained and standalone, promoting reusability and allow the code to be shared amongst the XSLT community and not just specific to Symphony.
Pedal to the metal, let’s get there!
My goal is to one day abolish the current way of including Utilities and Masters and instead rely on XSLT’s built-in mechanism for including such things. Of course, there will still be a clean and elegant interface to simplify the process. For example, on a new Symphony page, a list of XSLT documents will be presented on the sidebar - selecting a document will automatically insert the appropriate include/import instruction into code editor. Unfortunately, currently there are no plans to implement this change into Symphony but it’s something the team is eager to implement in the future.
Discussion
Driving on the wrong side of the road is your thing? Maybe you like throwing two cents at oncoming traffic. Whatever the case, let us have it!
Mark Lewis 22 June 07
