Help

Tutorial

An introduction to NVelocity for custom email template design

Auctiva Commerce allows you to create and edit email templates that can send notifications to customers. The email template design can be customized using NVelocity to display a multitude of order information. This tutorial will show you how to use NVelocity to create dynamic email templates in Auctiva Commerce.

What is NVelocity?

NVelocity is a template engine that enables you to design HTML email templates with variables and logic. Many of the default email templates in Auctiva Commerce include lines of NVelocity code that help display order information. You can find out more information by visiting the NVelocity website.

While NVelocity is considered to be a relatively easy coding language to learn, it certainly should be approached with caution if you're new to coding email templates. You might consider looking for a professional who can code these types of email templates for you.

NVelocity Basics

We highly recommend you read the Velocity User Guide and the Velocity Template Language (VTL) Reference. These resources will give you a much more in-depth look at this coding language. Use this tutorial as a starting point for your research.

Variables are a critical component in constructing an email template.  In most cases, you will use shorthand variables. A shorthand variable leads with the "$" symbol and then is followed by a VTL Identifier and then usually a property (e.g., $store.Name). You can find this variable in almost all the default Auctiva Commerce email templates. See the following HTML example:

<p>Thank you for shopping at $store.Name</p>

The "$store.Name" variable will be replaced with your store name in an HTML email template in this example. It's a good idea to look at the default email templates to see what variables exist (go to Marketing> Email> Templates). The best practice for creating new email templates is to copy similar default email templates and make your customizations as needed. This will ensure that you're calling the right variables.

Logic and directives are another critical component to email templates. NVelocity can do a variety of literal, conditional and loop statements. These all begin with the "#" symbol. The literal statements are "#set" and "#end." You can use "#set" to assign a value to a variable. You will use the "#end" statement to stop conditional and loop statements.  See the following HTML example:

#if ( $order.Items.TotalPriceById(0) > 199.99  )
<p>Thank you for your order. Get 20 dollars off your next order by using coupon code <b>LOYALCUSTOMER</b></p>
#else
<p> Thank you for your order!</p>
#end

This example uses an "#if" statement that requires an "#end" directive to stop the statement. In the email, this code will render a unique message that gives a coupon code to customers who have an order value of $200 or more. Otherwise, the customer gets a generic "Thank you" message.

The "#if" statement is one of many conditional statements you can use in an email template. You can also use the "#eslseif" and "#else" statements with "#if" statements.

The next most common statement is the "#foreach" loop. This is commonly used for listing order items or multiple shipments. See the following HTML example:

<ul>
#foreach ($orderItem in $order.Items)
<li>$orderItem.Name</li>
</ul>

In this example, the "#foreach" statement will return a list of each Order Item Name for all the ordered items. Much more sophisticated methods are used in the Auctiva Commerce default email templates for displaying this type of information.

This completes the introduction to the basic NVelocity components. We recommend taking a look at the default email templates to get an even better understanding of what is possible using this coding language. To view the HTML code for the default email templates, go to Marketing> Email> Templates. Click on the Edit icon for any of the templates and copy and paste the HTML code to an HTML editor.

Tags

◄ Back to Help

Customer Support

If you have been unable to find the answer you were looking for using our Help documentation, please file a customer support request. We have customer support professionals ready to help you 24 hours a day, Monday - Friday (excluding major holidays.)