Lithium has been around for quite a while. Through the years, we've used various technologies to render content on communities: JavaServer Pages (JSP), Velocity, and now FreeMarker. Out of the box, FreeMarker is a simple templating engine for Java. The real power of any templating engine, however, is in the injection of a data model for use in a template. As our Professional Services team, partners and customers have needed them – and sometimes before they need them – we've been adding objects to this data model to create richer content on our communities.
A separation of concerns
Templating engines generally attempt to split apart the logic of an application (in our case, our Java-based application code) from its content (HTML, CSS, etc.). This allows frontend engineers and designers to work on the look-and-feel of a web application without digging into the internals of the application itself.
An unfortunate side-effect of a technology such as JSP is the ability to call directly into Java code from the template. This can make upgrading existing templates from one version to the next extremely painful. Take this code for example:
<div>
<% User user = new User(34); %>
<%= user.getAvatar("medium"); %>
</div>
If we were to change the number of parameters to the "user" object's "getAvatar" method to 2 in version 13.1, any customer who had used this simple call would need to have their page(s) updated to reflect that change. It might not seem painful when it's just one method, but think about how many changes are made to code in a given month and how many potential "time bombs" there could be in related customer templates.
But what about FreeMarker?
FreeMarker, first and foremost, guards us against potential upgrade headaches (not to mention security hassles) by disallowing direct Java execution. This is "A Good Thing." Another step Lithium has taken is to "contractualize" the objects that are exposed to FreeMarker, so you won't run into any surprises when upgrading your community from version to version; any changes to the exposed objects – which should be few and far between – are communicated to our Upgrade team before communities are upgraded.
But as templating engines are generally only as good as the data models you provide them, we need a powerful set of objects so you can build the next great community. Fortunately, one of the very first objects we provided access to through FreeMarker was the "rest" object. This object encapsulates all of the calls you can make through our REST API (which is itself considered a contract point in our application), and makes them available directly to FreeMarker. If you haven't checked it out, and you're looking to build new components, I highly recommend reading the documentation (you'll need access to the Dev Nation section of the Lithosphere). In fact, we've exposed a number of objects to FreeMarker to provide information about your community.
Templatizing CSS
If you've been paying attention to new web technologies, you might've seen the terms "SASS" and "Compass" when reading about CSS. SASS is an extension of CSS that allows designers and engineers to reduce redundancy when writing CSS rules (which, historically, tend to be rather verbose). SASS templates are evaluated to CSS that browsers can understand. Compass is a framework built on top of SASS that provides common CSS patterns (for example, gradients, border radii, etc.). If you've ever had to write a cross-browser CSS rule to display a gradient, you may have had to write something like this:
.gradient {
background-color: #444444;
background-image: -webkit-gradient(linear, left top, left bottom, from(#444444), to(#999999));
background-image: -webkit-linear-gradient(top, #444444, #999999);
background-image: -moz-linear-gradient(top, #444444, #999999);
background-image: -o-linear-gradient(top, #444444, #999999);
background-image: linear-gradient(to bottom, #444444, #999999);
}
Yikes. Compass takes the monotony out of using properties and values that either have not been adopted by all vendors yet (hence the "vendor prefixes" like "-webkit-" and "-moz-" shown above), or are generally a pain to write (like clearfix). A similar declaration in Compass may look like this:
.gradient {
@include background-image(linear-gradient(top, #444444, #999999)); }
}
SASS and Compass are pretty hot right now, but Lithium does not support them yet. We've evaluated them for possible inclusion in the future (most likely as an alternative to FreeMarker, not as a rewrite). However, we do our own template processing when genearting CSS... using FreeMarker. The syntax is similar, and is exposed to CSS templates through the "css" context object:
.gradient {
${css.gradient("top", "#444444", "#999999")}
}
A few benefits are obvious: less typing, fewer mistakes and increased browser coverage. But as the web moves forward and as browser vendors update their applications to properly support CSS3 properties and values in non-vendor-prefixed forms, using these methods will also have the side-effect of being dynamically updated to maximize support across browsers. We keep up with sites like Paul Irish's CSS3 Please and others for updates in browser compatibility, and can easily update the FreeMarker objects to output new syntax as it becomes available. That saves you the headache of updating your stylesheets manually.
Where to next?
Whenever we expose new ways to customize our application, we're careful to not go overboard and expose too much, especially if we may need to change things in the future. Having said that, a good deal of our FreeMarker objects have come from suggestions or limitations brought up by our partners and customers. If there's something we don't have that you think we should, get in touch with us! We'd love to see you creating new functionality on your communities, while strengthening our platform at the same time.
Adam Traver is a Senior Software Engineer on Lithium's Engineering team.
He spends his days creating new product features that you're going to love and his evenings as one of Lithium's resident table tennis gurus. Follow him on the Lithosphere as AdamT. Looking to join the Engineering team? Check out Lithium's careers page for more details.
... View more
