Templating Choices

Which templating engine to choose is mostly a simple matter of preference, although a variety of factors can be applied as you consider which is best for your situation. All things being equal, you will probably want to use Freemarker as it is a true templating engine.

APT-Jelly was originally desiged to be used with Commons Jelly (hence the name), but that decision was met with some constructive criticism by the Java community because of Jelly's syntax and templating limitations. Jelly is not a true templating engine, but an XML scripting engine. The XML syntax of the Jelly templates (scripts) puts significant limitations on its templating capabilities (especially when outputting another XML document, for example). This requires Jelly templates to make some awkward workarounds for some basic templating techniques.

Based on some recommendations for templating engines from the community, the decision was made to support a true templating engine for the next release of APT-Jelly. The choice of Freemarker over Velocity was made primarily because Velocity didn't support named parameters for user-defined directives (macros), but there are also many other advantages of Freemarker over Velocity, including better error handling/reporting and a smaller dependency footprint. For a full feature comparison, see Freemarker vs. Velocity.

For most users, either Freemarker or Jelly will fully meet your needs, but Freemarker will probably do it in a cleaner, more concise manner. But if you need to write your own directives or extend the templating capabilities in any way, you might find that Jelly is cleaner, more consistent code.