Commerce Commerce 1.x Product Catalog Add to Cart Form
To add a product to the cart, you’ll need to submit the product record ID (not the resource ID) to the cart page. There are two form variations supported, one for multiple products, and the other for single products.
Table of Contents
Single Products Form
With the single products form only one product can be added to the cart per request. As the structure of the form is a little easier than the multiple products form, it is easier to use this when providing different products as variations in your catalog.
The form includes:
- an
add_to_cart
hidden input with value 1, this is used to trigger the add to cart logic. - the product ID in a hidden
product
input. This should be made dynamic, for example with the commerce.get_resource_product_id snippet, a TV holding the product ID(s) (like the Commerce Products TV), or a different way that you establish a products’ ID. - the quantity in a
quantity
input
<form method="post" action="[[~[[++commerce.cart_resource]]]]">
<input type="hidden" name="add_to_cart" value="1">
<input type="hidden" name="product" value="123">
<label for="add-quantity">Quantity:</label>
<input type="number" name="quantity" value="1">
<input type="submit" value="[[%commerce.add_to_cart? &namespace=`commerce` &topic=`frontend`]]">
</form>
The [[%commerce.add_to_cart]]
lexicon was added in v0.12; in older versions you may need to hardcode your submit text.
Multiple Products Form
To add multiple products in a single submit action, you need to provide a add_to_cart
value and a products
array. The products array is provided as product id => [options]
, for example products[123][quantity] = 5
.
In a form, that looks somewhat like this. Replace 123
with the ID of your product.
<form method="post" action="[[~[[++commerce.cart_resource]]]]">
<input type="hidden" name="add_to_cart" value="1">
<label for="add-quantity">Quantity:</label>
<input type="number" name="products[123][quantity]" value="1">
<input type="submit" value="[[%commerce.add_to_cart? &namespace=`commerce` &topic=`frontend`]]">
</form>
Note that these two form structures cannot be mixed. The products[id][quantity]
array format takes precedence over the product
+ quantity
structure.
Adding custom fields to the order item
Commerce (as of 0.11) supports simple custom fields using the Item Data Module. The module allows you to define what field names to accept from the user, and then you can start sending those fields along with the add to cart request. This is great for user comments or simple product variations that have no impact on stock.
See the Item Data Module documentation for instructions on how to set that up.
AJAX
You can also add products to the cart using AJAX. Just serialize the form values, and POST those values to the cart page with an XMLHttpRequest. Instead of HTML, you’ll get JSON back.
When using
window.fetch
or other ways of sending an ajax request except jQuery, you must specify either theX-Requested-With=XMLHttpRequest
orAccept=application/json
(v1.3+) header to trigger the JSON mode.
For example the following jQuery snippet can be used to progressively enhance add to cart forms with AJAX.
<script type="text/javascript">
$(function() {
// Grab all forms with a class of `add-to-cart`
$('form.add-to-cart').on('submit', function(e) {
// Prevent regular submit
e.preventDefault();
var form = $(this),
action = form.attr('action'),
values = form.serialize();
$.ajax({
url: action,
method: 'POST',
data: values,
dataType: 'json',
success: function(result) {
console.log(result);
// If we receive a success message, show an alert.
// You probably want to make this do something nice instead.
if (result.success) {
if (result.message && result.message.length) {
alert(result.message);
}
if (result.redirect) {
window.location = result.redirect;
}
}
else {
if (result.message && result.message.length) {
alert('An error occurred: ' + result.message);
}
else {
alert('Could not add the product to the cart.');
}
}
}
});
});
});
</script>
The JSON returned by the server will look something like this.
{
"success": true, // true or false
"message": "Added <Name of Product> to your cart.", // a localised success/error message
"redirect": false, // false or the url to redirect the user to
"redirect_method": "GET", // GET or POST. When this is POST, and redirect is a URL, you should create a form and submit it
"redirect_data": [], // An array of name => value pairs of data to submit when redirect_method = POST
"errors": [], // an array of errors
"output": "... the full html that would have normally been shown ...",
"order": { // information about the order / cart contents
"subtotal": 3000,
"discount": 0,
"shipping": 0,
"transaction": 0,
"total_ex_tax": 3000,
"tax": 0,
"total": 1800,
"total_due": 1800,
"total_quantity": 2,
"subtotal_formatted": "€18.00",
"discount_formatted": "€0.00",
"shipping_formatted": "€0.00",
"transaction_formatted": "€0.00",
"total_ex_tax_formatted": "€18.00",
"tax_formatted": "€0.00",
"total_formatted": "€18.00",
"total_due_formatted": "€18.00",
"items": [
{
"product": 1,
"sku": "BEANIE",
"name": "modmore blue beanie",
"link": "link/to/product.html", // false or a link to the product in the catalog
"description": "",
"price": 900,
"quantity": 2,
"subtotal": 1800,
"discount": 0,
"shipping": 0,
"total_before_tax": 1800,
"total_ex_tax": 1800,
"tax": 0,
"total": 1800
},
{
// additional products
}
]
}
}
Make sure to specify either the X-Requested-With
or Accept
request headers to toggle into JSON mode.
Other AJAX Cart actions
The following cart actions are available and require the mentioned data. This should be POST
ed to the page.
- Add product to cart:
add_to_cart=1
+products[123]['quantity']=321
orproduct=123
andquantity=321
. - Remove item:
remove_item=123
where123
is the ID of the order item - Update cart quantities:
update_cart=1
+ objectitems[order_item_id] = quantity
- Continue to the checkout (persist order to database and show account step):
checkout=1