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

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")