Lessons Learned About Velocity Templates

Posted by on Mar 18, 2010 in Development, Lessons | No Comments

Four different companies I’ve worked for used Velocity Templates. The technology isn’t a corporate secret, it’s a popular way to get that JSP/PHP style of template based development back into your Java. There are a few lessons I’ve learned from developing in Velocity that I’d like to share.

1. Don’t compile it into your code. To people using Velocity correctly, this may rattle your brain a little. Why would anyone compile Velocity into their code? Why, because it’s the way we used to handle JSP. Some people still put the image folders and style sheets in folders pushed out in their War files. How many headaches has that cause you? I personally like putting Velocity in the database, but it would be my preference that all style sheets for individual pages would be served by database, image addresses, links, and anchors would follow. Some of you may be sitting there asking, why shouldn’t I put my Velocity in my war file? Isn’t it safe there?
The Answer to both questions is actually, because some day you are going to have to compile and deploy a war file so you can make a single spelling correction on a Velocity template. Ever put inline Javascript in a Velocity page? Now imagine maintaining that javascript by building the war every time you want to make a change. Imagine for a moment you have a javascript, dynamic image, dynamic data and a bunch of legacy code wound up together and the only way you can debug the problem is to build the war and put in about 1000 alert tags, one at a time, one build at a time.
Hurts doesn’t it? It may only take a second to start the build file, it may only take a second for the build to finish. The War may end up in the deploy directory a second later, and a fraction of a second later you alt-tab to your browser and hit f5, and wait the tenth of a second your page loads, but this is going to take awhile. “But Jason,” you cry out, “this is the essence of programming.”
No, the essence of programming is in the ease, security and reliability of the process, the elegance of the product, and the product’s speed to production and profit. Now imagine an included directory, outside of the war containing all of your Velocity templates. Imagine a tool like Notepad++ or even Excel used to rapidly edit and merge out the Velocity, CSS and html of each iterative change. Change, save, Alt-Tab to the browser, refresh, test.

2. Always, always, always assign variables with the nullable exclamation mark.
$some_variable versus $!some_variable

Why? Imagine for a moment that you realize that no matter how good you are, how long lived and how perfect your product, that someone else will work with it. They will change the code and someday, $some_variable may accidentally be deleted. If you check the logs for why your pretty page isn’t loading or why something is choking or see in glaring font on your production environment the variable $some_variable staring back at you from the page, you’ll know that by not adding a single exclamation mark (bang) you messed up the whole page from whenever and wherever in antiquity you wrote it.

3. Extend the Velocity Template, do not mess with the base source. This wasn’t my mistake, but my lesson. Do not meddle with the base code unless you plan on submitting it to the Velocity source project and are fairly certain they’ll adopt your solution. Velocity is going to change. It’s going to grow and adapt. Keep your code out of the base and don’t force others to carve through your hack.

4. Try not to build a Constants file out of Velocity. If something needs to be constant, set it in a flat text file. If something needs to be dynamic, don’t name it or add Constant to its name. This is a paradigm shift.

5. Keep your style out of Velocity, unless Velocity is being used to make your style sheets. Treat Velocity like it’s a sub-textual language to CSS and HTML. If you’re going to use Velocity to write both, keep them separate. Let Velocity write out your CSS and then let Velocity write out your html, but for the same reasons squared, don’t mix style in with your Velocity driven html. Keep them separate. Why? Because you’re going to some day want to skin this. The average corporate website gets a makeover every 18-26 months. If you work for a start-up, that change may occur every 6 months. Your masterpiece will find it hard to keep up with the styling of the next great Graphic artist unless style and function are kept in as separate a pen as possible.

6. Build it once, build it small, and then make it a self-sufficient include. Velocity is about templating, so if you’re going to build a table and use that table and its attached styles a billion times, make the table a function that incorporates a sub-template, do it once the right time, and dear God try to avoid cutting and pasting the same logic elventy billion times in your Velocity. Small, efficient, elegant and easy to debug!

7. Based off of number 5 and number 1, as much as possible, keep your Velocity driven Javascripts outside of your Html driven velocity. Javascript can be one of the biggest bears of any interface to debug. Thanks to firebug and other tools you can step through it all and find problems, but if a Javascript problem is caused by your velocity, find that out directly, not indirectly in a 40,000 line Velocity that includes html, javascript and about 5000 includes.

8. Start simple, keep it simple and as it grows, realize that it was always supposed to be this way. In other words, each time you do something where you follow the rules, remind yourself of why you obey them. If you’re up at 4:00 AM in the morning, and haven’t slept in 72 hours, and are about to break a rule, stop for a moment and appreciate all of the times you didn’t break the rules and choose not to. The developer who follows you will thank you for it.

Leave a Reply