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.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
Updated customization guides
Damian Legawiec336717018026
diff --git a/admin/app/views/spree/admin/shared/_user_dropdown.html.erb b/admin/app/views/spree/admin/shared/_user_dropdown.html.erbindex 336d61852b..09cf66947d 100644--- a/admin/app/views/spree/admin/shared/_user_dropdown.html.erb+++ b/admin/app/views/spree/admin/shared/_user_dropdown.html.erb@@ -27,7 +27,7 @@<div class="dropdown-divider"></div>- <%= link_to_with_icon 'book', 'Help center', 'https://spreecommerce.org/docs', class: 'dropdown-item', target: '_blank' %>+ <%= link_to_with_icon 'book', 'Help center', 'https://spreecommerce.org/docs/user', class: 'dropdown-item', target: '_blank' %><%= link_to_with_icon 'message-circle', 'Contact us', 'https://spreecommerce.org/contact/', class: 'dropdown-item', target: '_blank' %><div class="dropdown-divider"></div>diff --git a/core/lib/spree/core/configuration.rb b/core/lib/spree/core/configuration.rbindex 336afd95af..5b2d0fe615 100644--- a/core/lib/spree/core/configuration.rb+++ b/core/lib/spree/core/configuration.rb@@ -28,7 +28,7 @@ module Spreepreference :address_requires_phone, :boolean, default: false # Determines whether we require phone in addresspreference :allow_checkout_on_gateway_error, :boolean, default: falsepreference :allow_empty_price_amount, :boolean, default: false- preference :allow_guest_checkout, :boolean, default: true # this is only used in the rails frontend, and is not implemented in API+ preference :allow_guest_checkout, :boolean, default: true, deprecated: true # this is only used in the rails frontend, and is not implemented in APIpreference :alternative_shipping_phone, :boolean, default: false # Request extra phone for ship addrpreference :always_include_confirm_step, :boolean, default: false # Ensures confirmation step is always in checkout_progress bar, but does not force a confirm step if your payment methods do not support it.preference :always_put_site_name_in_title, :boolean, deprecated: truediff --git a/docs/developer/contributing/creating-an-extension.mdx b/docs/developer/contributing/creating-an-extension.mdxindex 0bc4da2bbd..77b5d3923b 100644--- a/docs/developer/contributing/creating-an-extension.mdx+++ b/docs/developer/contributing/creating-an-extension.mdx@@ -78,7 +78,7 @@ bin/rails g spree_simple_sales:installNow we need to extend `Spree::HomeController` and add an action that selects "on sale" products.- Note for the sake of this example that \`Spree::HomeController\` is only included in spree_frontend so you need to make it a dependency on your extensions \*.gemspec file.+ Note for the sake of this example that \`Spree::HomeController\` is only included in spree_storefront so you need to make it a dependency on your extensions \*.gemspec file.Make sure you are in the `spree_simple_sales` root directory and run the following command to create the directory structure for our controller decorator:diff --git a/docs/developer/core-concepts/i18n.mdx b/docs/developer/core-concepts/i18n.mdxindex d2e187a07e..bb20b15e44 100644--- a/docs/developer/core-concepts/i18n.mdx+++ b/docs/developer/core-concepts/i18n.mdx@@ -118,10 +118,6 @@ You don't need to copy any files from `spree_i18n` or `rails-i18n` for their tra## Translating Views-<Note>-This section is only applicable for optional`spree_frontend` and `spree_backend` gems-</Note>-When reviewing the source of any view in Spree you'll notice that all text is rendered by passing a string to a helper method similar to:```erbdiff --git a/docs/developer/core-concepts/preferences.mdx b/docs/developer/core-concepts/preferences.mdxindex b77ff946d3..30d9d593b0 100644--- a/docs/developer/core-concepts/preferences.mdx+++ b/docs/developer/core-concepts/preferences.mdx@@ -11,7 +11,6 @@ Here is a list of all the runtime preferences that are available in Spree.| `allow_checkout_on_gateway_error` | Continues the checkout process even if the payment gateway error failed. | `false` || `address_requires_phone` | Determines whether a phone number is required for Addresses. | `true` || `alternative_shipping_phone` | Determines if an alternative phone number should be present for the shipping address on the checkout page. | `false` |- | `allow_guest_checkout` | Determines if guests can proceed to checkout without creating an account. | `true` || `always_include_confirm_step` | Determines if the confirmation step is always included in the checkout process, regardless of the payment method. | `false` || `auto_capture` | Depending on whether or not Spree is configured to "auto capture" the credit card, either a purchase or an authorize operation will be performed on the card (via the current credit card gateway). | `false` || `auto_capture_on_dispatch` | Captures payment for each shipment in Shipment#after_ship callback, and makes Shipment.ready when payment authorized. | `false` |diff --git a/docs/developer/customization/checkout.mdx b/docs/developer/customization/checkout.mdxindex 1e85f35891..f6d163593c 100644--- a/docs/developer/customization/checkout.mdx+++ b/docs/developer/customization/checkout.mdx@@ -1,6 +1,7 @@---title: Checkout Flowdescription: Learn how to customize the checkout process in Spree.+version: v5---## Overview@@ -41,70 +42,30 @@ If you want a list of all the currently available states for the checkout, use tThe Spree checkout process consists of the following steps. With the exception of the Registration step, each of these steps corresponds to a state of the [Order object](/developer/core-concepts/orders):-* Registration Optional - only if using [spree_auth_devise](https://github.com/spree/spree_auth_devise) extension, can be toggled through the `Spree::Auth::Config[:registration_step]` configuration setting-* Address Information+* Shipping Address and Contact Information* Delivery Options Shipping Method-* Payment-* Confirmation+* Payment and Billing Information+* Confirmation (optional)The following sections will provide a walk-through of checkout from a user's perspective, and offer some information on how to configure the default behavior of the various steps.-### Registration+### Shipping Address and Contact Information-<Info>-This section only applies when using `spree_frontend` and `spree_auth_devise` gems.-</Info>--Prior to beginning the checkout process, the customer will be prompted to create a new account or to log in to their existing account. By default, there is also a "guest checkout" option that allows users to specify only their email address if they do not wish to create an account.--Technically, the registration step is not an actual state in the `Spree::Order` state machine. The `spree_auth_devise` gem (an extension that comes with Spree Starter by default) adds the `check_registration` before filter to all actions of `Spree::CheckoutController` except for obvious reasons the `registration` and `update_registration` actions, which redirects to a registration page unless one of the following is true:--* `Spree::Auth::Config[:registration_step]` preference is not `true`-* user is already logged in-* the current order has an email address associated with it--The method is defined like this:--```ruby-def check_registration- return unless Spree::Auth::Config[:registration_step]- return if spree_current_user || current_order.email- store_location- redirect_to spree.checkout_registration_path-end-```--#### Disabling guest checkout--To completely disable guest checkout and require registration for checkout, you need to change Spree configuration in `config/initializers/spree.rb`:--```ruby-Spree::Config[:allow_guest_checkout] = false-```--### Address Information--This step allows the customer to add both their billing and shipping information. Customers can click the "use billing address" option to use the same address for both.+This step allows the customer to add shipping information and contact information. Customers have also option to sign in or create an account. For payment methods such as Stripe customers can use quick checkout option via payment wallets such as Apple Pay, Google Pay, etc and skip the rest of the checkout process.The address fields include a select box for choosing state/province. If there are no states configured for a particular country, the select box will be replaced by a text field instead.-The list of countries that appear in the country select box can also be configured. Spree will list all countries by default, but you can configure exactly which countries you would like to appear. The list can be limited to a specific set of countries by [setting the Store's checkout zone](/developer/core-concepts/stores#checkout-configuration). Spree assumes that the list of billing and shipping countries will be the same. You can always change this logic via class decorator if this does not suit your needs.+The list of countries that appear in the country select box can also be configured. Spree will list all countries by default, but you can configure exactly which countries you would like to appear. The list can be limited to a specific set of countries by [setting the Store's checkout zone](/developer/core-concepts/stores#checkout-configuration).### Delivery Options-During this step, the user may choose a delivery method. Spree assumes the list of shipping methods to be dependent on the shipping address.+During this step, the user may choose a delivery method. Spree assumes the list of shipping methods to be dependent on the shipping address. If there are multiple shipments eg. different Stock Locations or Vendors, the user will be asked to select shipping method for each shipment.### Payment-This step is where the customer provides payment information. This step is intentionally placed last in order to minimize security issues with credit card information. Credit card information is never stored in the database so it would be impossible to have a subsequent step and still be able to submit the information to the payment gateway. Spree submits the information to the gateway before saving the model so that the sensitive information can be discarded before saving the checkout information.+This step is where the customer provides payment and billing information. Spree does not store any payment information in the database. For payment methods such as Stripe, we use Stripe JavaScript SDKs to render their payment form inside the checkout page, fully compliant with PCI DSS standards.-Spree stores only the last four digits of the credit card number along with the expiration information. The full credit card number and verification code are never stored in the Spree database.--Several gateways such as ActiveMerchant and Beanstream provide a secure method for storing a "payment profile" in your database. This approach typically involves the use of a "token" which can be used for subsequent purchases but only with your merchant account. If you are using a secure payment profile it would then be possible to show a final "confirmation" step after payment information is entered.--If you do not want to use a gateway with payment profiles then you will need to customize the checkout process so that your final step submits the credit card information. You can then perform authorization before the order is saved. This is perfectly secure because the credit card information is not ever saved. It's transmitted to the gateway and then discarded like normal.-- Spree discards the credit card number after this step is processed. If you do not have a gateway with payment profiles enabled then your card information will be lost before it's time to authorize the card.+Besides Credit Card, Wallets and other 3rd party payment methods, Spree also supports Store Credit and Gift Cards (Spree 5.1+ only) which can be used to pay for the entire order or part of the order.For more information about payments, please see the [Payments guide](/developer/core-concepts/payments).@@ -122,6 +83,8 @@ This step is disabled by default, but can be enabled by two ways:2. conditionally for specific orders by overriding the `confirmation_required?` method in `Spree::Order`, eg.+ `app/models/spree/order_decorator.rb` file:+```rubymodule Spreemodule OrderDecoratordiff --git a/docs/developer/customization/quickstart.mdx b/docs/developer/customization/quickstart.mdxindex 921ceb33c8..b0a91de2e9 100644--- a/docs/developer/customization/quickstart.mdx+++ b/docs/developer/customization/quickstart.mdx@@ -29,7 +29,6 @@ There are several ways you can achieve this:| `allow_checkout_on_gateway_error` | Continues the checkout process even if the payment gateway error failed. | `false` || `address_requires_phone` | Determines whether a phone number is required for Addresses. | `true` || `alternative_shipping_phone` | Determines if an alternative phone number should be present for the shipping address on the checkout page. | `false` |- | `allow_guest_checkout` | Determines if guests can proceed to checkout without creating an account. | `true` || `always_include_confirm_step` | Determines if the confirmation step is always included in the checkout process, regardless of the payment method. | `false` || `auto_capture` | Depending on whether or not Spree is configured to "auto capture" the credit card, either a purchase or an authorize operation will be performed on the card (via the current credit card gateway). | `false` || `auto_capture_on_dispatch` | Captures payment for each shipment in Shipment#after_ship callback, and makes Shipment.ready when payment authorized. | `false` |@@ -65,12 +64,6 @@ There are several ways you can achieve this:You can find more information in the [Authentication](authentication) section.</Accordion>- <Accordion title="Images">- Spree allows you to change the images for products, variants and taxons.-- Please see [Images customization section](images) for more information.- </Accordion>-<Accordion title="Checkout flow">With Spree you can change the checkout flow to fit your business needs.diff --git a/docs/developer/customization/routes.mdx b/docs/developer/customization/routes.mdxindex b50249c0c1..49ae9a8355 100644--- a/docs/developer/customization/routes.mdx+++ b/docs/developer/customization/routes.mdx@@ -22,19 +22,3 @@ mount Spree::Core::Engine, at: `/shop````The different parts of Spree (API, Admin) will be mounted there as well, eg. `http://localhost:3000/shop/products`.--## Customizing admin panel path--<Info>-Remember to have the `spree_backend` installed.-</Info>--By default, Spree Admin is mounted at `/admin` and is accessible at `http://localhost:3000/admin`.--You can change the path of the admin panel by setting the `admin_path` option in your `config/initializers/spree.rb` file, eg.--```ruby-Spree.admin_path = '/dashboard'-```--This will change the path of the Spree Admin to `http://localhost:3000/dashboard`.\ No newline at end of filediff --git a/docs/developer/customization/v4/checkout.mdx b/docs/developer/customization/v4/checkout.mdxnew file mode 100644index 0000000000..2f59f87fad--- /dev/null+++ b/docs/developer/customization/v4/checkout.mdx@@ -0,0 +1,214 @@+---+title: Checkout Flow+description: Learn how to customize the checkout process in Spree.+version: v4+---++## Overview++The Spree checkout process has been designed for maximum flexibility. It's been redesigned several times now, each iteration has benefited from the feedback of real-world deployment experience. It is relatively simple to customize the checkout process to suit your needs. Secure transmission of customer information is possible via SSL and credit card information is never stored in the database.++## The Checkout Flow DSL++Spree comes with a new checkout DSL that allows you succinctly define the different steps of your checkout. This new DSL allows you to customize _just_ the checkout flow, while maintaining the unrelated admin states, such as "canceled" and "resumed", that an order can transition to. Ultimately, it provides a shorter syntax compared with overriding the entire state machine for the `Spree::Order` class.++The default checkout flow for Spree is defined like this, adequately demonstrating the abilities of this new system:++```ruby+checkout_flow do+ go_to_state :address+ go_to_state :delivery+ go_to_state :payment, if: ->(order) {+ order.update_totals+ order.payment_required?+ }+ go_to_state :confirm, if: ->(order) { order.confirmation_required? }+ go_to_state :complete+ remove_transition from: :delivery, to: :confirm+```++we can pass a block on each checkout step definition and work some logic to figure if the step is required dynamically. e.g. the confirm step might only be necessary for payment gateways that support payment profiles.++These conditional states present a situation where an order could transition from delivery to one of payment, confirm or complete. In the default checkout, we never want to transition from delivery to confirm, and therefore have removed it using the `remove_transition` method of the Checkout DSL. The resulting transitions between states look like the image below:++These two helper methods are provided on `Spree::Order` instances for your convenience:++* `checkout_steps` - returns a list of all the potential states of the checkout.+* `has_step?` - Used to check if the current order fulfills the requirements for a specific state.++If you want a list of all the currently available states for the checkout, use the `checkout_steps` method, which will return the steps in an array.++## Default Checkout Steps++The Spree checkout process consists of the following steps. With the exception of the Registration step, each of these steps corresponds to a state of the [Order object](/developer/core-concepts/orders):++* Registration Optional - only if using [spree_auth_devise](https://github.com/spree/spree_auth_devise) extension, can be toggled through the `Spree::Auth::Config[:registration_step]` configuration setting+* Address Information+* Delivery Options Shipping Method+* Payment+* Confirmation++The following sections will provide a walk-through of checkout from a user's perspective, and offer some information on how to configure the default behavior of the various steps.++### Registration++<Info>+This section only applies when using `spree_frontend` and `spree_auth_devise` gems.+</Info>++Prior to beginning the checkout process, the customer will be prompted to create a new account or to log in to their existing account. By default, there is also a "guest checkout" option that allows users to specify only their email address if they do not wish to create an account.++Technically, the registration step is not an actual state in the `Spree::Order` state machine. The `spree_auth_devise` gem (an extension that comes with Spree Starter by default) adds the `check_registration` before filter to all actions of `Spree::CheckoutController` except for obvious reasons the `registration` and `update_registration` actions, which redirects to a registration page unless one of the following is true:++* `Spree::Auth::Config[:registration_step]` preference is not `true`+* user is already logged in+* the current order has an email address associated with it++The method is defined like this:++```ruby+def check_registration+ return unless Spree::Auth::Config[:registration_step]+ return if spree_current_user || current_order.email+ store_location+ redirect_to spree.checkout_registration_path+end+```++#### Disabling guest checkout++To completely disable guest checkout and require registration for checkout, you need to change Spree configuration in `config/initializers/spree.rb`:++```ruby+Spree::Config[:allow_guest_checkout] = false+```++### Address Information++This step allows the customer to add both their billing and shipping information. Customers can click the "use billing address" option to use the same address for both.++The address fields include a select box for choosing state/province. If there are no states configured for a particular country, the select box will be replaced by a text field instead.++The list of countries that appear in the country select box can also be configured. Spree will list all countries by default, but you can configure exactly which countries you would like to appear. The list can be limited to a specific set of countries by [setting the Store's checkout zone](/developer/core-concepts/stores#checkout-configuration). Spree assumes that the list of billing and shipping countries will be the same. You can always change this logic via class decorator if this does not suit your needs.++### Delivery Options++During this step, the user may choose a delivery method. Spree assumes the list of shipping methods to be dependent on the shipping address.++### Payment++This step is where the customer provides payment information. This step is intentionally placed last in order to minimize security issues with credit card information. Credit card information is never stored in the database so it would be impossible to have a subsequent step and still be able to submit the information to the payment gateway. Spree submits the information to the gateway before saving the model so that the sensitive information can be discarded before saving the checkout information.++Spree stores only the last four digits of the credit card number along with the expiration information. The full credit card number and verification code are never stored in the Spree database.++Several gateways such as ActiveMerchant and Beanstream provide a secure method for storing a "payment profile" in your database. This approach typically involves the use of a "token" which can be used for subsequent purchases but only with your merchant account. If you are using a secure payment profile it would then be possible to show a final "confirmation" step after payment information is entered.++If you do not want to use a gateway with payment profiles then you will need to customize the checkout process so that your final step submits the credit card information. You can then perform authorization before the order is saved. This is perfectly secure because the credit card information is not ever saved. It's transmitted to the gateway and then discarded like normal.++ Spree discards the credit card number after this step is processed. If you do not have a gateway with payment profiles enabled then your card information will be lost before it's time to authorize the card.++For more information about payments, please see the [Payments guide](/developer/core-concepts/payments).++### Confirmation++This is the final opportunity for the customer to review their order before submitting it to be processed. Users have the opportunity to return to any step in the process using either the back button or by clicking on the appropriate step in the "progress breadcrumb."++This step is disabled by default, but can be enabled by two ways:++1. globally for all orders by setting a preference in `config/initializers/spree.rb`:++ ```ruby+ Spree::Config[:always_include_confirm_step] = true+ ```++2. conditionally for specific orders by overriding the `confirmation_required?` method in `Spree::Order`, eg.++ ```ruby+ module Spree+ module OrderDecorator+ # require confirmation for orders with a US billing address+ def confirmation_required?+ billing_address&.country_iso == 'US'+ end+ end+ end+ ```++## Adding Logic Before or After a Particular Step++The [state_machines](https://github.com/state-machines/state_machines) gem allows you to implement callbacks before or after transitioning to a particular step. These callbacks work similarly to [Active Record Callbacks](http://guides.rubyonrails.org/active_record_callbacks.html) in that you can specify a method or block of code to be executed prior to or after a transition. If the method executed in a before_transition returns false, then the transition will not execute.++So, for example, if you wanted to verify that the user provides a valid zip code before transitioning to the delivery step, you would first implement a `valid_zip_code?` method, and then tell the state machine to run this method before that transition, placing this code in a file called `app/models/spree/order_decorator.rb`:++```ruby+module Spree+ module OrderDecorator+ def self.prepended(base)+ base.state_machine.before_transition to: :delivery, do: :valid_zip_code?+ end++ def valid_zip_code?+ # logic to check if the zip code is valid+ end+ end++ Order.prepend(OrderDecorator)+end+```++This callback would prevent transitioning to the `delivery` step if `valid_zip_code?` returns false.++## Modifying the checkout flow++To add or remove steps to the checkout flow, you can use the+[insert_checkout_step](https://github.com/spree/spree/blob/a39ed2b69f1f2b2f413b7f46090bd0deeb439d61/core/app/models/spree/order/checkout.rb#L138) and [remove_checkout_step](https://github.com/spree/spree/blob/a39ed2b69f1f2b2f413b7f46090bd0deeb439d61/core/app/models/spree/order/checkout.rb#L157) helpers respectively.++The `insert_checkout_step` method takes a `before` or `after` option to determine where to insert the step:++```ruby+module Spree+ module OrderDecorator+ def self.prepended(base)+ base.insert_checkout_step :new_step, before: :address+ # or+ # base.insert_checkout_step :new_step, after: :address+ end+ end++ Order.prepend(OrderDecorator)+end+```++The `remove_checkout_step` will remove just one checkout step at a time:++```ruby+module Spree+ module OrderDecorator+ def self.prepended(base)+ base.remove_checkout_step :address+ base.remove_checkout_step :delivery+ end+ end++ Order.prepend(OrderDecorator)+end+```++What will happen here is that when a user goes to checkout, they will be asked to potentially fill in their payment details and then potentially confirm the order. This is the default behavior of the payment and the confirm steps within the checkout. If they are not required to provide payment or confirmation for this order then checking out this order will result in its immediate completion.++To completely re-define the flow of the checkout, use the `checkout_flow` helper:++```ruby+module Spree+ module OrderDecorator+ def self.prepended(base)+ base.checkout_flow do+ go_to_state :payment+ go_to_state :complete+ end+ end+ end++ Order.prepend(OrderDecorator)+end+```\ No newline at end of filediff --git a/docs/developer/customization/storefront.mdx b/docs/developer/customization/v4/storefront.mdxsimilarity index 99%rename from docs/developer/customization/storefront.mdxrename to docs/developer/customization/v4/storefront.mdxindex 1c338c2fba..5566508e69 100644--- a/docs/developer/customization/storefront.mdx+++ b/docs/developer/customization/v4/storefront.mdx@@ -1,5 +1,3 @@-# Storefront-<Note>This section covers the Rails storefront which was extracted to [`spree_frontend`](https://github.com/spree/spree_rails_frontend) ruby gem.</Note>diff --git a/docs/mint.json b/docs/mint.jsonindex b2685ea2b5..8eec2d5748 100644--- a/docs/mint.json+++ b/docs/mint.json@@ -117,14 +117,15 @@"pages": ["developer/customization/quickstart","developer/customization/v4/authentication",- "developer/customization/images",- "developer/customization/checkout",+ "developer/customization/v4/images",+ "developer/customization/v4/checkout",+ "developer/customization/v4/admin-panel",+ "developer/customization/v4/storefront",+ "developer/customization/v4/deface","developer/customization/permissions","developer/customization/dependencies","developer/customization/decorators","developer/customization/routes",- "developer/customization/v4/admin-panel",- "developer/customization/v4/deface"]},