Item Forms on a Catalog Page

This tutorial will cover how to properly code forms on your catalog page. There are a number of different scenarios that we will cover in this tutorial:

Single item with quantity box
Single item with quantity box and drop down options
Single item with quantity box and variations
Multiple items with quantity box
Multiple items with quantity box and drop down options

Single item with quantity box

<form method="POST" action="${checkoutUrl}">
  <input type="hidden" name="merchantId" value="${merchantID}"/>
  <input type="hidden" name="ADD" value="${item.getMerchantItemID()}"/>

  Quantity: <input type="text" name="Quantity" value="1"> <br/>

  <input type="submit" value="add to cart"/>
</form>

Things to note about this code:

Where the form is posted to is the checkout URL which is available from the velocity variable $checkoutUrl
The merchant ID is contained within the form as a hidden input named "merchantId" and the value is pulled from the velocity variable $merchantID
The item that is to be added to the cart is contained within a hidden input named "ADD" and the value is pulled from the item object using $item.getMerchantItemID()
The quantity input is named quantity and has a default value of 1 so that the customer doesn't have to change it unless they want more than one.
There is a submit button for the user to click.

Single item with quantity box and drop down options

<form method="POST" action="${checkoutUrl}">
  <input type="hidden" name="merchantId" value="${merchantID}"/>
  <input type="hidden" name="ADD" value="${item.getMerchantItemID()}"/>

  Quantity: <input type="text" name="Quantity" value="1"> <br/>
  #foreach ($itemOption in $item.getOptions())
    #if ($itemOption.getType() == "dropdown")
      <input type="hidden" name="OptionName$velocityCount" value="$itemOption.getName()" />
      $itemOption.getName() <select name="OptionValue$velocityCount">
        #foreach ($dropDownValue in $itemOption.getDropDownValues())
          <option>$dropDownValue</option>
        #end
      </select> <br />
    #end    
  #end

  <input type="submit" value="add to cart"/>
</form>

Things to note about this code:

Same code as above, but with additional fields for the options
Options are passed as two parameters to checkout OptionName# and OptionValue# where # is an incrementing number. We use the $velocityCount variable to automatically assign the number as loop.
Only drop down options are being displayed in this example.

Single item with quantity box and variations

This scenario is fairly complex to code. We have a separate tutorial on Variations on a Catalog Site that you should read. This code is taken from that tutorial though to make this a complete example here.

<html>
  <head>
  ${group.getCatalogJavaScript()}
 
  <script type="text/javascript">
  var m = ${item.getVariationMatrix().getJavascriptItemVariationMatrix()}
 
  function formChange(f) {
    var variationNames = [
    #foreach ($variation in ${item.getVariations()})
      #if ($velocityCount > 1)
              ,
      #end
      "$variation.getName()"
    #end
    ];
 
    var htmlElements = [
    #foreach ($variation in ${item.getVariations()})
      #if ($velocityCount > 1)
              ,
      #end
      document.getElementById("VariationValue$velocityCount")
    #end
    ];
     
    ucCatalogHandleVariations(m, variationNames, htmlElements, f);
  }
  </script>
</head>
<body>
 
<form action="http://secure.ultracart.com/cgi-bin/UCEditor" method="GET">
  <input type="hidden" name="MerchantID" value="${merchantID}">
  <input type="hidden" name="ADD" value="${item.getMerchantItemID()}">
  <table> 
    <tr>
      <td>Quantity</td>
      <td><input type="text" name="Quantity" value="1"></td>
    </tr>

    #foreach ($variation in $item.getVariations())
    <tr>
      <td> $variation.getName()
        <input type="hidden" name="VariationName${velocityCount}" value="${variation.getName()}">
      </td>
      <td>
        <select name="VariationValue${velocityCount}" id="VariationValue${velocityCount}" onfocus="formChange(this)">
          <option></option>
#foreach ($value in ${variation.getValues()})
          <option>$value</option>
#end
        </select>
      </td>
    <tr>
    #end
  </table>
  <input type="submit" name="addToCart" value="add to cart">
</form>
</body>
</html>

Multiple items with quantity box

This scenario is what you typically see on a group page within the catalog when you are targeting wholesale customers. The goal of this form is to allow the customer to enter the quantities for a variety of items and then add them to the cart in a single operation.

<form method="POST" action="${checkoutUrl}">
  <input type="hidden" name="merchantId" value="${merchantID}"/>

  <table>
    <tr>
      <td>Item ID</td>
      <td>Description</td>
      <td>Quantity</td>
    </tr>
  #foreach($item in $group.getItems())
    <tr>
      <td>
        ${item.getMerchantItemID()}
      </td>
      <td>
        ${item.getDescription()}
      </td>
      <td>
        <input type="text" name="ADD_${item.getMerchantItemID()}" value=""/>
      </td>
    </tr>
  #end
  </table> <br />

  <input type="submit" value="add to cart"/>
</form>

Things to note about this code:

The items are displayed in a table format with the item id and description
The quantity field is named ADD_<item ID> where <item ID> is put into the field name with ${item.getMerchantItemID()}
The quantity field is initialized to an empty value and not 1 so that only those items they specify a quantity for will be added to the cart.