ShoppingCart

An e‑commerce shopping cart component that displays a product grid, supports category filtering, shows a floating cart sidebar, and provides a configurable checkout process. Product data is loaded via a query binding with field mappings for title, price, image, categories, and more. The component includes add‑to‑cart, quantity controls, and subtotal calculation.

Use Cases

• Online stores with product browsing and cart
• E‑commerce product catalogs with add‑to‑cart functionality
• Storefront pages with category filtering
• Product listing pages with checkout flow
• Simple shops with floating cart sidebar

Properties

binding

Query binding to load product data from a data source. Type: object.

titleField

Column name for product title/name. Type: string. Required.

priceField

Column name for product price (numeric). Type: string. Required.

imageField

Column name for product image URL. Use search_unsplash to populate with contextual images. Type: string.

descriptionField

Column name for product description text. Type: string.

categoriesField

Column name for available categories (comma‑separated string like 'Electronics,Accessories'). Enables category filter when mapped. Type: string.

installmentsField

Column name for number of installment payments (integer). Shows 'or Nx $X.XX' below price. Type: string.

freeShippingField

Column name for free shipping flag (boolean). Shows 'Free shipping' badge on product card. Type: string.

currencySymbol

Currency symbol displayed before prices. Type: string. Default: $

currencyId

Currency ID for number formatting (locale‑aware decimal separators). Type: string. Options: USD, EUR, GBP, BRL, CAD, AUD. Default: USD

columns

Number of columns in product grid. 2=detailed, 3=balanced, 4=compact. Type: number. Options: 2, 3, 4. Default: 4

cartPosition

Position of the floating cart sidebar. Type: string. Options: right, left. Default: right

enableCategoryFilter

Show category filter pills above product grid. Requires categoriesField to be mapped. Type: boolean. Default: true

enableInstallments

Show installment pricing below product price. Requires installmentsField to be mapped. Type: boolean. Default: true

enableFreeShippingBadge

Show 'Free shipping' badge on products. Requires freeShippingField to be mapped. Type: boolean. Default: true

enableOrderNotification

Send order summary email to app owner when checkout completes. Type: boolean. Default: true

enableCustomerEmail

Send order confirmation email to the customer who placed the order. Requires customer to be logged in with an email address. Type: boolean. Default: true

checkoutAction

Action when checkout button is clicked. 'url'=navigate, 'alert'=show summary, 'script'=run JavaScript. Type: string. Options: url, alert, script. Default: alert

checkoutUrl

URL to navigate to on checkout (only used when checkoutAction='url'). Type: string.

checkoutScript

JavaScript executed on checkout (only used when checkoutAction='script'). context.cart contains { items, total }. context.currentUser contains { id, email, displayName, roles } if logged in (null if not). ALWAYS guard: if (!context.currentUser) { await context.alert('Please log in', 'Login Required', 'warning'); context.navigate('login'); return; }. save() returns the new record ID. Type: string.

primaryColor

Cart sidebar background color and Add to Cart button color. Type: string. Default: #1b1a20

accentColor

Accent color for cart badge, prices in cart, and free shipping badge. Type: string. Default: #eabf00

cartButtonColor

Floating cart button background color. Type: string. Default: #1b1a20

customCss

Custom CSS styles for the shopping cart container. Type: string.

Best Practices

• Always configure binding with a query that returns product data
• Map titleField and priceField at minimum - these are required for the cart to work
• Map imageField for visual product cards (use search_unsplash to populate image_url column)
• Map categoriesField if products have categories (comma-separated values like 'Electronics,Accessories')
• Set columns=4 for compact product grids, columns=3 for balanced, columns=2 for detailed
• Use checkoutAction='script' with context.cart for custom checkout logic
• Set enableCategoryFilter=false if products don’t have categories
• Use enableFreeShippingBadge=true with a boolean free_shipping column for badges
• Use context.currentUser in checkout scripts to associate orders with the logged‑in user (e.g., context.currentUser.id, context.currentUser.email)
• Use the return value of save() to get the new record ID for creating child records (e.g., const orderId = await context.orders.save())
• Cart state persists across page navigation via sessionStorage - cleared automatically after successful checkout
• Set enableOrderNotification=true to email the app owner a summary when orders are placed
• Set enableCustomerEmail=true to send order confirmation to the customer (requires authentication)
• For 'My Orders' pages, use query filter with template variable: { field: 'user_id', operator: 'eq', value: '{{currentUser.id}}' }

Common Mistakes

Not mapping titleField and priceField

Why it's a problem: These are required for the cart to display products and calculate totals.

Fix: Always set titleField and priceField to match your data source columns.

Enabling category filter without mapping categoriesField

Why it's a problem: Category filter needs a column with comma-separated categories to extract filter options.

Fix: Either map categoriesField to a column like 'available_categories' or set enableCategoryFilter=false.

Using ShoppingCart for admin product management

Why it's a problem: ShoppingCart is a customer‑facing browsing/purchasing component, not an admin tool.

Fix: Use DataGrid with enableCrudActions=true for admin product management.

Not creating a products data table with appropriate columns

Why it's a problem: ShoppingCart requires a data source with at least title and price columns.

Fix: Create a products table with columns: title, price, image_url, available_categories, free_shipping, etc.

Checkout script references data sources (orders, order_items) not added as queries on the cart page

Why it's a problem: context.orders.createNew() fails with 'Cannot read properties of undefined' because 'orders' query doesn’t exist on this page. Script context only includes queries from the CURRENT page.

Fix: Add addQuery() calls for EVERY data source referenced in checkoutScript. If script uses context.orders and context.order_items, add: page.addQuery('orders', ordersTable.dataSourceId, { operation: 'create' }) and page.addQuery('order_items', orderItemsTable.dataSourceId, { operation: 'create' }) on the cart page.