Max: A story about FreeMarker and Velocity

Discussions

News: Max: A story about FreeMarker and Velocity

  1. Max: A story about FreeMarker and Velocity (24 messages)

    In "A story about FreeMarker and Velocity," Max highlights why he's migrated from Apache's Velocity to Freemarker, a move other projects (such as WebWork 2) have also made. Primarily, the focus is on function and user-friendliness, with errors not being transparently ignored.

    He highlights the strengths and weaknesses of both Velocity and Freemarker; for Velocity, however, the crucial flaws are in the areas of error handling and logging. He adds that Freemarker has much better error handling as well as far simpler configuration. Downsides to Freemarker appear in terms of a lack of simple escapes for Freemarker expressions, and the fact that its syntax doesn't work well in XML editors.

    He concludes the entry with:
    Velocity served me well and is probably serving many projects well; it just did not cut it well for Hibernate Tools. Today I am convinced that I could have saved myself and the Hibernate world from a lot of trouble if I had decided to use FreeMarker from the beginning.
    In fairness, Max adds that another version of Velocity is being worked on, but that some of his concerns (such as external dependencies) are still heavier than he'd like.

    Threaded Messages (24)

  2. Cool work! Thanks Max.

    I was just looking for something like this.

    By the way, is there any comparison between their performance/speed?
  3. 1. Velocity's configuration can be done in a properties file. He's pushing a freemarker agenda on that one.

    2. Why is integration of your storage mechanism important in dealing with your template engine? I agree, velocity could throw a better error, but where's the abstraction?
  4. 0. no i don't have concrete numbers on performance/speed. Only noticed that my complete unittest suite time where not using significantly less/more time and memory.

    1. My whole point was that I did not want it to be in a properties file! I wanted it to be in java api and *at least* have access to some of these "worker objects" instances like the resourceloaders. Being able to configure it in a properties file were secondary for my usecase.

    2. I don't get this question ? Why would I ever want to abstract it away to a point where I cannot trace back to the origin of error ?!
  5. 1. My whole point was that I did not want it to be in a properties file! I wanted it to be in java api and *at least* have access to some of these "worker objects" instances like the resourceloaders. Being able to configure it in a properties file were secondary for my usecase.

    So instead of configuring outside the app in a properties, or some other configuration file, you rather do it in code. Understood.
    2. I don't get this question ? Why would I ever want to abstract it away to a point where I cannot trace back to the origin of error ?!

    I just wonder why your tempate engine could cause a DB related error.
  6. 1. My whole point was that I did not want it to be in a properties file! I wanted it to be in java api and *at least* have access to some of these "worker objects" instances like the resourceloaders. Being able to configure it in a properties file were secondary for my usecase.
    So instead of configuring outside the app in a properties, or some other configuration file, you rather do it in code. Understood.
    2. I don't get this question ? Why would I ever want to abstract it away to a point where I cannot trace back to the origin of error ?!
    I just wonder why your tempate engine could cause a DB related error.

    I think that having sensible defaults for the 90% usage case makes sense. If that means that one or two lines of Java code can replace the need for "yet another property file" then I think that is a strong argument for FreeMarker. Plus I think another part of Max's point was that setting up FreeMarker via code was more java-friendly then just calling Velocity's setProperty() over and over.

    My bet is that FreeMarker also has some sort of property-file way of configuration (is that true?) so it isn't like that method of configuration isn't available.

    Am I blind or am I missing where the DB-related error is showing up on Max's example? To me the point is clear

    <code>

    Expression table.namee is undefined on line 15, column 14 in doc/tables/table.ftl.
    The problematic instruction:
    ----------
    ==> ${table.namee} [on line 15, column 12 in doc/tables/table.ftl]
    ----------

    Java backtrace for programmers:
    ----------
    freemarker.core.InvalidReferenceException:
     Expression table.namee is undefined on line 15, column 14 in doc/tables/table.ftl.
        at freemarker.core.TemplateObject.assertNonNull(TemplateObject.java:124)
        at freemarker.core.Expression.getStringValue(Expression.java:118)
        at freemarker.core.Expression.getStringValue(Expression.java:93)
        ...
    </code>

    Is much easier to decipher and debug than Velocity's cryptic error.

    Can anybody aruge that Velocity isn't good at what it does? No, it has been used successfully on a ton of projects. I do think it is very useful to list its shortcomings.

    Max, have you communicated with the keepers of FreeMarker about making the ${} more easily escapable?
  7. I think that having sensible defaults for the 90% usage case makes sense. If that means that one or two lines of Java code can replace the need for "yet another property file" then I think that is a strong argument for FreeMarker.

    Velocity has a default .properties file within the velocity jar, with defaults values. It seems he wishes to configure it beyond that.
    Am I blind or am I missing where the DB-related error is showing up on Max's example?

    I got the assumption from...
    Caused by: java.lang.IllegalArgumentException: $seam_appname is not a valid reference. at org.hibernate.tool.hbm2x.HibernateEventHandler.referenceInsert(HibernateEventHandler.java:11) at org.apache.velocity.app.event.EventCartridge.referenceInsert(EventCartridge.java:131) ... 19 more
  8. George: yes, freemarker community knows about the escaping. Asked them about some details before i wrote the blog - they were very helpfull. Same was the velocity community for that matter.

    Spencer: The only reason I mentioned defaults was that I find Velocity's default settings to be way to loose. I would rather have a strictness I can loosen up or at least have various options I can enable/disable. FreeMarker provides strictness upfront which you as a user can configure to be "less-strict" without implementing custom eventhandler stuff, BUT of course you can implement custom "strictness" if you want.

    And no, just because hibernate is part of the package name does not mean it has something to do with the database. If you had noticed then the package name is org.hibernate.*tool* which is where the migration from velocity to freemarker occurred. ...and the error I showed were an example what occurred when you run with a custom "strictness" in velocity.
  9. You are right - I was looking in the code block for what you were talking about. Didn't see it in the paragraph above.
  10. XML Handling[ Go to top ]

    I also like Freemarker's built in support for XML data models - in comparison Anakia feels like an after thought.
  11. freemarker is nice[ Go to top ]

    and I use it too. For example www.abclinuxu.cz generates its content via Freemarker, it has 150 thousands users a month.
  12. Nice article[ Go to top ]

    I have been using velocity for a long time now and I got to the point that I could not tolerate the same problems you describe here.

    To ease migration from velocity to freemarker I'm using guara, a small java framework that supports both template engines running at the same time. Using guara I am able to migrate from velocity to freemarker slowly.
  13. freemarker syntax non-starter[ Go to top ]

    There's no doubt FreeMarker is better implemented and more carefully designed, but it's xml-based syntax, particularly for use in creating xml-ish documents like html is terrible. Velocity's syntax is exactly what I want from a templating language, and it's a pity we can't have the excellent implementation of FreeMarker combined with Velocity's easy syntax.
  14. re: freemarker syntax non-starter[ Go to top ]

    [Freemarker's] xml-based syntax, particularly for use in creating xml-ish documents like html is terrible.

    Agreed, but then this was addressed in v2.3.4 so it's no longer an issue.
  15. re: freemarker syntax non-starter[ Go to top ]

    ...and also mentioned in the blog ;)
  16. re: freemarker syntax non-starter[ Go to top ]

    [Freemarker's] xml-based syntax, particularly for use in creating xml-ish documents like html is terrible.
    Agreed, but then this was addressed in v2.3.4 so it's no longer an issue.

    []-based syntax is hardly any better than <>-based.
  17. Whitespace?[ Go to top ]

    The last time I used Velocity was about a year ago so this may have been fixed. I switched to FreeMarker because I could not completly control white space in Velocity, which I felt was a very important feature in terms of a template engine. FreeMarker does not add space between directives and if for some reason line breaks or unwanted white space does show up, you can strip it out with a directive (<#t>, <#rt>, <#lt>). I've found this very helpful when exact white space is an issue and really struggled to find a solution with Velocity for this.


    Keller
  18. Whitespace?[ Go to top ]

    I actually had it on my list of things to mention in the blog, but I forgot to mention it.

    Whitespace is still an issue with velocity; freemarker again has much better default AND you can override it.
  19. Error Handling and Syntax[ Go to top ]

    Couple of point on this subject I would like to make:

    1. Error handling in Velocity 1.5-dev is revised to pass through RuntimeException classes. You can see an example of this with Click:

    http://click.sourceforge.net/docs/error-npe.html

    2. Freemarker is a more powerful and expressive templating language than Velocity. However this is both a blessing and a curse, as Velocity is easier to learn and use.

    3. Velocity syntax is easier to read in HTML templates than the Fremarker syntax.

    regards Malcolm Edgar
    http://click.sourceforge.net
  20. Error Handling and Syntax[ Go to top ]

    1. does not change the fact that it does not fail on bad reference/syntax with a reference to where it went wrong.

    2. if you just limit you to the features velocity has, then freemarker is equal...it is only if you choose to use the more expressive features you need to learn more.

    3. freemarker has two types of syntax. tag based <> and now hard-bracket based [] which makes this point void IMO.
  21. Error Handling and Syntax[ Go to top ]

    1. Velocity 1.5-dev does actually it does show you where it fails:

    http://click.sourceforge.net/docs/error-parsing.html

    2. Well the point was Velocity is easier to learn.

    3. I have tried the new FM [/] syntax is HTML pages, and its still pretty ugly. Its better than jsp xml style markup, but is very heavy.

    regards Malcolm Edgar
  22. Error Handling and Syntax[ Go to top ]

    1. Velocity 1.5-dev does actually it does show you where it fails:http://click.sourceforge.net/docs/error-parsing.html2.

    Regarding point 1 above, is it really appropriate to compare Velocity 1.5 beta code with the current stable production version of FreeMarker? The features that Max is talking about in FreeMarker have been part of our stable/production version for well over 3 years(!)

    Moreover, while Velocity 1.5 beta is surely some improvement over the current stable version, it does not catch up with functionality that has been present in FreeMarker for the past 3 years at least. In fact, I recently came upon a wiki page that describes a roadmap for Velocity releases. As far as I can tell, there is, to all intents and purposes, nothing on Velocity 2.0 wishlist that is not already implemented in the stable production version of FreeMarker. You can see: http://wiki.apache.org/jakarta-velocity/RoadMap

    Even if all the points on Velocity 2.0 roadmap (support for JSP taglibs, sensible whitespace handling, macros with bodies....) were to be implemented, it might be approximately competitive with FreeMarker's current stable feature set.

    All of this does have certain clear implications IMO. FreeMarker is still a fairly well known project in the java/web world. So this is a codebase that has been subjected to the stresses of real-world usage in a large number of projects out there. It is very well tested.

    Now, I am obviously biased, but given this, I am puzzled as to why anybody looking for this kind of tool should opt for Velocity 1.5 beta over FreeMarker 2.3 stable?
    Well the point was Velocity is easier to learn.


    As for your this point, that Velocity is easier to learn, this just strikes me as false. FreeMarker does not offer a steeper learning curve to a new user. To learn to use FreeMarker to do the same things that you do with Velocity is no harder.

    Granted, FreeMarker is a more powerful, full-featured tool. But that just means that the extra power is there when you need it. If you never need to use a JSP taglib, FM's support for taglibs does not cause any steeper learning curve on the user. The same is the case of the XML processing functionality and so on. It's there when you need it, but it does not impose a steeper learning curve on new users.

    Point 2 is just false.
    3. I have tried the new FM [/] syntax is HTML pages, and its still pretty ugly. Its better than jsp xml style markup, but is very heavy.regards Malcolm Edgar

    As far as I can tell, point 3 is also false basically. I don't mean the statement that the syntax is ugly, since that is purely subjective and doesn't fall within truth/falsity, but the statement about the syntax being "very heavy".

    Concretely, let's compare certain constructs in VTL (Velocity template language) with FTL (FreeMarker template language).

    Straight assignment. In FTL:

    [#assign x=3]

    In VTL:

    #set ($x=3)

    Here, I grant that the VTL is 2 characters shorter than the FTL. However, this is not because of the logic and structure of the syntax, but because we are using a longer keyword 'assign' vs. 'set'. If we allowed 'set' as a synonym for 'assign' (Maybe we should...) then the FTL syntax would be one character shorter. (This is because we don't need the $.

    Consider an if statement. In FTL:

    [#if name = "Joe"]
      ...
    [/#if]

    In VTL, we have:

    #if ($name == "Joe")
      ...
    #end

    In this case, the VTL and FTL constructs are exactly the same length. However, I think the FTL has a clear advantage over the VTL, which is that it clearly distinguishes the end of an if directive over another sort of directive, where VTL always uses the same closing tag of #end. FTL is the same length, but has a tangible readability advantage.

    Now, let's consider a loop:

    In FTL, we have:

    [#list users as user]
       ...
    [/#list]

    In VTL, we have:

    #foreach ($user in $users)
       ...
    #end

    This time, the VTL construct is actually one character longer. 30 characters vs. 29. This is because of the need for the $ characters within the parentheses when FTL avoids that visual clutter.

    Now, it's true that in VTL you can write:

    $foo

    vs.

    ${foo}

    However, this is an ambiguous advantage, particularly wrt point 2, learnability, since it provides 2 different ways of writing the same thing. FM is consistent in requiring ${...}.

    As for the aesthetics, that the FTL snippets above are "ugly" and the VTL snippets presumably are not, that is not within the range of objective analysis really. I defer to the reader the judgment as to whether the above is a valid argument in favor of Velocity over FreeMarker.

    Anyway, Malcolm, this stuff about FM's syntax being "very heavy" (presumably in comparison with VTL) does not stand up to any real scrutiny. I really believe that a fair-minded objective review of this issue (not from me of course, I'm not objective) would come to the conclusion that there is no significant difference in notational convenience between the two tools.

    Regards,

    Jonathan Revusky
    --
    lead developer, FreeMarker project, http://freemarker.org/
  23. So why is FM syntax wrong?[ Go to top ]

    I don't really get why is FreeMarker syntax wrong because of the tag delimiters. I surely know about mistakes in the syntax design, but it has no much to do with the tag delimiters, still I mostly just hear that complain. One could say that <...> confuses the HTML editors. Well, OK, since the user community is lazzy to write editor plugings. But there is the [...] now. Surely it has no editor syntax-highlight support for that yet, but the pont is, why do many people still find it a wrong design? You see, at least it's esily understandable and clearly visible where are the bounds of the directives (unlike with #end, where you sometimes have to know tricks like #end#**#blah). And at least you see which diretive is closed. This last is critical for any template that heavily uses macros with body (that Velocity templates don't do, since Velocity doesn't support macros with body). Also, it's clearly visible in the start-tag if it has corresponding end tag, i.e. [#foo /] VS [#foo]...[/#foo] (which is, again, not a problem for Velocity only because it doesn't support macros with body).

    Regarding $foo VS ${foo}. This has again good reasons. With $foo the delimiting is tricky (harder to learn, easier to miss). Like, is this: "This is $userName. Blah" OK, or the dot will be the part of the expression after the $? Of course you can always write ${foo}, but still, this is an additional rule to remember. Also, a very important thing is that FreeMarker allows you any expression in interpolations, like you can write ${x + 1} (no need to write #set(y = x + 1) $y). Velocity doesn't allow expressions in general after the $ AFAIR, it allows references only. This is an important difference, that begs for better delimiting in FreeMarker. Last not least, since "$" (not only "${") is a reserved pattern in Velocity, the chance for accidental clashes is much higher. Worst, you can't even clearly escape $ in Velocity, except like ${D}, where D is a variable that stores the string "$". Really, in Velocity, if $foo is just static text or an interpolation depends in runtime conditions, which is IMO really bad from the point of maintenance and avoiding templat author's mistakes in general.
  24. Error Handling and Syntax[ Go to top ]

    The features that Max is talking about in FreeMarker have been part of our stable/production version for well over 3 years(!)

    As someone adequately noted on Max's blog, it is not dissimilar to Windows Vista vs. Mac OS X feature comparison - head over to the comments section of Max's blog for a link to hilarious videos where the videos introducing Windows Vista features have been replaced with images showing their long available Mac OS X equivalents (leaving the original audio track where some Microsoftie narrates about the new "innovative" Vista features). I watched them to understand why it was linked in, and it is freaking hilarious!
  25. I appreciate your pointing out Max's blog entry to readers of theserverside.com.

    Since this seems to have generated some reader interest, I think it's appropriate to point out other blog entries that detail a transition from Velocity to FreeMarker.

    http://blog.nominet.org.uk/tech/Web/2005/06/29/Switching+from+Velocity+to+FreeMarker.html

    What I think is interesting about the above referenced blog entry is that the author, Matt Ward, makes the case that FreeMarker's language syntax (contrary to what Velocity supporters claim here) is actually preferable for a variety of technical reasons.

    http://jroller.com/page/webwork2live?anchor=switch_to_freemarker_from_velocity

    This is one of the Webwork people explaining why he switched to FreeMarker.

    In the following blog entry, Howard Abrams, a FreeMarker user, relates how he tried to use Velocity but went back to FreeMarker because Velocity's limitations were too frustrating. (Note that in his preamble, Howard has some of the project history wrong. FreeMarker actually predates Velocity.)

    http://www.howardism.org/thoughts/001511.html

    In general, for people interested in this topic, our page here: http://freemarker.org/fmVsVel.html will be of interest.

    Anyway, thanks again for generating some buzz. It is hard to compete for user mindshare with projects from ASF and other well-known entities.

    Regards,

    Jonathan Revusky
    --
    lead developer FreeMarker project, http://freemarker.org