@zohofinance/commerce 1.0.0 → 1.1.0

package/ts-dist/mocks/init-theme/.claude/skills/theme-from-figma/zcommerce-docs/reference/global-objects.md

@@ -0,0 +1,415 @@
+---
+title: "Global Objects"
+weight: 14
+---
+
+# Global Objects
+
+Global objects are variables available in every template without needing to be passed or assigned. They provide access to store data, request context, and platform information.
+
+---
+
+## Store Objects
+
+### store
+
+The current store. Available on every page.
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `store.name` | string | Store display name |
+| `store.tag_line` | string | Store tagline |
+| `store.email` | string | Contact email |
+| `store.phone` | string | Contact phone number |
+| `store.logo` | object | Store logo; use `store.logo.url` |
+| `store.favicon` | object | Store favicon; use `store.favicon.url` |
+| `store.social_profiles` | array | Social links: `{ name, link }` |
+| `store.social_preview` | object | Open Graph preview; use `store.social_preview.url` |
+| `store.customer_portal.enabled` | boolean | Whether customer accounts are enabled |
+| `store.customer_portal.signin_url` | string | URL to the sign-in page |
+| `store.breadcrumb.enabled` | boolean | Whether breadcrumb navigation is enabled |
+| `store.breadcrumb.level` | number | Breadcrumb depth |
+| `store.preferences` | object | Feature flags (e.g. `is_menu_enabled`, `is_footer_enabled`, `search_box_enabled`, wishlist, save-for-later, customer sign-up) |
+
+Individual preference keys follow the platform configuration in your store.
+
+**Removed (not exposed in Liquid):** `organizationID`, `current_user`. To read the signed-in customer in client-side code, use `GET /portal/user` instead of a Liquid global.
+
+```liquid
+<title>{{ page_title }} | {{ store.name }}</title>
+<img src="{{ store.logo.url }}" alt="{{ store.name }}">
+
+{% if analytics.webmaster_meta_tag != '' %}
+  <meta name="google-site-verification" content="{{ analytics.webmaster_meta_tag }}">
+{% endif %}
+
+<link rel="shortcut icon" href="{{ store.favicon.url }}">
+
+{% if store.customer_portal.enabled %}
+  <a href="{{ store.customer_portal.signin_url }}">Sign In</a>
+{% endif %}
+```
+
+---
+
+### analytics
+
+Site verification and analytics identifiers (split out from the old `organization` object).
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `analytics.webmaster_meta_tag` | string | Google site verification meta content |
+| `analytics.google_analytics_container_id` | string | Google Analytics / GTM container ID |
+
+---
+
+### seo
+
+SEO copy for the current page, provided as a top-level global on the storefront response. Use `seo.description` and `seo.keywords` in `<head>` when your theme should emit description and keywords meta tags. For checking non-empty values, filters like `escape`, and general layout usage, follow the same patterns as **`store`** and **`analytics`** above.
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `seo.description` | string | Meta description for the page (may be empty) |
+| `seo.keywords` | string | Meta keywords for the page (may be empty) |
+
+---
+
+### currency
+
+Global currency information. Use this instead of any former `cart.currency` field.
+
+---
+
+### product
+
+The current product (available on product pages).
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `product.id` | string | Product ID |
+| `product.title` | string | Product name |
+| `product.description` | string | HTML description |
+| `product.short_description` | string | Short plain-text or HTML summary |
+| `product.price` | number | Current price (in cents) |
+| `product.on_sale` | boolean | Whether the product is on sale |
+| `product.price_min_formatted` / `price_max_formatted` | string | Formatted price range |
+| `product.available` | boolean | Whether the product is purchasable |
+| `product.url` | string | Relative URL |
+| `product.cover_media` | object | Primary image / media |
+| `product.images` | array | All product images |
+| `product.variants` | array | Product variants |
+| `product.attribute_names` | array | Attribute names (e.g. Size, Color) |
+| `product.options` | array | `ProductOption` objects: `name`, `values`, `selected_value` |
+| `product.initial_variant` | object | Selected variant, or default first available |
+| `product.updated_at` | string | Last update timestamp |
+| `product.average_rating` | number | Average review score (see note below) |
+| `product.review_count` | number | Number of reviews (see note below) |
+| `product.specification_group` | array | Specification groups |
+| `product.custom_fields` | array | Custom field definitions |
+| `product.compare_at_price` | number | Original price before discount |
+| `product.created_at` | string | Creation timestamp |
+
+`average_rating` and `review_count` are set on collection, category, search, and recommendations pages; they are `0` elsewhere.
+
+```liquid
+<h1>{{ product.title }}</h1>
+<p>{{ product.price }}</p>
+
+{% if product.on_sale %}
+  <span class="sale">{{ "product.on_sale_label" | t }}</span>
+{% endif %}
+
+{% for image in product.images %}
+  <img src="{{ image | image_url }}" alt="{{ product.title }}">
+{% endfor %}
+
+{% for option in product.options %}
+  <label>{{ option.name }}</label>
+  <span>{{ option.selected_value }}</span>
+{% endfor %}
+```
+
+---
+
+### collection
+
+The current collection (available on collection pages).
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `collection.id` | string | Collection ID |
+| `collection.title` | string | Collection name |
+| `collection.description` | string | HTML description |
+| `collection.url` | string | Relative URL |
+| `collection.products` | array | Products in this collection |
+| `collection.products_count` | number | Total product count |
+| `collection.last_modified_time` | string | Last modification time |
+| `collection.page_context` | object | Pagination / listing context (replaces `collection.paginate`) |
+
+**Removed — not exposed:** includes `sort_by`, `image`, `featured_image`, `tags`, `all_tags`, `all_types`, `all_vendors`, `template_suffix`, and others not listed above.
+
+```liquid
+<h1>{{ collection.title }}</h1>
+<p>{{ collection.products_count }} products</p>
+
+{% for product in collection.products %}
+  {% render 'product-card', product: product %}
+{% endfor %}
+```
+
+---
+
+### cart
+
+The current customer's shopping cart.
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `cart.items` | array | Line items in the cart |
+| `cart.item_count` | number | Total number of items |
+| `cart.total_price` | number | Cart total (in cents) |
+| `cart.items_subtotal_price_formatted` | string | Subtotal, formatted |
+| `cart.total_discount_formatted` | string | Total discount, formatted |
+| `cart.total_price_formatted` | string | Total price, formatted |
+
+Test for an empty cart with `cart.item_count == 0`. Use the global **`currency`** object for currency display, not a property on `cart`.
+
+**Removed — not exposed:** includes `cart_level_discount_applications`, `discount_applications`, `checkout_charge_amount`, `note`, `original_total_price`, `requires_shipping`, `taxes_included`, `tax_total`, `total_weight`, and discount/tax line objects (`DiscountApplication`, `TaxLine`, etc.).
+
+#### Cart line items (`cart.items[]`)
+
+| Property | Description |
+|----------|-------------|
+| `item.id` | Line item ID |
+| `item.product` | Full product object |
+| `item.product.title` | Product title |
+| `item.selected_variant` | Chosen variant |
+| `item.selected_variant.cover_media` | Line image |
+| `item.selected_variant.sku` | SKU |
+| `item.item_total` / `item.item_total_formatted` | Line total |
+| `item.rate` / `item.rate_formatted` | Unit price |
+| `item.label_rate` / `item.label_rate_formatted` | List / label price |
+| `item.discount_total_formatted` | Discount on the line |
+| `item.item_custom_fields` | Custom fields |
+
+```liquid
+{% if cart.item_count > 0 %}
+  <span class="cart-badge">{{ cart.item_count }}</span>
+{% endif %}
+
+{% for item in cart.items %}
+  <div class="cart-item">
+    <span>{{ item.product.title }}</span>
+    <span>{{ item.rate }} × {{ item.quantity }}</span>
+  </div>
+{% endfor %}
+
+<strong>Total: {{ cart.total_price_formatted }}</strong>
+```
+
+---
+
+### save_for_later
+
+Saved items use the same line-item shape as `cart.items`: `item.id`, `item.product`, `item.selected_variant`, etc.
+
+---
+
+### customer
+
+The logged-in customer (nil if not logged in).
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `customer.id` | string | Customer ID |
+| `customer.first_name` | string | First name |
+| `customer.last_name` | string | Last name |
+| `customer.email` | string | Email address |
+| `customer.orders` | array | Order history |
+| `customer.addresses` | array | Saved addresses |
+| `customer.default_address` | object | Primary address |
+
+```liquid
+{% if customer %}
+  <span>Welcome, {{ customer.first_name }}</span>
+{% else %}
+  <a href="{{ routes.signin_url }}">Sign In</a>
+{% endif %}
+```
+
+---
+
+## Page Context Objects
+
+### page_title
+
+The title of the current page, set automatically based on page type:
+
+```liquid
+<title>{{ page_title }} | {{ store.name }}</title>
+```
+
+### request
+
+Information about the current HTTP request:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `request.path` | string | Current URL path |
+| `request.host` | string | Hostname |
+
+```liquid
+<link rel="canonical" href="{{ request.host }}{{ request.path }}">
+```
+
+---
+
+### menu
+
+The store’s default navigation menu. Top-level entries are `menu.menu_items`; nested items use `child_items`. Each item follows `{ id, name, url, child_items, resource }`.
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `menu.menu_items` | array | Top-level navigation items |
+
+```liquid
+{% for item in menu.menu_items %}
+  <a href="{{ item.url }}">{{ item.name }}</a>
+  {% for child in item.child_items %}
+    <a href="{{ child.url }}">{{ child.name }}</a>
+  {% endfor %}
+{% endfor %}
+```
+
+---
+
+### page_info
+
+Information about the current page context. Useful for building URLs in client-side scripts.
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `page_info.origin` | string | The base origin URL (e.g. `https://yourstore.com`) |
+
+```liquid
+{% assign search_url = page_info.origin %}
+```
+
+---
+
+### routes
+
+Platform-provided URL routes for dynamic features.
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `routes.predictive_search_url` | string | Predictive search API |
+| `routes.cart_api_url` | string | Cart API |
+| `routes.checkout_coupons_api_url` | string | Checkout coupons API |
+| `routes.quote_api_url` | string | Quote API |
+| `routes.quotes_list_api_url` | string | Quotes list API |
+| `routes.quote_request_api_url_prefix` | string | Prefix for quote request API |
+| `routes.quote_detail_api_url_prefix` | string | Prefix for quote detail API |
+| `routes.signin_url` | string | Sign-in page |
+| `routes.signup_url` | string | Sign-up page |
+| `routes.forgotpassword_url` | string | Forgot password page |
+| `routes.product_recommendations_url_suffix` | string | Suffix for product recommendations URL (see below) |
+| `routes.product_reviews_url_suffix` | string | Suffix for product reviews URL (see below) |
+
+**Recommended products** — `product.recommended_products` is not available in Liquid. Build the URL and call the API from JavaScript:
+
+```liquid
+{% assign reco_url = product.id | prepend: '/products/' | append: routes.product_recommendations_url_suffix %}
+```
+
+`GET /products/{id}/recommendations` returns `{ recommendations: [...], sections: {...} }`.
+
+**Product reviews** — reviews API path changed from `/reviews/{id}` to `/products/{id}/reviews`. Replace `routes.reviews_api_url_prefix` with `routes.product_reviews_url_suffix`:
+
+```liquid
+{% assign reviews_url = product.id | prepend: '/products/' | append: routes.product_reviews_url_suffix %}
+```
+
+```liquid
+{% assign route_url = routes.predictive_search_url %}
+```
+
+---
+
+## Section Objects
+
+### section
+
+Available inside section templates. Provides access to the section's settings and blocks.
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `section.settings` | object | The section's current setting values |
+| `section.blocks` | array | The section's block instances |
+| `section.id` | string | Unique section ID |
+
+```liquid
+<h2>{{ section.settings.title }}</h2>
+
+{% for block in section.blocks %}
+  {{ block.settings.text }}
+{% endfor %}
+```
+
+### block
+
+Available inside a block loop. Represents a single block instance.
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `block.type` | string | Block type identifier |
+| `block.settings` | object | Block setting values |
+| `block.zcommerce_attributes` | string | Required attributes for editor interaction |
+
+```liquid
+{% for block in section.blocks %}
+  <div {{ block.zcommerce_attributes }}>
+    {{ block.settings.heading }}
+  </div>
+{% endfor %}
+```
+
+---
+
+## Layout Variables
+
+These are used exclusively in layout files (`theme.liquid`, `accounts.liquid`):
+
+| Variable | Placement | Description |
+|----------|-----------|-------------|
+| `content_for_header` | Inside `<head>` | Server-injected platform scripts, meta tags, stylesheets, and analytics (from Zoho Commerce admin) |
+| `content_for_layout` | Inside `<body>` | Page-specific content |
+| `content_for_footer` | Before `</body>` | Post-DOM scripts |
+
+> **Note:** `content_for_header` outputs markup and scripts that the server injects based on your Zoho Commerce admin configuration. That includes standard head content and **analytics scripts** when tracking is enabled for the store. You do **not** need any separate analytics wiring in the theme—place `{{ content_for_header }}` once in your layout `<head>` and the platform applies analytics for you alongside other meta and scripts.
+
+See [Layouts](../layouts) for usage examples.
+
+---
+
+## Variant objects
+
+When iterating `product.variants` or using `product.initial_variant`:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `variant.cover_media` | object | Primary image for the variant |
+| `variant.available_stock` | number | Available quantity |
+| `variant.options` | array | Option values by position: `options[0]`, `options[1]`, `options[2]` |
+| `variant.sku` | string | SKU |
+| `variant.price_formatted` | string | Current price, formatted |
+| `variant.label_price_formatted` | string | List / label price, formatted |
+| `variant.discount_total_formatted` | string | Discount amount, formatted |
+| `variant.product_id` | string | Parent product ID |
+| `variant.custom_fields` | array | Custom fields |
+
+Use **`product.options`** for option pickers — `options_with_values` is not available on variants.
+
+**Removed — no replacement:** `compare_at_price` on variants.
+
+**Removed — not exposed:** includes `barcode`, `inventory_quantity`, `unit_price_measurement`, `store_availabilities`, `quantity_price_breaks`, `quantity_rule`, and other fields not listed above.