This documentation relates to the latest version of Confluence.
If you are using an earlier version, please go to the documentation home page and select the relevant version.

Migrating to Velocity 1.5

Added by Per Fragemann, last edited by Christopher Owen on Jan 16, 2008  (view change)
All Versions
Click for all versions
Confluence 2.9 Documentation

Index

Confluence trunk development (2.8) will be based on Velocity 1.5. The migration to the latest version of Velocity brings with it some issues that Confluence developers need to be aware of.

Word tokens are no longer valid as the first argument to Velocimacros

In Velocity 1.4, the velocimacro syntax was changed to prevent the use of work tokens as the first argument to most directives (except for defining the macro itself). This makes the following, common webwork structure fail to parse in Velocity 1.4 and beyond.

#bodytag (Select "label=$theLabel" "name='extraLevelName'" "list=levelTypes" "theme='notable'")

This means that you must quote the first argument to make it a proper string.

#bodytag ("Select" "label=$theLabel" "name='extraLevelName'" "list=levelTypes" "theme='notable'")

For these directives to work correctly with the new syntax a patched version of Webwork 2.1 is also required. Confluence now depends on this custom version of Webwork 2.1.

Multi-line comments behave strangely in Velocimacros

Due to an apparent bug in Velocity 1.5 VELOCITY-537, multi-line comments in Velocimacros can cause ParseExceptions. Multi-line macro comments have mainly been used in Confluence to control the output of extraneous whitespace during the rendering of a macro. To work around this issue a new #trim() directive has been introduced that can be used to strip whitespace from macro rendering. This unfortunately introduces a slight overhead to rendering as whitespace must be trimmed in every execution at runtime rather than stripped by the lexer at template parsing time.

Using comments to control whitespace
#macro (globalLogoBlock)#*
    *##if ($settingsManager.getGlobalSettings().isDisableLogo())#* render nothing
    *##else#*
        *#<a href="$req.contextPath/homepage.action"><img src="#logo("")" align="absmiddle" border="0"></a>#*
    *##end#*
*##end
Using the trim directive to control whitespace
#macro (globalLogoBlock)
#trim()
    #if ($settingsManager.getGlobalSettings().isDisableLogo())
    #else
        <a href="$req.contextPath/homepage.action"><img src="#logo("")" align="absmiddle" border="0"></a>
    #end
#end
#end

We'll be able to revert to the previous method once VELOCITY-537 is fixed and integrated, although it's arguable that the new directive makes for more maintainable macros.

Exceptions from method executions in macro parameters are no longer swallowed

Due to another bug in Velocity 1.3, exceptions that occur during a method execution in a macro parameter evaluation were swallowed silently; the return value of such executions was null. Velocity 1.5 contains a fix for this which means its likely that we are going to run into situations where pages which previously worked regardless of broken method calls are going to fail with a MethodInvocationException. There's only one correct solution here: fix the broken method calls as we find them.

Equality test operator is more strict

In previous versions of Velocity testing for equality using just a single = worked. This has been made stricter in Velocity 1.5; you must use == otherwise a ParseException will be thrown.

Backwards compatibility with Velocity templates used in existing themes and plugins

We realise that some of the changes that Velocity 1.5 brings to Confluence could cause annoying compatibility problems and lots of work for plugin maintainers, particulary the new Velocimacro syntax requirements. Confluence 2.8 will load all plugin templates using a special resource loader which will attempt to automatically fix loaded templates to work with the new Velocity engine (com.​atlassian.​confluence.​util.​velocity.​Velocity13CompatibleResourceLoader). This does add some additional overhead to plugin loading (the template is adjusted once at load time and then cached) but it will ease the burden on plugin developers during this transitional period.

It is still a good idea for plugin authors to use the new Velocimacro syntax; updating your templates can be made easier by looking for the info messages logged by the resource loader whenever it finds incompatible syntax.

Found incompatible Velocity 1.5 syntax in resource: [resource name]; [template fragment]

Labels:

velocity velocity Delete
velocity15 velocity15 Delete
template template Delete
plugin plugin Delete
theme theme Delete
Enter labels to add to this page:
Wait Image 
Looking for a label? Just start typing.

Comments (4)

 

  1. Jan 16, 2008

    Roberto Dominguez says:

    Thanx for the heads up and for identifying what type of issues we would have to ...

    Thanx for the heads up and for identifying what type of issues we would have to deal with!

    Now, getting a little bit greedy, here comes some suggestions:

    • When upgrading a library, do you mind a paragraph or two on the rationale? (i.e. "To deal with performance issue because of blah..." or "To use this nice feature blah blah blah). This could give us also a heads up of new features or to be aware of work-arounds that are not longer required.
    • Noticed that Tangosol is being upgraded too. Are there going to be any issues we should be aware of? Noticed that the rationale is in the Jira issue itself. That's ok, as long as it is avail somewhere.

    1. Jan 23, 2008

      Per Fragemann says:

      You are right, I will try to incorporate that in the future. In this case we wan...

      You are right, I will try to incorporate that in the future. In this case we want to move towards auto-encoding every variable to prevent cross-site-scripting problems that have been troubling us a lot in the past. In general we consider it to be good practice to update libraries as often as possible, at least now and then

  2. Jan 16, 2008

    Guy Fraser says:

    Per thanks for the heads up on this and the details of what to look for, it's fa...

    Per - thanks for the heads up on this and the details of what to look for, it's fantastic to see this sort of information coming out before the release from a developer perspective.

    I agree with Roberto that a brief rationale would be useful - especially if there are new features we might not be aware of and could take advantage of. Doh, just read the ticket again - and properly this time. Yes, that is a nasty bug in 1.3.

    Confluence 2.8 is sounding like it's going to keep us plugin developers busy, I must say it's great to hear that you're finally dropping support for Java 1.4

    1. Jan 23, 2008

      Per Fragemann says:

      Yes, there will be quite a few changes, especially to the UI. Velocity is just t...

      Yes, there will be quite a few changes, especially to the UI. Velocity is just the first step, we are moving towards cleaner CSS and HTML, and also we will be using more (and better) JavaScript to enable easier navigation. It will be way easier in the future to create custom themes.

      And now that Confluence has a dedicated Engine-Room Team you can definitely expect more structural changes (to the better!) in the future. We will keep you informed!

Add Comment