Skip to content

armgit / spree

Public Imported from GitHub
0

Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.

Improve storefront helper methods documentation

Damian Legawiec7ee364f627d8
diff --git a/docs/developer/storefront/helper-methods.mdx b/docs/developer/storefront/helper-methods.mdx
index bcec1d6c93..f8af65e868 100644
--- a/docs/developer/storefront/helper-methods.mdx
+++ b/docs/developer/storefront/helper-methods.mdx
@@ -3,6 +3,11 @@ title: Storefront Helper Methods
sidebarTitle: Helper Methods
---
+import SpreeTheme from '/snippets/objects/spree_theme.mdx'
+import SpreeOrder from '/snippets/objects/spree_order.mdx'
+import SpreeStore from '/snippets/objects/spree_store.mdx'
+import SpreeUser from '/snippets/objects/spree_user.mdx'
+
Here you can find a list of helper methods provided by Spree that are available in the Storefront that you can use in every template.
<Warning>
@@ -23,14 +28,46 @@ will return
USD
```
-## `current_store`
+## `current_locale`
-Returns the current store [Spree::Store](https://github.com/spree/spree/blob/master/core/app/models/spree/store.rb) instance.
+Returns the currently selected locale. By default in the Storefront this will be `store.default_locale`. This can be changed in the `Settings -> Store Defaults` page. If there are multiple locales available, it will return the locale that is currently selected by the user.
```erb
-<%= current_store.name %>
+<%= current_locale %>
```
+<Info>
+ Locale also affects the storefront URLs. For example, if the default locale is `en` and the user selects `fr`, the URL will be `/fr/products/123`.
+</Info>
+
+## `current_order`
+
+<ResponseField name="current_order" type="Spree::Order" description="The current order object.">
+ <SpreeOrder />
+</ResponseField>
+
+Returns the current order object. If no order is found, it will return `nil`.
+
+<Tip>
+ Order is automatically created when a user adds a product to the cart.
+</Tip>
+
+## `current_store`
+
+<ResponseField name="current_store" type="Spree::Store" description="The current store object.">
+ <SpreeStore />
+</ResponseField>
+
+Returns the current store [Spree::Store](https://github.com/spree/spree/blob/master/core/app/models/spree/store.rb) instance.
+
+## `current_theme`
+
+<ResponseField name="current_theme" type="Spree::Theme" description="The current theme object.">
+ <SpreeTheme />
+</ResponseField>
+
+Returns the current theme [Spree::Theme](https://github.com/spree/spree/blob/master/core/app/models/spree/theme.rb) instance.
+
## `local_time`
Displays a time in the user's timezone in a human readable format (based on the browser's timezone).
@@ -57,14 +94,16 @@ will return
## `try_spree_current_user`
-Returns the current user object (class depends on the `Spree.admin_user_class` configuration). If the user is not signed in, it will return `nil`.
+<ResponseField name="try_spree_current_user" type="Spree.user_class" description="The current user object.">
+ <SpreeUser />
+</ResponseField>
-```erb
-<%= try_spree_current_user.email %>
-```
+Returns the current user object (class depends on the `Spree.admin_user_class` configuration). If the user is not signed in, it will return `nil`.
-If you want to check if the user is signed in, you can use the following:
+<Tip>
+ If you want to check if the user is signed in, you can use the following:
-```erb
-<%= try_spree_current_user.present? %>
-```
+ ```erb
+ <%= try_spree_current_user.present? %>
+ ```
+</Tip>
\ No newline at end of file
diff --git a/docs/snippets/objects/spree_address.mdx b/docs/snippets/objects/spree_address.mdx
new file mode 100644
index 0000000000..4a68236898
--- /dev/null
+++ b/docs/snippets/objects/spree_address.mdx
@@ -0,0 +1,59 @@
+import SpreeState from '/snippets/objects/spree_state.mdx';
+import SpreeCountry from '/snippets/objects/spree_country.mdx';
+
+<Expandable title="properties">
+ <ResponseField name="id" type="integer">
+ Address ID
+ Example: 456
+ </ResponseField>
+
+ <ResponseField name="address1" type="string">
+ Address line 1
+ Example: `123 Main St`
+ </ResponseField>
+
+ <ResponseField name="address2" type="string">
+ Address line 2
+ Example: `Apt 1`
+ </ResponseField>
+
+ <ResponseField name="city" type="string">
+ City
+ Example: `Anytown`
+ </ResponseField>
+
+ <ResponseField name="zipcode" type="string">
+ Zipcode
+ Example: `12345`
+ </ResponseField>
+
+ <ResponseField name="state" type="Spree::State">
+ State object, if the country requires a state.
+ <SpreeState />
+ </ResponseField>
+
+ <ResponseField name="state_name" type="string">
+ State name, used when the country doesn't require a state object
+ Example: `Some Province`
+ </ResponseField>
+
+ <ResponseField name="state_text" type="string">
+ Returns either state.name (if state is present) or state_name
+ Example: `California` or `Some Province`
+ </ResponseField>
+
+ <ResponseField name="country_name" type="string">
+ Country name
+ Example: `United States`
+ </ResponseField>
+
+ <ResponseField name="country_iso" type="string">
+ Country ISO code
+ Example: `US`
+ </ResponseField>
+
+ <ResponseField name="country" type="Spree::Country">
+ Country object
+ <SpreeCountry />
+ </ResponseField>
+</Expandable>
\ No newline at end of file
diff --git a/docs/snippets/objects/spree_country.mdx b/docs/snippets/objects/spree_country.mdx
new file mode 100644
index 0000000000..54ca556f8d
--- /dev/null
+++ b/docs/snippets/objects/spree_country.mdx
@@ -0,0 +1,36 @@
+<Expandable title="properties">
+ <ResponseField name="id" type="integer">
+ Country ID
+ Example: 1
+ </ResponseField>
+
+ <ResponseField name="name" type="string">
+ Country name
+ Example: `United States`
+ </ResponseField>
+
+ <ResponseField name="iso3" type="string">
+ Country ISO3 code
+ Example: `USA`
+ </ResponseField>
+
+ <ResponseField name="iso" type="string">
+ Country ISO code
+ Example: `US`
+ </ResponseField>
+
+ <ResponseField name="iso_name" type="string">
+ Country ISO name
+ Example: `UNITED STATES`
+ </ResponseField>
+
+ <ResponseField name="states_required" type="boolean">
+ Whether states are required for this country
+ Example: `true`
+ </ResponseField>
+
+ <ResponseField name="zipcode_required" type="boolean">
+ Whether zipcodes are required for this country
+ Example: `true`
+ </ResponseField>
+</Expandable>
\ No newline at end of file
diff --git a/docs/snippets/objects/spree_line_item.mdx b/docs/snippets/objects/spree_line_item.mdx
new file mode 100644
index 0000000000..e55183de8c
--- /dev/null
+++ b/docs/snippets/objects/spree_line_item.mdx
@@ -0,0 +1,78 @@
+import SpreeVariant from '/snippets/objects/spree_variant.mdx';
+
+<Expandable title="properties">
+ <ResponseField name="id" type="integer">
+ Line item ID
+ Example: 123
+ </ResponseField>
+
+ <ResponseField name="quantity" type="integer">
+ Quantity of the variant ordered
+ Example: 2
+ </ResponseField>
+
+ <ResponseField name="price" type="decimal">
+ Unit price of the variant when ordered
+ Example: 29.99
+ </ResponseField>
+
+ <ResponseField name="display_price" type="string">
+ Formatted unit price with currency
+ Example: "$29.99"
+ </ResponseField>
+
+ <ResponseField name="total" type="decimal">
+ Total price for this line item (quantity * price)
+ Example: 59.98
+ </ResponseField>
+
+ <ResponseField name="display_total" type="string">
+ Formatted total price with currency
+ Example: "$59.98"
+ </ResponseField>
+
+ <ResponseField name="adjustment_total" type="decimal">
+ Sum of all adjustments for this line item
+ Example: -5.00
+ </ResponseField>
+
+ <ResponseField name="display_adjustment_total" type="string">
+ Formatted adjustment total with currency
+ Example: "-$5.00"
+ </ResponseField>
+
+ <ResponseField name="additional_tax_total" type="decimal">
+ Sum of additional tax amounts
+ Example: 4.50
+ </ResponseField>
+
+ <ResponseField name="included_tax_total" type="decimal">
+ Sum of included tax amounts
+ Example: 2.75
+ </ResponseField>
+
+ <ResponseField name="promo_total" type="decimal">
+ Sum of promotion adjustments
+ Example: -10.00
+ </ResponseField>
+
+ <ResponseField name="display_promo_total" type="string">
+ Formatted promotion total with currency
+ Example: "-$10.00"
+ </ResponseField>
+
+ <ResponseField name="order_id" type="integer">
+ Associated order ID
+ Example: 456
+ </ResponseField>
+
+ <ResponseField name="variant" type="Spree::Variant">
+ Associated product variant
+ <SpreeVariant />
+ </ResponseField>
+
+ <ResponseField name="currency" type="string">
+ Currency of the line item
+ Example: "USD"
+ </ResponseField>
+</Expandable>
diff --git a/docs/snippets/objects/spree_order.mdx b/docs/snippets/objects/spree_order.mdx
new file mode 100644
index 0000000000..07973a9997
--- /dev/null
+++ b/docs/snippets/objects/spree_order.mdx
@@ -0,0 +1,156 @@
+import SpreeUser from '/snippets/objects/spree_user.mdx';
+import SpreeAddress from '/snippets/objects/spree_address.mdx';
+import SpreeLineItem from '/snippets/objects/spree_line_item.mdx';
+
+<Expandable title="properties">
+ <ResponseField name="number" type="string">
+ The order number
+ Example: `R123456789`
+ </ResponseField>
+
+ <ResponseField name="total" type="decimal">
+ The total amount of the order
+ Example: 99.99
+ </ResponseField>
+
+ <ResponseField name="display_total" type="string">
+ Formatted total with currency
+ Example: "$99.99"
+ </ResponseField>
+
+ <ResponseField name="item_total" type="decimal">
+ Sum of all line item amounts pre-tax
+ Example: 89.99
+ </ResponseField>
+
+ <ResponseField name="display_item_total" type="string">
+ Formatted item total with currency
+ Example: "$89.99"
+ </ResponseField>
+
+ <ResponseField name="adjustment_total" type="decimal">
+ Sum of all adjustments
+ Example: -10.00
+ </ResponseField>
+
+ <ResponseField name="display_adjustment_total" type="string">
+ Formatted adjustment total with currency
+ Example: "-$10.00"
+ </ResponseField>
+
+ <ResponseField name="tax_total" type="decimal">
+ Sum of all tax amounts
+ Example: 13.25
+ </ResponseField>
+
+ <ResponseField name="display_tax_total" type="string">
+ Formatted tax total with currency
+ Example: "$13.25"
+ </ResponseField>
+
+ <ResponseField name="shipment_total" type="decimal">
+ Sum of shipment amounts
+ Example: 10.00
+ </ResponseField>
+
+ <ResponseField name="display_shipment_total" type="string">
+ Formatted shipment total with currency
+ Example: "$10.00"
+ </ResponseField>
+
+ <ResponseField name="promo_total" type="decimal">
+ Sum of all promotion adjustments
+ Example: -15.00
+ </ResponseField>
+
+ <ResponseField name="display_promo_total" type="string">
+ Formatted promotion total with currency
+ Example: "-$15.00"
+ </ResponseField>
+
+ <ResponseField name="included_tax_total" type="decimal">
+ Sum of included tax amounts
+ Example: 8.25
+ </ResponseField>
+
+ <ResponseField name="additional_tax_total" type="decimal">
+ Sum of additional tax amounts
+ Example: 5.00
+ </ResponseField>
+
+ <ResponseField name="payment_total" type="decimal">
+ Sum of completed payment amounts
+ Example: 99.99
+ </ResponseField>
+
+ <ResponseField name="state" type="string">
+ Current order state
+ Example: `cart`
+ </ResponseField>
+
+ <ResponseField name="email" type="string">
+ Customer email address
+ Example: `[email protected]`
+ </ResponseField>
+
+ <ResponseField name="user_id" type="integer">
+ Associated user ID
+ Example: 123
+ </ResponseField>
+
+ <ResponseField name="user" type="Spree::User">
+ Associated user object
+
+ <SpreeUser />
+ </ResponseField>
+
+ <ResponseField name="completed_at" type="datetime">
+ When the order was completed (placed and paid). For orders in `cart` state, this will be `nil`.
+ Example: `2023-06-15 13:45:00`
+ </ResponseField>
+
+ <ResponseField name="bill_address_id" type="integer">
+ Billing address ID
+ Example: 456
+ </ResponseField>
+
+ <ResponseField name="bill_address" type="Spree::Address">
+ Billing address object
+ <SpreeAddress />
+ </ResponseField>
+
+ <ResponseField name="ship_address_id" type="integer">
+ Shipping address ID
+ Example: 457
+ </ResponseField>
+
+ <ResponseField name="ship_address" type="Spree::Address">
+ Shipping address object
+ <SpreeAddress />
+ </ResponseField>
+
+ <ResponseField name="payment_state" type="string">
+ Payment state (balance_due, credit_owed, failed, paid, void)
+ Example: `paid`
+ </ResponseField>
+
+ <ResponseField name="shipment_state" type="string">
+ Shipment state (backorder, canceled, partial, pending, ready, shipped)
+ Example: `shipped`
+ </ResponseField>
+
+ <ResponseField name="currency" type="string">
+ Order currency
+ Example: `USD`
+ </ResponseField>
+
+ <ResponseField name="store_id" type="integer">
+ Associated store ID
+ Example: 1
+ </ResponseField>
+
+ <ResponseField name="line_items" type="array">
+ Line items in the order
+ <SpreeLineItem />
+ </ResponseField>
+</Expandable>
\ No newline at end of file
diff --git a/docs/snippets/objects/spree_state.mdx b/docs/snippets/objects/spree_state.mdx
new file mode 100644
index 0000000000..b7c13e6226
--- /dev/null
+++ b/docs/snippets/objects/spree_state.mdx
@@ -0,0 +1,21 @@
+<Expandable title="properties">
+ <ResponseField name="id" type="integer">
+ State ID
+ Example: 1
+ </ResponseField>
+
+ <ResponseField name="name" type="string">
+ State name
+ Example: `California`
+ </ResponseField>
+
+ <ResponseField name="abbr" type="string">
+ State abbreviation
+ Example: `CA`
+ </ResponseField>
+
+ <ResponseField name="country_id" type="integer">
+ Country ID
+ Example: 1
+ </ResponseField>
+</Expandable>
\ No newline at end of file
diff --git a/docs/snippets/objects/spree_store.mdx b/docs/snippets/objects/spree_store.mdx
new file mode 100644
index 0000000000..7f1c9858f7
--- /dev/null
+++ b/docs/snippets/objects/spree_store.mdx
@@ -0,0 +1,68 @@
+import SpreeCountry from '/snippets/objects/spree_country.mdx';
+
+<Expandable title="Properties">
+ <ResponseField name="name" type="string">
+ Store name
+ Example: "My Store"
+ </ResponseField>
+
+ <ResponseField name="url" type="string">
+ Store URL
+ Example: `https://mystore.com`
+ </ResponseField>
+
+ <ResponseField name="code" type="string">
+ Unique store identifier
+ Example: `my-store`
+ </ResponseField>
+
+ <ResponseField name="mail_from_address" type="string">
+ Email address used for sending emails
+ Example: `[email protected]`
+ </ResponseField>
+
+ <ResponseField name="default_currency" type="string">
+ Default store currency
+ Example: `USD`
+ </ResponseField>
+
+ <ResponseField name="supported_currencies" type="string">
+ List of supported currencies
+ Example: `USD,EUR,GBP`
+ </ResponseField>
+
+ <ResponseField name="default_locale" type="string">
+ Default store locale
+ Example: `en`
+ </ResponseField>
+
+ <ResponseField name="supported_locales" type="string">
+ List of supported locales
+ Example: `en,es,fr`
+ </ResponseField>
+
+ <ResponseField name="default_country_id" type="integer">
+ Default country ID
+ Example: `1`
+ </ResponseField>
+
+ <ResponseField name="default_country" type="Spree::Country">
+ Default country
+ <SpreeCountry />
+ </ResponseField>
+
+ <ResponseField name="checkout_zone_id" type="integer">
+ Checkout zone ID
+ Example: `2`
+ </ResponseField>
+
+ <ResponseField name="seo_title" type="string">
+ SEO title
+ Example: `My Amazing Store`
+ </ResponseField>
+
+ <ResponseField name="meta_description" type="string">
+ Meta description for SEO
+ Example: `The best products at the best prices`
+ </ResponseField>
+</Expandable>
\ No newline at end of file
diff --git a/docs/snippets/objects/spree_theme.mdx b/docs/snippets/objects/spree_theme.mdx
new file mode 100644
index 0000000000..731973f13b
--- /dev/null
+++ b/docs/snippets/objects/spree_theme.mdx
@@ -0,0 +1,301 @@
+<Expandable title="properties">
+ <ResponseField name="id" type="integer">
+ Theme ID
+ Example: 1
+ </ResponseField>
+
+ <ResponseField name="name" type="string">
+ Theme name
+ Example: `Winter Sale Theme`
+ </ResponseField>
+
+ <ResponseField name="preferred_checkout_sidebar_text_color" type="string">
+ Checkout sidebar text color
+ Example: `#000000`
+ </ResponseField>
+
+ <ResponseField name="preferred_custom_font_code" type="string">
+ Custom font code
+ Example: `@import url('https://fonts.googleapis.com/css2?family=Inter&display=swap');`
+ </ResponseField>
+
+ <ResponseField name="preferred_font_family" type="string">
+ Font family
+ Example: `Inter`
+ </ResponseField>
+
+ <ResponseField name="preferred_font_size_scale" type="integer">
+ Font size scale
+ Example: `100`
+ </ResponseField>
+
+ <ResponseField name="preferred_header_font_family" type="string">
+ Header font family
+ Example: `Inter`
+ </ResponseField>
+
+ <ResponseField name="preferred_header_font_size_scale" type="integer">
+ Header font size scale
+ Example: `100`
+ </ResponseField>
+
+ <ResponseField name="preferred_headings_uppercase" type="boolean">
+ Headings uppercase
+ Example: `true`
+ </ResponseField>
+
+ <ResponseField name="preferred_button_border_thickness" type="integer">
+ Button border thickness
+ Example: `1`
+ </ResponseField>
+
+ <ResponseField name="preferred_button_border_opacity" type="integer">
+ Button border opacity
+ Example: `100`
+ </ResponseField>
+
+ <ResponseField name="preferred_button_border_radius" type="integer">
+ Button border radius
+ Example: `100`
+ </ResponseField>
+
+ <ResponseField name="preferred_button_shadow_opacity" type="integer">
+ Button shadow opacity
+ Example: `0`
+ </ResponseField>
+
+ <ResponseField name="preferred_button_shadow_horizontal_offset" type="integer">
+ Button shadow horizontal offset
+ Example: `0`
+ </ResponseField>
+
+ <ResponseField name="preferred_button_shadow_vertical_offset" type="integer">
+ Button shadow vertical offset
+ Example: `4`
+ </ResponseField>
+
+ <ResponseField name="preferred_button_shadow_blur" type="integer">
+ Button shadow blur
+ Example: `5`
+ </ResponseField>
+
+ <ResponseField name="preferred_input_border_thickness" type="integer">
+ Input border thickness
+ Example: `1`
+ </ResponseField>
+
+ <ResponseField name="preferred_input_border_opacity" type="integer">
+ Input border opacity
+ Example: `100`
+ </ResponseField>
+
+ <ResponseField name="preferred_input_border_radius" type="integer">
+ Input border radius
+ Example: `8`
+ </ResponseField>
+
+ <ResponseField name="preferred_input_shadow_opacity" type="integer">
+ Input shadow opacity
+ Example: `0`
+ </ResponseField>
+
+ <ResponseField name="preferred_input_shadow_horizontal_offset" type="integer">
+ Input shadow horizontal offset
+ Example: `0`
+ </ResponseField>
+
+ <ResponseField name="preferred_input_shadow_vertical_offset" type="integer">
+ Input shadow vertical offset
+ Example: `4`
+ </ResponseField>
+
+ <ResponseField name="preferred_input_shadow_blur" type="integer">
+ Input shadow blur
+ Example: `5`
+ </ResponseField>
+
+ <ResponseField name="preferred_border_width" type="integer">
+ Border width
+ Example: `1`
+ </ResponseField>
+
+ <ResponseField name="preferred_border_radius" type="integer">
+ Border radius
+ Example: `6`
+ </ResponseField>
+
+ <ResponseField name="preferred_border_shadow_opacity" type="integer">
+ Border shadow opacity
+ Example: `0`
+ </ResponseField>
+
+ <ResponseField name="preferred_border_shadow_horizontal_offset" type="integer">
+ Border shadow horizontal offset
+ Example: `0`
+ </ResponseField>
+
+ <ResponseField name="preferred_border_shadow_vertical_offset" type="integer">
+ Border shadow vertical offset
+ Example: `4`
+ </ResponseField>
+
+ <ResponseField name="preferred_border_shadow_blur" type="integer">
+ Border shadow blur
+ Example: `5`
+ </ResponseField>
+
+ <ResponseField name="preferred_product_listing_image_height" type="integer">
+ Product listing image height
+ Example: `300`
+ </ResponseField>
+
+ <ResponseField name="preferred_product_listing_image_width" type="integer">
+ Product listing image width
+ Example: `300`
+ </ResponseField>
+
+ <ResponseField name="preferred_product_listing_image_height_mobile" type="integer">
+ Product listing image height mobile
+ Example: `190`
+ </ResponseField>
+
+ <ResponseField name="preferred_product_listing_image_width_mobile" type="integer">
+ Product listing image width mobile
+ Example: `190`
+ </ResponseField>
+
+ <ResponseField name="preferred_primary_color" type="string">
+ Primary color
+ Example: `#000000`
+ </ResponseField>
+
+ <ResponseField name="preferred_accent_color" type="string">
+ Accent color
+ Example: `#F0EFE9`
+ </ResponseField>
+
+ <ResponseField name="preferred_danger_color" type="string">
+ Danger color
+ Example: `#C73528`
+ </ResponseField>
+
+ <ResponseField name="preferred_neutral_color" type="string">
+ Neutral color
+ Example: `#999999`
+ </ResponseField>
+
+ <ResponseField name="preferred_background_color" type="string">
+ Background color
+ Example: `#FFFFFF`
+ </ResponseField>
+
+ <ResponseField name="preferred_text_color" type="string">
+ Text color
+ Example: `#000000`
+ </ResponseField>
+
+ <ResponseField name="preferred_success_color" type="string">
+ Success color
+ Example: `#00C773`
+ </ResponseField>
+
+ <ResponseField name="preferred_button_background_color" type="string">
+ Button background color
+ Example: `#000000`
+ </ResponseField>
+
+ <ResponseField name="preferred_button_text_color" type="string">
+ Button text color
+ Example: `#ffffff`
+ </ResponseField>
+
+ <ResponseField name="preferred_button_hover_background_color" type="string">
+ Button hover background color
+ Example: `#000000`
+ </ResponseField>
+
+ <ResponseField name="preferred_button_hover_text_color" type="string">
+ Button hover text color
+ Example: `#ffffff`
+ </ResponseField>
+
+ <ResponseField name="preferred_button_border_color" type="string">
+ Button border color
+ Example: `#000000`
+ </ResponseField>
+
+ <ResponseField name="preferred_border_color" type="string">
+ Border color
+ Example: `#E9E7DC`
+ </ResponseField>
+
+ <ResponseField name="preferred_sidebar_border_color" type="string">
+ Sidebar border color
+ Example: `#E9E7DC`
+ </ResponseField>
+
+ <ResponseField name="preferred_secondary_button_background_color" type="string">
+ Secondary button background color
+ Example: `#000000`
+ </ResponseField>
+
+ <ResponseField name="preferred_secondary_button_text_color" type="string">
+ Secondary button text color
+ Example: `#ffffff`
+ </ResponseField>
+
+ <ResponseField name="preferred_secondary_button_hover_background_color" type="string">
+ Secondary button hover background color
+ Example: `#000000`
+ </ResponseField>
+
+ <ResponseField name="preferred_secondary_button_hover_text_color" type="string">
+ Secondary button hover text color
+ Example: `#ffffff`
+ </ResponseField>
+
+ <ResponseField name="preferred_input_text_color" type="string">
+ Input text color
+ Example: `#6b7280`
+ </ResponseField>
+
+ <ResponseField name="preferred_input_background_color" type="string">
+ Input background color
+ Example: `#ffffff`
+ </ResponseField>
+
+ <ResponseField name="preferred_input_border_color" type="string">
+ Input border color
+ Example: `#000000`
+ </ResponseField>
+
+ <ResponseField name="preferred_input_focus_border_color" type="string">
+ Input focus border color
+ Example: `#000000`
+ </ResponseField>
+
+ <ResponseField name="preferred_input_focus_background_color" type="string">
+ Input focus background color
+ Example: `#ffffff`
+ </ResponseField>
+
+ <ResponseField name="preferred_input_focus_text_color" type="string">
+ Input focus text color
+ Example: `#000000`
+ </ResponseField>
+
+ <ResponseField name="preferred_checkout_sidebar_background_color" type="string">
+ Checkout sidebar background color
+ Example: `#f3f4f6`
+ </ResponseField>
+
+ <ResponseField name="preferred_checkout_divider_background_color" type="string">
+ Checkout divider background color
+ Example: `#f3f4f6`
+ </ResponseField>
+
+ <ResponseField name="preferred_checkout_sidebar_text_color" type="string">
+ Checkout sidebar text color
+ Example: `#000000`
+ </ResponseField>
+</Expandable>
\ No newline at end of file
diff --git a/docs/snippets/objects/spree_user.mdx b/docs/snippets/objects/spree_user.mdx
new file mode 100644
index 0000000000..eb7ec5d625
--- /dev/null
+++ b/docs/snippets/objects/spree_user.mdx
@@ -0,0 +1,42 @@
+import SpreeAddress from '/snippets/objects/spree_address.mdx';
+
+<Expandable title="properties">
+ <ResponseField name="id" type="integer">
+ User ID
+ Example: 123
+ </ResponseField>
+
+ <ResponseField name="email" type="string">
+ User email address
+ Example: `[email protected]`
+ </ResponseField>
+
+ <ResponseField name="first_name" type="string">
+ User first name
+ Example: `John`
+ </ResponseField>
+
+ <ResponseField name="last_name" type="string">
+ User last name
+ Example: `Doe`
+ </ResponseField>
+
+ <ResponseField name="bill_address" type="Spree::Address">
+ Default billing address object
+ <SpreeAddress />
+ </ResponseField>
+
+ <ResponseField name="ship_address" type="Spree::Address">
+ Default shipping address object
+ <SpreeAddress />
+ </ResponseField>
+
+ <ResponseField name="tag_list" type="array">
+ User tags (tags are used managable by store admins)
+ Example:
+
+ ```ruby
+ ["vip", "wholesale"]
+ ```
+ </ResponseField>
+</Expandable>
\ No newline at end of file
diff --git a/docs/snippets/objects/spree_variant.mdx b/docs/snippets/objects/spree_variant.mdx
new file mode 100644
index 0000000000..cba9113cb7
--- /dev/null
+++ b/docs/snippets/objects/spree_variant.mdx
@@ -0,0 +1,101 @@
+<Expandable title="properties">
+ <ResponseField name="id" type="integer">
+ Variant ID
+ Example: 123
+ </ResponseField>
+
+ <ResponseField name="sku" type="string">
+ Stock Keeping Unit - unique identifier for the variant
+ Example: "ABC-123"
+ </ResponseField>
+
+ <ResponseField name="name" type="string">
+ Name of the variant (inherited from product)
+ Example: "Basic T-Shirt"
+ </ResponseField>
+
+ <ResponseField name="options_text" type="string">
+ Formatted string of option values
+ Example: "Size: Large, Color: Blue"
+ </ResponseField>
+
+ <ResponseField name="descriptive_name" type="string">
+ Full descriptive name including master status or options
+ Example: "Basic T-Shirt - Size: Large, Color: Blue"
+ </ResponseField>
+
+ <ResponseField name="price" type="decimal">
+ Base price of the variant
+ Example: 29.99
+ </ResponseField>
+
+ <ResponseField name="display_price" type="string">
+ Formatted price with currency
+ Example: "$29.99"
+ </ResponseField>
+
+ <ResponseField name="weight" type="decimal">
+ Weight of the variant
+ Example: 1.5
+ </ResponseField>
+
+ <ResponseField name="height" type="decimal">
+ Height of the variant
+ Example: 10.0
+ </ResponseField>
+
+ <ResponseField name="width" type="decimal">
+ Width of the variant
+ Example: 5.0
+ </ResponseField>
+
+ <ResponseField name="depth" type="decimal">
+ Depth of the variant
+ Example: 2.0
+ </ResponseField>
+
+ <ResponseField name="is_master" type="boolean">
+ Whether this is the master variant of the product
+ Example: false
+ </ResponseField>
+
+ <ResponseField name="position" type="integer">
+ Display order position
+ Example: 1
+ </ResponseField>
+
+ <ResponseField name="track_inventory" type="boolean">
+ Whether inventory tracking is enabled for this variant
+ Example: true
+ </ResponseField>
+
+ <ResponseField name="available?" type="boolean">
+ Whether the variant is available for purchase (not discontinued and product is available)
+ Example: true
+ </ResponseField>
+
+ <ResponseField name="in_stock?" type="boolean">
+ Whether the variant currently has stock available
+ Example: true
+ </ResponseField>
+
+ <ResponseField name="tax_category_id" type="integer">
+ ID of the associated tax category
+ Example: 1
+ </ResponseField>
+
+ <ResponseField name="cost_price" type="decimal">
+ Cost price of the variant
+ Example: 15.00
+ </ResponseField>
+
+ <ResponseField name="cost_currency" type="string">
+ Currency of the cost price
+ Example: "USD"
+ </ResponseField>
+
+ <ResponseField name="product_id" type="integer">
+ ID of the associated product
+ Example: 456
+ </ResponseField>
+</Expandable>
diff --git a/storefront/app/helpers/spree/products_helper.rb b/storefront/app/helpers/spree/products_helper.rb
index 5b3e2bdbc4..4f899acc58 100644
--- a/storefront/app/helpers/spree/products_helper.rb
+++ b/storefront/app/helpers/spree/products_helper.rb
@@ -21,10 +21,14 @@ module Spree
end
def weeks_online(product)
+ Spree::Deprecation.warn('weeks_online is deprecated and will be removed in Spree 5.2')
+
(Time.current - product.activated_at.in_time_zone(current_store.preferred_timezone)).seconds.in_weeks.to_i.abs
end
def brand_name(product)
+ Spree::Deprecation.warn('brand_name is deprecated and will be removed in Spree 5.2. Please use `product.brand_name` instead.')
+
product.brand&.name || product.try(:vendor)&.display_name
end
@@ -152,6 +156,10 @@ module Spree
product.main_taxon.self_and_ancestors.find_all { |taxon| taxon.depth != 0 }
end
+ # Generates the JSON-LD elements for a list of products.
+ #
+ # @param product_slugs [Array<String>] The slugs of the products to generate elements for
+ # @return [Array<Hash>] The JSON-LD elements
def product_list_json_ld_elements(product_slugs)
product_slugs.each_with_index.map do |product_slug, index|
{
@@ -162,6 +170,10 @@ module Spree
end
end
+ # Generates the JSON-LD breadcrumbs for a product.
+ #
+ # @param product [Spree::Product] The product to generate breadcrumbs for
+ # @return [Hash] The JSON-LD breadcrumbs
def product_json_ld_breadcrumbs(product)
json_ld = {
'@context' => 'https://schema.org',
diff --git a/storefront/app/helpers/spree/storefront_helper.rb b/storefront/app/helpers/spree/storefront_helper.rb
index 6f69468db5..e1dc6dd5a2 100644
--- a/storefront/app/helpers/spree/storefront_helper.rb
+++ b/storefront/app/helpers/spree/storefront_helper.rb
@@ -3,12 +3,20 @@ module Spree
include BaseHelper
include Heroicon::Engine.helpers
+ # Renders the storefront partials for the given section.
+ #
+ # @param section [String] The section to render
+ # @param options [Hash] The options/variables to pass to the partials
+ # @return [String] The rendered partials
def render_storefront_partials(section, options = {})
Rails.application.config.spree_storefront.send(section).map do |partial|
render partial, options
end.join.html_safe
end
+ # Returns the page description for the current page.
+ #
+ # @return [String] The page description
def page_description
return @page_description if @page_description.present?
@@ -23,6 +31,10 @@ module Spree
@page_description
end
+ # Returns the page image for the current page.
+ # This is used for SEO, social media and Open Graph tags.
+ #
+ # @return [String] The page image
def page_image
return @page_image if @page_image.present?
diff --git a/storefront/app/helpers/spree/storefront_locale_helper.rb b/storefront/app/helpers/spree/storefront_locale_helper.rb
index f28d7ce87d..46daf69d12 100644
--- a/storefront/app/helpers/spree/storefront_locale_helper.rb
+++ b/storefront/app/helpers/spree/storefront_locale_helper.rb
@@ -1,5 +1,8 @@
module Spree
module StorefrontLocaleHelper
+ # Returns the currently selected locale.
+ #
+ # @return [String] The currently selected locale
def current_locale
@current_locale ||= if user_locale?
try_spree_current_user.selected_locale
diff --git a/storefront/app/helpers/spree/wishlist_helper.rb b/storefront/app/helpers/spree/wishlist_helper.rb
index f17218987e..40ce16f0f2 100644
--- a/storefront/app/helpers/spree/wishlist_helper.rb
+++ b/storefront/app/helpers/spree/wishlist_helper.rb
@@ -1,5 +1,8 @@
module Spree
module WishlistHelper
+ # Returns the current wishlist for the current user.
+ #
+ # @return [Spree::Wishlist] The current wishlist
def current_wishlist
@current_wishlist ||= try_spree_current_user&.default_wishlist_for_store(current_store)
end