Elastic Path Commerce Development

Velocity Email Formatting

Velocity Email Formatting

Customizing Email

Email messages are created by ep-<topic>-email-handler modules in response to JMS events, and formatted by the Velocity template and properties files in ext-assets/src/main/assets/themes/electronics/default/templates/velocity/email. Changes to email format or content should be made directly in the ext-assets module.

Configuring Velocity

Velocity is a templating engine. It is used to merge data from the application with HTML templates to generate text or HTML email messages.. The serviceVelocityEmail.xml file is located in the ext-integration/src/main/webapp/WEB-INF/spring/service directory. It contains settings that allow you to configure behavior of the Velocity engine.

The cacheSeconds property of the globalMessageSource bean specifies how long message source resource files are cached. In production, it should be set to -1 (infinite). For testing purposes, it can be set to a positive value. This will allows you to test changes to message source resource files without having to restart your application or servlet container.

<bean id="globalMessageSource" class="org.springframework.context.support.ReloadableResourceBundleMessageSource">
        <property name="basenames">
        	<list>
        		<value>/WEB-INF/misc/message-source/application</value>
   	            <value>/WEB-INF/templates/velocity/globals</value>
        		<value>org.springframework.security/messages</value>
        	</list>
        </property>
         <!-- Set cacheSeconds to -1 in Production Environment -->
	    <property name="cacheSeconds"><value>${ep.velocity.cache.seconds}</value></property>
	    <property name="defaultEncoding"><value>UTF-8</value></property>
    </bean>

For optimal performance, the following properties on the velocityProperties bean definition should also be set:

  • file.resource.loader.cache: Set this value to true for production to cache templates in Velocity's loader. Set this value to false for development so that changes to templates will take effect immediately.
  • velocimacro.library.autoreload: This parameter enables/disables automatic reloading of Velocity macros. Set this value to false for production. For development, setting this value to true will allow changes to Velocity macros to take effect without restarting the server.
  • velocimacro.messages.on: Set this value to false for production for improved performance. When developing Velocity templates, this value can be set to true to see Velocity logging and debugging information.
  • runtime.log.logsystem.class: Set this value to org.apache.velocity.runtime.log.NullLogSystem as shown below for production.
    <entry key="runtime.log.logsystem.class"><value>org.apache.velocity.runtime.log.NullLogSystem</value></entry>