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.
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.
- 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 pageTip:
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.