This object represents an option on one of the items in the shopping cart. See item configuration for details on managing items.
Local currency fields are only available to the REST API. |
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> |