Announcement: You can find the guides for Commerce 7.5 and later on the new Elastic Path Documentation site. This Developer Center contains the guides for Commerce 6.13.0 through 7.4.1.Visit new site

This version of Elastic Path Commerce is no longer supported or maintained. To upgrade to the latest version, contact your Elastic Path representative.

Velocity - Templating engine

Velocity - Templating engine

Velocity is a template engine that serves as an alternative to JSP, separating Java code from the presentation tier. When working with Velocity, you will typically begin with a static HTML page and then add Velocity directives (or "code") to access and display the properties of Java objects. Files containing static text and Velocity code are called templates and have a .vm file extension. A Velocity engine is invoked to process the Velocity code in the template, rendering the result as text (HTML). In addition to the storefront UI layer, Velocity is used in Elastic Path to generate email messages and generate configuration files during the build process.

Syntax reference

The following subset of Velocity directives demonstrates the key funtionality provided by Velocity and also serves as a quick reference.

  • $!customer.address - Displays the address property of the customer object
  • $!customer.getAddress() - Displays the result of invoking the getAddress() method on the customer object
  • #if [#elseif] [#else] #end - Synax for Conditionals
  • #foreach( $ref in arg ) statement #end - Syntax for iteration (For Each loops)
  • #set($variable = "value") - Sets the value of a variable. The variable does not need to be declared
  • #include - Renders files that are not parsed by Velocity
  • #parse - Renders files that are parsed by Velocity
  • #macro - Defines a Velocity macro

Specifying paths and URLs in Velocity templates

The Elastic Path Search Engine Optimization (SEO) feature rewrites the URL of some pages in the storefront. For this reason, pages using SEO cannot use paths relative the the page's path. In this case, you must use the absolute path to images or URLs. By including the #templateInit() directive at the top of your page, a Velocity variable named $baseUrl will contain the base portion of the absolute path you will need. For example, use syntax below to link to index.ep.

<a href="$baseUrl/index.ep">#springMessage("bc.home")</a>

Best practices

  • Presentation logic of any significant complexity should be invoked from a Velocity macro
  • Velocity templates should be formatted so that they are easy to read
  • A Velocity template should consist of mostly HTML sprinkled with Velocity macros and functions
  • Use parameters to help abstract logic within a macro
  • Templates should NOT contain business logic
  • Most macros should be in the global macro library
  • Only macros that are highly-specific to a particular page should be defined at the top of the page
    Tip:

    The velocimacro.library.autoreload setting determines whether Velocity automatically reloads global library macros. During development, this should be set to true so that you do not need to restart your app server when making a change to the global Velocity macro library. For more information, see Velocity (Storefront) and Velocity (Commerce Manager).

For more information, see the Velocity website.