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.

1 - Creating the T-Shirt Velocity template

1 - Creating the T-Shirt Velocity template

In the previous tutorial, you learned that Velocity templates belong to a collection of assets, known as a theme, that define the look of an Elastic Path store. In this tutorial, you will create your own Velocity template to display a personalized T-shirt's fields.

Creating the T-shirt Velocity template and .properties file

Velocity templates are files that bridge Java code and HTML. Templates contain a mixture of HTML and Velocity code that read or set Java object properties.

In this tutorial, the personalized T-shirt product has two pieces of information that customers can personalize: front text and back text. To get this information into Elastic Path, we'll create a Velocity template that includes two form fields where users can enter T-shirt text.

To create the Velocity template:

  1. Navigate to the <Source Code Root>extensions/assets/ext-assets/src/main/assets/themes/electronics/default/templates/velocity/catalog/product directory and create a file named tshirtTemplate.vm.
  2. In tshirtTemplate.vm, add the following Velocity code:
    #set($pageName = "catalog/product/tshirtTemplate.vm")
    #productMainTemplate(false true "" true true)
    #macro (addTshirtFields)
    <table border="0">
    #springFormTextarea("command.cartItems[0].tshirtFields.frontText" "maxlength='255'")
    <tr><td colspan="2">#springShowErrors("<br>" "req")</td></tr>
    #springFormTextarea("command.cartItems[0].tshirtFields.backText" "maxlength='255'")
    <tr><td colspan="2">#springShowErrors("<br>" "req")</td></tr>
  3. In the same directory, create another file named and add the following properties:
    tshirt.customize.section.title=Customize your T-shirt!!!
    tshirt.frontText=Front text (100 characters maximum)
    tshirt.backText=Back text (100 characters maximum)
    errors.tshirt.back.text.too.long=Back text is too long! It must be 100 characters or less.
    errors.tshirt.front.text.too.long=Front text is too long! It must be 100 characters or less.
    This properties file will store the T-Shirt Velocity template's localized messages and form field label text.

Adding the T-Shirt template to productMacros

As you can see above, tshirtTemplate.vm defines an addTshirtFields Velocity macro. To display the T-shirt personalization form fields whenever the Storefront displays a T-shirt product, you need to call the addTshirtFields macro in the Velocity template that displays store products in detail: productMacros.vm

  1. In <Source Code Root>extensions/assets/ext-assets/src/main/assets/themes/electronics/default/templates/velocity/catalog/product, open productMacros.vm and locate the following block of code:
            <input id="quantitySelect" type="hidden" name="cartItems[$cartItemIndex].quantity" value="1"/>
          <label for="quantity">#springMessage("productTemplate.qty")
          <select id="quantitySelect" name="cartItems[$cartItemIndex].quantity"
                #if ($command.getCartItems().get(0).isCalculatedBundle())
            #foreach( $index in $counter )
              <option value="$index" #if($productViewBean.isUpdate() && $productViewBean.getUpdateCartItemQty() == $index)selected #end>${index}</option>
        #set ($cartItemIndex = $cartItemIndex + 1)
        #if($minQty > 1)
            <div class="minqty">#springMessage("productTemplate.minOrderQty") $minQty</div>
    <div class="clear1"></div>
    <span id="globalInventoryError"></span>
  2. Insert the following Velocity code after the above code:
    <!-- Display personalization fields if it's a t-shirt -->
    #if($pageName == "catalog/product/tshirtTemplate.vm")