view_cart.vm

In addition to other standard variables like $cart, StoreFront system screens (display and post form data, such as checkout screens) have a $form variable that contains fields and data specific to that screen.

Listed below are the form fields specific to this screen template.

Form Legend
→ form field
→ submit button

Most of the boolean flags below are dictacted by Merchant Properties. These were seldom used flags created to allow merchants non-standard cart behavior during a time when they had limited control of the web design. With the introduction of the StoreFronts, these properties and flags aren't necessary. Now, if a merchant wishes non-standard cart behavior, he or she may edit the template as desired. The standard themes created by UltraCart will still contain references to these flags and properties to ensure they are backward compatible with long time customers who upgrade from a legacy cart to StoreFronts. If you are designing a new theme for personal use, you may wish to streamline and omit support for these conditionals all together. If you are designing a theme for general use, should you support these flags and merchant properties? Probably not worth the headache.

`$form` variables for template `view_cart.vm`

Name	Type	Formal Syntax	Comments/Sample Usage
`affiliateId`	`string`	`$form.affiliateId`
`allowCustomerSelectableCurrency`	`boolean`	`$form.allowCustomerSelectableCurrency`	same as showChangeCurrency. Use showChangeCurrency instead.
`allowPassingBranding`	`boolean`	`$form.allowPassingBranding`	deprecated. and misspelled too.
`amazonButtonUrl`	`string`	`$form.amazonButtonUrl`
`amazonCheckout`	`string`	`$form.amazonCheckout`	submit button. if non-null, this parameter signals the UltraCart engine that the payment method is Amazon Payments
`amazonMerchantId`	`string`	`$form.amazonMerchantId`	amazon merchant id
`amazonOrderReferenceId`	`string`	`$form.amazonOrderReferenceId`	this is populated by the amazon payments and must be present and valid if `amazonCheckout` is non-null
`amazonUseAddressBook`	`boolean`	`$form.amazonUseAddressBook`	if true, the amazon address book should load and display
`amazonWidgetUrl`	`string`	`$form.amazonWidgetUrl`	script url for the "Pay with Amazon" button. Example: `<script type='text/javascript'` `src='${form.amazonWidgetUrl}?sellerId=${formatHelper.urlEncode($form.amazonMerchantId)}'>` `</script>`
`applyAffiliateId`	`string`	`$form.applyAffiliateId`	submit button. if non-null, instructs the engine to apply a supplied affiliate id
`applyCoupon`	`string`	`$form.applyCoupon`	submit button. if non-null, instructs the engine to apply a coupon
`applyReferralCode`	`string`	`$form.applyReferralCode`	submit button. rarely used. If non-null, instructs the engine to apply a referral code
`buysafeBondAvailable`	`boolean`	`$form.buysafeBondAvailable`	if true, a buysafe bond is available and should be offered.
`buysafeBondChange`	`string`	`$form.buysafeBondChange`	submit button. if non-null, notifies the engine that the customer has selected/de-selected a buysafe bond.
`buysafeBondCost`	`BigDecimal`	`$form.buysafeBondCost`	the cost of the buysafe bond
`buysafeBondFree`	`boolean`	`$form.buysafeBondFree`	if true, the bond is being offered free by the merchant
`buysafeBondWanted`	`boolean`	`$form.buysafeBondWanted`	if true, the customer has indicated that they want the bond. this should be set to true if the customer chooses to opt into a bond
`buysafeBondingSignal`	`string`	`$form.buysafeBondingSignal`	deprecated. use example code provided by stock templates. this html creates the buysafe logo on the checkout, but it is non-responsive and unfit for mobile browsers.
`buysafeCartDisplayText`	`string`	`$form.buysafeCartDisplayText`	deprecated. use example code provided by stock templates.
`buysafeCartDisplayUrl`	`string`	`$form.buysafeCartDisplayUrl`	deprecated. use example code provided by stock templates.
`buysafeRolloverScriptUrl`	`string`	`$form.buysafeRolloverScriptUrl`	deprecated. use example code provided by stock templates.
`buysafeSpacer`	`boolean`	`$form.buysafeSpacer`	deprecated. use example code provided by stock templates.
`cartInNewWindow`	`boolean`	`$form.cartInNewWindow`	This is a rarely used Merchant Property that, when present and true, should render out the ability to close the window. This flag means that the cart was opened in another window already. For example: #if($form.cartInNewWindow) <script type="text/javascript"> function closeWindow() { window.close(); return false; } </script> #end and later in the page: #if($form.cartInNewWindow) <input type="image" name="continueShopping" src="/checkout/images/spacer.gif" border="0" class="ucContinueShoppingButton" id="ucContinueShoppingButtonId" onclick="return closeWindow()"/> #else <input type="image" name="continueShopping" src="/checkout/images/spacer.gif" border="0" class="ucContinueShoppingButton" id="ucContinueShoppingButtonId"/> #end
`changeCurrencyCode`	`string`	`$form.changeCurrencyCode`	submit button. if non-null, the cart engine examines the currencyCode parameter and changes the cart currency to it.
`checkoutInNewWindow`	`boolean`	`$form.checkoutInNewWindow`	if present and true, open the checkout in a new window. This value, rarely used, is a Merchant Property to allow merchants to open the checkout in a new window.
`checkoutUrl`	`string`	`$form.checkoutUrl`	the url of the checkout, if a custom url is used.
`containsPreorderedItems`	`boolean`	`$form.containsPreorderedItems`	if true, one or more items are pre-ordered items. this flag is used to display a pre-order message somewhere prominent on the screen.
`continueShopping`	`string`	`$form.continueShopping`	input submit button. if this is non-null, the shopping experience is redirected back to the catalog page.
`couponCode`	`string`	`$form.couponCode`	a coupon to be added to the cart
`couponInputFieldStr`	`string`	`$form.couponInputFieldStr`	This is static text for creating the "Enter Coupons" label. Over the years, there seems to be a huge amount of customization over the years for coupons. "Enter Coupon" vs. "Enter Coupons" vs. "Enter Coupon Code". So, this field will contain the value from the constant "checkout.viewcart.couponCodeText", "coupon code"
`couponPluralStr`	`string`	`$form.couponPluralStr`	Used to show the total number of coupons. For example, "5 Coupons" would need a plural version of the word 'coupon', whatever language that may be.
`couponSingularStr`	`string`	`$form.couponSingularStr`	Used to show the total number of coupons. For example, "1 Coupon" would need a singular version of the word 'coupon', whatever language that may be.
`coupons`	`Coupon[ ]`	`$form.coupons`
`currencyCode`	`string`	`$form.currencyCode`	The currency or target currency code.
`currencySuffix`	`string`	`$form.currencySuffix`	example: USD
`currencySymbol`	`string`	`$form.currencySymbol`	example: $
`email`	`string`	`$form.email`	the email address of the customer
`errors`	`Error[ ]`	`$form.errors`	see Error, see errors.vm
`finalizeOrder`	`string`	`$form.finalizeOrder`	If true, the checkout is immedatiatly finalized.
`formattedBuysafeBondCost`	`string`	`$form.formattedBuysafeBondCost`	formatted values are a string representation of the decimal value, complete with currency symbol, periods, and commas
`formattedSubtotal`	`string`	`$form.formattedSubtotal`	formatted values are a string representation of the decimal value, complete with currency symbol, periods, and commas
`formattedSubtotalBeforeDiscount`	`string`	`$form.formattedSubtotalBeforeDiscount`	formatted values are a string representation of the decimal value, complete with currency symbol, periods, and commas
`formattedSubtotalDiscount`	`string`	`$form.formattedSubtotalDiscount`	formatted values are a string representation of the decimal value, complete with currency symbol, periods, and commas
`formattedSubtotalFinal`	`string`	`$form.formattedSubtotalFinal`	formatted values are a string representation of the decimal value, complete with currency symbol, periods, and commas
`freePromotion`	`boolean`	`$form.freePromotion`	if true, the free promotional item is added to the cart.
`freePromotionConfirm`	`boolean`	`$form.freePromotionConfirm`	confirmation boolean
`freePromotionHtml`	`string`	`$form.freePromotionHtml`	Some merchants wish to include a free promotional item (configured on the back end). this html presents that offer to the customer.
`hasSubtotalDiscount`	`boolean`	`$form.hasSubtotalDiscount`
`hideQuantity`	`boolean`	`$form.hideQuantity`	if true, do not show quantity
`hideViewUrls`	`boolean`	`$form.hideViewUrls`	if true, do not link the item images to their view urls
`highlightBlankQualifiers`	`boolean`	`$form.highlightBlankQualifiers`	if true, any options that do not yet have a `selectedValue` should be highlighted. What are qualifiers? The original name of options. 20 years is a long, long time.
`hostLinkHtml`	`string`	`$form.hostLinkHtml`
`infoMessages`	`string[ ]`	`$form.infoMessages`	see Message, see info_messages.vm
`items`	`CartItem[ ]`	`$form.items`
`lockQuantity`	`boolean`	`$form.lockQuantity`	if true, do not allow item quantities to be edited
`lockedItems`	`boolean`	`$form.lockedItems`	if true, do not allow any edits on items (no deletions)
`merchantId`	`string`	`$form.merchantId`
`passiveBranding`	`string`	`$form.passiveBranding`	deprecated.
`payPalCheckout`	`string`	`$form.payPalCheckout`	submit button. if true, the cart payment method is PayPal.
`payPalExpressCheckout`	`boolean`	`$form.payPalExpressCheckout`
`paypalCheckoutBml`	`string`	`$form.paypalCheckoutBml`	submit button. if true, the cart payment method is PayPal Bill Me Later.
`proactiveEmailCollection`	`boolean`	`$form.proactiveEmailCollection`
`recalculate`	`string`	`$form.recalculate`	if true, the cart totals and shipping are recalculated
`referralCode`	`string`	`$form.referralCode`
`referralCodeDescription`	`string`	`$form.referralCodeDescription`
`relatedItems`	`RelatedItem[]`	`$form.relatedItems`	Items related to the shopping cart items. These are displayed in a section usually titled "Customer who bought these products also bought these items", etc.
`showAffiliateId`	`boolean`	`$form.showAffiliateId`
`showAmazon`	`boolean`	`$form.showAmazon`
`showChangeCurrency`	`boolean`	`$form.showChangeCurrency`	This is a merchant property. If true, a drop down of currency codes may be displayed allowing the customer to select the checkout currency. The drop down should have the name `currencyCode` (see that property above) This setting is managed on the back end: Home → Configuration → Checkout → Multi-Currency.
`showCouponEntry`	`boolean`	`$form.showCouponEntry`	If true, coupon entry should be displayed. There are numerous settings and properties that could cause this to be false: A Merchant Property that turns off coupons completely. If the cart has a customer profile and that customer profile is set to "no coupons". (Home → Operations → Customer Profiles → Manage → edit a profile) If the cart has a customer profile and that customer profile belongs to a Pricing Tier that is set to "no coupons". (Home → Operations → Customer Profiles → Pricing Tiers)
`showCoupons`	`boolean`	`$form.showCoupons`	if true, show the coupon section. this is true if there are coupons in the cart or if there is an affiliate id associated with the cart. the affiliate id is for legacy reasons. The original cart displayed the affiliate id below the coupon in the same section. So, technically, just because this is true does not mean there are coupons. You should still check to see if the coupons array is non empty. If it's false, then there are no coupons.
`showOptions`	`boolean`	`$form.showOptions`	This is true if any of the items have options, false otherwise. It exists so that a header column or label can be generated for options before looping through the items.
`showPayPal`	`boolean`	`$form.showPayPal`	True if the cart can be paid for by PayPal. To qualify for PayPal, all of the following must be true. The merchant has configured a valid PayPal account. The cart has zero auto order items. The cart has zero pre-order items. The cart subtotal is greater than zero. There is a Merchant Property to force PayPal to never show. That property must not be true.
`showPayPalBml`	`boolean`	`$form.showPayPalBml`	This is true if showPayPal is true, unless the merchant has a Merchant Property set to explictly turn this off.
`showReferralCode`	`boolean`	`$form.showReferralCode`	This is governed by a Merchant Property to collect referral code. Seldom used. If true, the referral code input field should display.
`showShipping`	`boolean`	`$form.showShipping`	If true, the shipping estimate should display. This is true if the cart needs shipping (and a Merchant Property to turn it off is not true) A cart needs shipping if any of the items have a non-zero weight.
`submitCart`	`string`	`$form.submitCart`
`subtotal`	`BigDecimal`	`$form.subtotal`
`subtotalBeforeDiscount`	`BigDecimal`	`$form.subtotalBeforeDiscount`
`subtotalDiscount`	`BigDecimal`	`$form.subtotalDiscount`
`subtotalFinal`	`BigDecimal`	`$form.subtotalFinal`
`useMultipart`	`boolean`	`$form.useMultipart`	if true, the form should have the following attribute: `enctype='multipart/form-data'` to ensure it can handle file uploads. This will be true if any of the cart item options are files. For example, if it stencil item has an option for a pattern pdf that the customer can upload.
`viewUrlsToNewWindow`	`boolean`	`$form.viewUrlsToNewWindow`	if true, any hyperlinks to product pages should open in a new window.

Sample Code

This template is one of the most complex pages in the entire checkout and is constantly being updated in the stock themes. Rather than post stale code here, please see MrTeas, Craft, or Natural for examples.

UltraCart Documentation

view_cart.vm

`$form` variables for template `view_cart.vm`

Sample Code

Flow

$form variables for template view_cart.vm

Sample Code

Flow

`$form` variables for template `view_cart.vm`