ShoppingLists

Purpose

ShoppingLists is the reusable that manages shopping-list collection views and list-level actions.

It supports list retrieval, CRUD workflows, and import/export behavior for saved shopping lists.

Where it's rendered

In Components/Profile/Default.liquid:

{% render 'Reusables\\ShoppingLists\\Default', shoppingLists: shoppingLists %}

Inputs (Liquid render parameters)

Liquid parameters

shoppingLists (array)

The initial shopping lists data used to render the list view.

Passed into the JS via shoppinglistsreusabledefault.initComponent(...).

Model shape (storefront example)

Sanitized real storefront example (provided by the user). Only the fields relevant to this reusable are kept.

[
  {
    "id": "Shopping List Id",
    "title": "Sample text",
    "alias": "sample",
    "items": [
      {
        "productId": "Product Id",
        "productVariantId": "Product Variant Id",
        "quantity": 1,
        "product": {
          "id": "Product Id",
          "title": "Sample text",
          "alias": "sample",
          "link": "product/sample",
          "mediaItems": [
            {
              "id": "Media Id",
              "link": "https://example.com/sample",
              "position": 0,
              "alt": "Sample text",
              "mediaType": "Image"
            },
            ...
          ],
          "productVariants": [
            {
              "id": "Product Variant Id",
              "quantityConstraints": {
                "additive": {
                  "minimum": 1,
                  "maximum": 999999,
                  "step": 1,
                  "isValid": true
                },
                "absolute": {
                  "minimum": 1,
                  "maximum": 999999,
                  "step": 1,
                  "isValid": true
                }
              },
              "dimension1ItemId": "Dimension Item Id",
              "dimension2ItemId": "Dimension Item Id",
              "sku": "Sample text",
              "canOrder": true,
              "sellOutOfStock": true,
              "startQuantity": 1
            },
            ...
          ],
          "dimension1": {
            "id": "Dimension Id",
            "name": "Sample text",
            "type": "Color",
            "items": [
              {
                "id": "Dimension Item Id",
                "value": "Sample text",
                "textColor": "#000000"
              },
              ...
            ]
          },
          "dimension2": {
            "id": "Dimension Id",
            "name": "Sample text",
            "type": "Size",
            "items": [
              {
                "id": "Dimension Item Id",
                "value": "Sample text"
              },
              ...
            ]
          }
        }
      },
      ...
    ]
  },
  ...
]

Required fields

Per shopping list:

id

title

alias

items[]

Per item:

productId

productVariantId

quantity

product

id, title, alias

mediaItems[] (optional but used for previews)

productVariants[] (used for mapping dimensions/variant data)

Optional fields

The implementation reads many product fields when available (categories, tags, labels, attributes, etc.) but the core UI only requires variant media + title/alias and variant dimension ids.

Template behavior (Liquid + Alpine)

Feature flag

Rendered only when:

GlobalData.Settings.EnableShoppingLists is truthy.

Alpine wiring

The root wrapper mounts:

x-data='shoppinglistsreusabledefault.initComponent(shoppingLists, translationErrors)'

Where:

shoppingLists is the Liquid parameter

translationErrors is a JSON string built from Reusables.ShoppingLists.Translations.*

Two main views

Lists overview (selectedShoppingListIndex == null)

Shows list cards with title, preview images (up to 3), and actions.

Supports:

create new list (opens PromptModal)

view list

import/export

rename (inline)

delete (confirmation modal)

add items to cart

List details (selectedShoppingListIndex != null)

Shows:

rename toolbar

import/export actions

item selection (select all / per item)

quantity controls (increase/decrease/input)

delete selected items (confirmation modal)

add selected to cart

PromptModal usage

The template itself doesn’t mount the PromptModal; instead it opens it through $store.modal.open(...) and relies on:

promptmodalreusabledefault.isDataValid(modalData)

for validation of modal inputs.

Data contract (JS runtime)

Document runtime state shape, factories, and main state fields.

JavaScript

Global object

Global object: shoppinglistsreusabledefault (in Reusables/ShoppingLists/Default.js).

Factory:

initComponent(shoppingLists, translationErrors)

State (returned object)

Core state:

shoppingLists

selectedShoppingListIndex, selectedShoppingList

isLoadingLists, isShoppingListChanging, isUpdating

openPopup (per-list actions popover)

rename state:

isRenaming[]

originalTitles[]

draftTitles[]

delete state:

pendingDeleteIndex

debouncing/cancellation:

debounceMap

cancelTokenMap

Methods (nested inside initComponent)

init()

If URL path contains /shoppingLists/{alias}, auto-opens the matching shopping list.

If alias doesn’t exist, resets URL path.

init

Alpine lifecycle method that reads the URL (optional alias) and sets the initial view (overview vs a specific list).

getImage(item)

Returns { link, alt } using variant media first, then product media.

sendSelectEvent(product, listName, position)

Sends GA event selectItem using prepareListProducts(...).

setUrlPath(alias)

Updates the current URL path to either:

/.../shoppingLists (no alias)

/.../shoppingLists/{alias}

getDimension(item, dimensionName)

Resolves display name/value for a dimension (e.g. dimension1, dimension2) by:

finding the variant

reading variant.dimension1ItemId / variant.dimension2ItemId

mapping to product.dimensionX.items[]

getVariant(item, variantId)

Returns the matching product variant by id.

isOutOfStock

isOutOfStock(item) returns true when the item's variant is missing or its quantityConstraints.additive.isValid is false.

isNotifyState

isNotifyState(item) returns true when Stock Alerts is active and the item's variant exists but is out of stock. The template then shows the shared Reusables/ProductAvailabilityAction "Notify me" button instead of the quantity stepper/add-to-cart button.

hydrateItemsConstraints

hydrateItemsConstraints(items = []) hydrates personalized quantity constraints for the products of the opened list via servicesreusabledefault.hydrateProductConstraints(product), so the notify/cart decision reflects real per-visitor stock.

Runs only when Stock Alerts is active.

Skips items without a product or without variants.

hydrateItemsPrices

hydrateItemsPrices(items = []) replaces Shopranos prices with ERP prices for products flagged pricePending, via servicesreusabledefault.hydrateProductPrices(product).

Dedupes products (they are shared across lists), so each is priced once; the service batches them into one request.

Clears pricePending per product, and logs a console error on failure.

Both hydration methods run when a shopping list is opened.

selectAllItems() / deselectAllItems()

Toggles item.selected for all items in selectedShoppingList.

selectAllItems

deselectAllItems

viewShoppingLists

selectItem(item) / deselectItem(item)

Toggles selection on a single item.

createNewShoppingList(modalTranslations)

Opens PromptModal for a required newShoppingList input.

Uses promptmodalreusabledefault.isDataValid(modalData).

Blocks duplicate list names client-side.

Calls servicesreusabledefault.createShoppingList({ title }).

Refreshes via Alpine.store('shoppingLists').fetch() and replaces local shoppingLists.

viewShoppingList(index) / viewShoppingLists()

Switches between overview and list details.

Clones items to avoid mutating the original reference.

openRenameShoppingList(index)

Enters rename mode for a list.

Snapshots original title and draft title.

saveRenaming(modalTranslations, index)

Validates empty name and duplicates.

Calls servicesreusabledefault.updateShoppingList(list).

On success, updates both local shoppingLists and the global Alpine.store('shoppingLists').list.

cancelRenaming(clearToasts)

Clears toast messages (optional).

Reverts drafts to originals and exits rename mode.

confirmShoppingListDeletion(alias, modalTranslations)

Opens a confirmation modal.

On confirm, calls deleteShoppingList(...).

deleteShoppingList(alias, deleteErrorMessage)

Calls servicesreusabledefault.deleteShoppingList(alias).

On success, refreshes via Alpine.store('shoppingLists').fetch().

addItemToCart(...)

Calls servicesreusabledefault.addToCart(...).

Handles response.data.lineFailures[] by mapping error types to translated messages.

addSelectedItemsToCart(items, errorMessages, selectAllItems)

Calls servicesreusabledefault.addMultipleToCart(variations).

Handles lineFailures similarly to single add.

getLineFailureMessages(lineFailure, errorMessages, selectedProductTitle)

Maps server error types to UI messages.

Ensures messages are unique.

deleteItemFromShoppingList(itemIndex, deleteItemErrorMessage)

Removes a single item by index and updates the shopping list via updateShoppingList service call.

handleClearShoppingList(modalTranslations, items)

Opens confirmation modal to clear selected items.

deleteSelectedItemsFromShoppingList(items, deleteErrorMessage)

Removes selected items, sends servicesreusabledefault.updateShoppingList(...), and syncs local + global state.

debounceUpdate(item, delay)

Debounces server update per item id.

Cancels any pending axios request (via stored cancel token).

updateShoppingList(item, useDebounce)

Updates the current shopping list on the server via servicesreusabledefault.updateShoppingList(this.selectedShoppingList).

On success, syncs shoppingLists[listIndex].items to Alpine.store('shoppingLists').list.

increaseQuantity(item, variant) / decreaseQuantity(item, variant) / updateItemQuantity(newQuantity, item, variant)

Updates quantities and calls updateShoppingList(..., true) (debounced).

handleImportShoppingList(alias, modalTranslations, template)

Opens PromptModal with a required file input.

On confirm, reads file from #importFile and calls importShoppingList(alias, file).

importShoppingList(alias, file)

Calls servicesreusabledefault.importShoppingList(alias, file).

Refreshes shopping lists via the global store.

exportShoppingList(alias)

Calls servicesreusabledefault.exportShoppingList(alias).

Global Alpine stores

This reusable uses:

$store.shoppingLists

list

fetch()

$store.modal

open(...)

close()

$store.toast

removeAll()

add(...)

Services / API calls

This reusable calls (via servicesreusabledefault):

createShoppingList({ title })

updateShoppingList(list)

deleteShoppingList(alias)

addToCart(productId, variantId, quantity, finalPrice, originalPrice, showToast)

addMultipleToCart(variations)

importShoppingList(alias, file)

exportShoppingList(alias)

Dependencies

Liquid: Reusables/ShoppingLists/Default.liquid

JS: Reusables/ShoppingLists/Default.js

Translations: Reusables/ShoppingLists/Default.json

Render sites:

Components/Profile/Default.liquid

Reusable dependency:

Reusables/PromptModal/Default.* (via $store.modal + promptmodalreusabledefault.isDataValid)

Notes

The local shoppingLists array is kept in sync with Alpine.store('shoppingLists').list after create/update/delete/import.

The code excludes the pseudo-list entry ("save to different list") by slicing to slice(0, -1) after fetching.

Quantity updates are debounced and can cancel previous requests; this avoids spamming the server when users type quickly.

ShoppingLists

Purpose#

Where it's rendered#

Inputs (Liquid render parameters)#

Liquid parameters#

Model shape (storefront example)#

Required fields#

Optional fields#

Template behavior (Liquid + Alpine)#

Feature flag#

Alpine wiring#

Two main views#

PromptModal usage#

Data contract (JS runtime)#

JavaScript#

Global object#

State (returned object)#

Methods (nested inside initComponent)#

init()#

init#

getImage(item)#

sendSelectEvent(product, listName, position)#

setUrlPath(alias)#

getDimension(item, dimensionName)#

getVariant(item, variantId)#

isOutOfStock#

isNotifyState#

hydrateItemsConstraints#

hydrateItemsPrices#

selectAllItems() / deselectAllItems()#

selectAllItems#

deselectAllItems#

viewShoppingLists#

selectItem(item) / deselectItem(item)#

createNewShoppingList(modalTranslations)#

viewShoppingList(index) / viewShoppingLists()#

openRenameShoppingList(index)#

saveRenaming(modalTranslations, index)#

cancelRenaming(clearToasts)#

confirmShoppingListDeletion(alias, modalTranslations)#

deleteShoppingList(alias, deleteErrorMessage)#

addItemToCart(...)#

addSelectedItemsToCart(items, errorMessages, selectAllItems)#

getLineFailureMessages(lineFailure, errorMessages, selectedProductTitle)#

deleteItemFromShoppingList(itemIndex, deleteItemErrorMessage)#

handleClearShoppingList(modalTranslations, items)#

deleteSelectedItemsFromShoppingList(items, deleteErrorMessage)#

debounceUpdate(item, delay)#

updateShoppingList(item, useDebounce)#

increaseQuantity(item, variant) / decreaseQuantity(item, variant) / updateItemQuantity(newQuantity, item, variant)#

handleImportShoppingList(alias, modalTranslations, template)#

importShoppingList(alias, file)#

exportShoppingList(alias)#

Global Alpine stores#

Services / API calls#

Dependencies#

Notes#