Updating to Velocity 2.0

*Note* that this help page has been updated to reflect the improvements introduced by the 732_20180912 patch.

Starting with Rhythmyx 7.3.2 patch 732_20180608, Percussion uses version 2.0 of the Velocity Template Engine.  For most customer implementations, applying this or any subsequent patch is a seemless upgrade.  However some implementations may require that User Velocity Macro's, Templates, and Bindings be updated to take into account updates and changes in the Engine. 

Velocity 2.0 Upgrade Guide

There is a migration guide for Velocity 2.0 on the Apache Velocity website.  Much of this migration work was performed when Percussion updated the Velocity Assembly engine.  However, some customers may be required to make Template, Macro, and Binding updates specific to their Rhythmyx implementation.  As of patch level 732_20180912 and greater, many of the early restrictions imposed by Velocity 2.0 have been either mitigated or resolved.   If you still encounter errors in Templates or Macro's after this patch level, please create a support ticket and the team will work to resolve the issue for you.  You implementation may use a coding pattern that is unique, that may require a new Auto Correct pattern be added to the product. 

Hyphens (-) in Variable Names

As of patch level 732_20180912 and greater, this restriction no longer applies. The stock version of Apache Velocity 2.0 does not currently allow for hypens in variable, slot, or template names.  Based on customer feedback, Percussion has updated the Velocity Engine to relax this restriction for backwards compatibility purposes. After patching to a current patch level, customer's that experienced issues with the hyphen restriction will no longer have problems with Templates or Macros that use hyphens. 

"#" or "$" String Literals

As of patch level 732_20180912 and greater, this restriction still applies, however the system will automatically correct these strings when found in Templates or Macro files. After patching, customers should no longer experience errors in template preview or publishing related to these string literals.   We do recommend that these string literals be replaced in Templates and Macros eventually, so that the Auto Correct Velocity Precompiler can be turned off for optimal performance. With the new Auto Correct feature, these change are not required immediately after patching. 

Background. Velocity 2.0 parses strings between double quotes as mini templates, looking for Velocity variables between the quotes so that they can be substituted.  Text in single quotes is not evalauted by the parser.  Velocity 2.0 has a quirk where if it sees certain characters like "#" or "$" it generates a parsing error.  It is sometimes common for Template developers to use # in strings as it relates to an anchor/bookmark on URLs.  To work around this quirk, update your templates to replace "#" with '#'.  Another common string is "$" for jQuery or regular expressions. Updating this to '$' should resolve the issue. 

As text between single quotes are not parsed by the engine, replacing the double quotes with single quotes causes the parsing error to go away.  In general practice, it is best to only use double quotes for strings that will contain Velocity variables that you want replaced when the Template is rendered. 

100% Comments

Another Velocity 2.0 quirk is that it fails to parse VM files that contains 100% comments.  Typically such files may be old test files, or retired Velocity macro files, still sitting on the server.  To work around this quirk, rename the affected file to have a non .vm extension, like .archive or .bak.  Alternatively such a file could be deleted from the server completely, as it is 100% comments, it is not being used.

velocityCount and velocityHasNext variables retired

After patching, customers should no longer experience errors in template preview related to these deprecated velocityCount or velocityHasNext variables.   We do recommend that these strings be replaced in Templates and Macros eventually, so that the Auto Correct Velociy Precompiler can ultimately be turned off for optimal performance. With the new Auto Correct feature, these change are not required immediately after patching. 

Velocity 2.0 now always uses the call by sharing (aka Java) calling convention.

Call by sharing: the method arguments are not passed by reference, meaning that trying to assign a new value to a formal parameter will not change the value of the actual parameter after the macro terminates execution, but changing the internal data of a passed object will work. This is the behavior of Java method calling. Warning: the call-by-sharing behavior is new in Velocity 1.7. The previous behavior was closer to true call-by-macro expansion.

The Velocity 2.0 approach of "Call By Sharing" means it requires the caller use the same name as the macro parameter (which works as all variables are global). 

Velocity 2.0 Macro Evaluation Stratergy

Velocity Macro's Pass Variables by Name