This object represents an option on one of the items in the shopping cart. See item configuration for details on managing items.
Field | Type | Description | Required when adding an item to cart |
name | string | Option name | YES |
selectedValue | string | Seleted value on the option | YES |
| |
costPerLetter costPerLetterLocalized costPerLetterLocalizedFormatted | number number string | Fee per letter specified in a single or multiline option | NO |
costPerLine costPerLineLocalized costPerLineLocalizedFormatted | number | Fee per line of text specified in a multiline option | NO |
costIfSpecified costIfSpecifiedLocalized costIfSpecifiedLocalizedFormatted | number | Fee if specified | NO |
ignoreIfDefault | boolean | True if option will be ignored on the order if the default value is selected | NO |
label | label | Option display label | NO |
oneTimeFee | boolean | True if the fee is only applied once (irregardless of quantity) | NO |
optionOid | integer | A unique option object identifier. This is provided to easy debugging with UltraCart premium support. | NO |
required | boolean | True if required | NO |
type | string | Type of option. See OPTION_TYPE_ constants in the checkoutapi.js for a list of valid values. | NO |
values | CartItemOptionValue[ ] | Values that the customer can select from for radio or drop down style options | NO |
Short Example of creating a CartItem with options:
// create my cart item. just the bare required properties: itemId, quantity.
// see: http://docs.ultracart.com/display/ucdoc/CartItem
var item = {'itemId': myItem.itemId, 'quantity': 1};
item.options = []; // create the (initially empty) options placeholder.
var opt = {'name': 'Option1', 'selectedValue': 'Large'};
item.options.push(opt);
opt = {'name': 'Option2', 'selectedValue': 'Skittles'};
item.options.push(opt);
// add items takes an array. I've only got one item, so I'll surround it by brackets to create a single element array.
ultraCart.addItems([item]);
Full example of downloading an item from the server, creating select boxes for it, and then adding an item with options to a cart:
(You may download this example as a zip file. See this page's attachments.)
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<script type='text/javascript' src='js/jquery-1.7.2.js'></script>
<script type='text/javascript' src='js/jquery.json-2.2.min.js'></script>
<script type='text/javascript' src='js/checkoutapi-2.1.2.js'></script>
<style type='text/css'>
#log{
font-family: Courier, Serif;
font-size: 0.7em;
}
</style>
<script type='text/javascript'>
if (typeof String.prototype.trim === 'undefined') {
String.prototype.trim = function() {
return this.replace(/^\s+|\s+$/g, '');
};
}
var myItem = null; // this will hold a reference to my item after it is loaded.
var merchantCartConfig =
{
merchantId: "DEMO",
isCheckoutPage: false,
checkoutSite: 'secure.ultracart.com',
// remoteApiUrl: 'http://staging.moraicecream.com/wp-content/themes/minimatica/ultracart-scripts/' + 'proxy.php',
remoteApiUrl: location.protocol + "//" + location.hostname + "/proxy.php",
debugMode: true,
verboseAjax: true
};
jQuery(document).ready(function() {
ultraCart.init(merchantCartConfig);
loadShirtOptions();
// ultraCart.clearItems();
// var Options = [
// {name: "Michael Flavor", label: "Michael Label"},
// {name:
// "Michael Flavor", label: "Michael Label"},
// {name: "Michael Flavor", label:
// "Michael Label"},
// {name: "Michael Flavor", label: "Michael Label"}
// ];
// var itemToAdd = {itemId: '001', quantity: 1, options:Options};
// var errors = ultraCart.addItems([itemToAdd]);
// console.log(errors);
// var cart = ultraCart.getCart();
// console.log(jQuery.toJSON(cart.items));
});
function sortOptionValues(a, b) {
// I'm sorting option values on their displayOrder property.
// see: http://docs.ultracart.com/display/ucdoc/ItemOptionValue
return (a.displayOrder - b.displayOrder);
}
function loadShirtOptions() {
var shirt = ultraCart.getItem('TSHIRT', {async:true,onComplete:function(result) {
// when the shirt item returns, load up some options with it.
if (result) {
myItem = result;
log('Loading options for item [' + result.itemId + ']');
// see: http://docs.ultracart.com/display/ucdoc/Item
var shirtOptions = result.options;
if (shirtOptions && shirtOptions.length) {
// loop through each option and create a row in the table containing a drop down box with options
var html = '';
for (var i = 0; i < shirtOptions.length; i++) {
// see: http://docs.ultracart.com/display/ucdoc/ItemOption
var opt = shirtOptions[i];
log(" Loading item option: [" + opt.name + "], label: [" + opt.label + "]");
html += '<tr><td>' + opt.label + '<\/td>';
html += '<td><select class="item_option" name="' + opt.name + '">';
opt.values.sort(sortOptionValues);
for (var j = 0; j < opt.values.length; j++) {
// see: http://docs.ultracart.com/display/ucdoc/ItemOptionValue
var val = opt.values[j];
log(" Loading option value: [" + val.value + "], is default: [" + val.defaultValue + "]");
html += '<option value="' + val.value + '"' + (val.defaultValue ? " selected='selected'" : "") + '>' + val.value + '<\/option>';
}
html += "<\/select>";
html += '<\/td><\/tr>';
} // end of for-each-option-loop
jQuery('#options_table').html(html);
} // end of if-result-has-options
} // end of if-result-is-value
} // end of onComplete
} // end of opts hash
);
}
function addShirt() {
// Pay Attention Here! We're adding to the cart.
// The cart item objects are different from regular items. The regular items are concerned about displaying
// information. The cart item objects are concerned about maintain cart state.
// So we've switched from Item => CartItem.
// ItemOption => CartItemOption
// create my cart item. just the bare required properties: itemId, quantity.
// see: http://docs.ultracart.com/display/ucdoc/CartItem
var item = {'itemId': myItem.itemId, 'quantity': 1};
item.options = []; // create the (initially empty) options placeholder.
// get all the options and add the selected values to my item.
// each select field has a class of 'item_option'. Use that to find them all.
jQuery('.item_option').each(function(idx, el){
// the *only* things we care about with the items are the name and the selected value.
// the server doesn't care about the label, etc.
// step 1. get the name of the element.
// step 2. get the selected value (jQuery makes this easy)
// add the item to the array.
var $el = jQuery(el); // wrap the element in a jQuery object for easy value retrieval.
// see: http://docs.ultracart.com/display/ucdoc/CartItemOption
var opt = {'name': el.name, 'selectedValue': $el.val()};
item.options.push(opt);
});
// add items takes an array. I've only got one item, so I'll surround it by brackets to create a single element array.
ultraCart.addItems([item]);
log("Item was added to the cart.");
log("run this in your browser console: ultraCart.getCart().items");
}
function log(msg) {
jQuery('#log').append(msg).append("<br />");
}
</script>
</head>
<body>
<h4>Add a T-SHIRT to Your Cart</h4>
<table id='options_table'>
<tr>
<td colspan='2'><em>loading options...please wait.</em></td>
</tr>
</table>
<br />
<input type='button' value='Add Shirt' onclick='addShirt()'/>
<div id='log' style='margin-top:20px;'>
<div style='font-weight:bold'>Log Events Will Appear Below:</div>
</div>
</body>
</html>