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
[skip ci] documentation - customization guides - part 1
Damian Legawiec998c1fe12883
diff --git a/docs/developer/contributing/creating-an-extension.mdx b/docs/developer/contributing/creating-an-extension.mdxindex 758f3d53c8..439d8a2152 100644--- a/docs/developer/contributing/creating-an-extension.mdx+++ b/docs/developer/contributing/creating-an-extension.mdx@@ -36,7 +36,7 @@ The first thing we need to do is create a migration that adds a sale_price columWe can do this with the following command:```bash-bundle exec rails g migration add_sale_price_to_spree_variants sale_price:decimal+bin/rails g migration add_sale_price_to_spree_variants sale_price:decimal```Because we are dealing with prices, we need to now edit the generated migration to ensure the correct precision and scale. Edit the file `db/migrate/XXXXXXXXXXX_add_sale_price_to_spree_variants.rb` so that it contains the following:@@ -67,11 +67,11 @@ Once you have added the gem, it's time to bundle:bundle install```-Finally, let's run the `spree_simple_sales` install generator to copy over the migration we just created \(answer **yes** if prompted to run migrations\):+Finally, let's run the `spree_simple_sales` install generator to copy over the migration we just created answer **yes** if prompted to run migrations:```bash# context: Your Spree store's app root (i.e. Rails.root); not the extension's root path.-bundle exec rails g spree_simple_sales:install+bin/rails g spree_simple_sales:install```## Adding a Controller Action to HomeController@@ -119,7 +119,7 @@ endNow that our variants have the attribute `sale_price` available to them, let's update the sample data so we have at least one product that is on sale in our application. We will need to do this in the rails console for the time being, as we have no admin interface to set sale prices for variants. So, in order to do this, first open up the rails console:```bash-bundle exec rails c+bin/rails c```Now, follow the steps I take in selecting a product and updating its master variant to have a sale price. Note, you may not be editing the exact same product as I am, but this is not important. We just need one "on sale" product to display on the sales page.@@ -165,7 +165,7 @@ endSpree::Variant.prepend SpreeSimpleSalesSpree::VariantDecorator```-If there is a `sale_price` present on the product's master variant, we return that price. Otherwise, we call the original implementation of `price_in` \(using `return super`\).+If there is a `sale_price` present on the product's master variant, we return that price. Otherwise, we call the original implementation of `price_in` using `return super`.## Testing Our Decoratordiff --git a/docs/developer/contributing/updating-extensions.mdx b/docs/developer/contributing/updating-extensions.mdxindex 9b100aa76b..e12fb24f39 100644--- a/docs/developer/contributing/updating-extensions.mdx+++ b/docs/developer/contributing/updating-extensions.mdx@@ -7,7 +7,7 @@ description: How to upgrade your Spree extension to work with Spree 4Zeitwerk is the [new default code autoloader in Rails 6](https://weblog.rubyonrails.org/2019/2/22/zeitwerk-integration-in-rails-6-beta-2/).-This doesn't work well with the old approach to decorators \(files that name ends with decorator.rb, eg. `app/models/spree/order_decorator.rb`\) using [class_eval](https://www.jimmycuadra.com/posts/metaprogramming-ruby-class-eval-and-instance-eval/).+This doesn't work well with the old approach to decorators files that name ends with decorator.rb, eg. `app/models/spree/order_decorator.rb` using [class_eval](https://www.jimmycuadra.com/posts/metaprogramming-ruby-class-eval-and-instance-eval/).To fix this we need to convert all `class_eval` decorators to modules and use [Module.prepend](https://medium.com/@leo_hetsch/ruby-modules-include-vs-prepend-vs-extend-f09837a5b073). Also we need to name them properly according to [Zeitwerk naming rules](https://github.com/fxn/zeitwerk#file-structure)diff --git a/docs/developer/core-concepts/adjustments.mdx b/docs/developer/core-concepts/adjustments.mdxindex a77664c358..f88a9b1283 100644--- a/docs/developer/core-concepts/adjustments.mdx+++ b/docs/developer/core-concepts/adjustments.mdx@@ -130,7 +130,7 @@ module Spreeend```-Next you need to add the class to spree `Rails.application.config.spree.adjusters` so it is included whenever adjustments are updated \(Promotion and Tax are included by default\):+Next you need to add the class to spree `Rails.application.config.spree.adjusters` so it is included whenever adjustments are updated Promotion and Tax are included by default:```ruby# NOTE: it is advisable that that Tax be implemented last so Tax is calculated correctlydiff --git a/docs/developer/core-concepts/calculators.mdx b/docs/developer/core-concepts/calculators.mdxindex 5b24b529b1..81e5d4a81e 100644--- a/docs/developer/core-concepts/calculators.mdx+++ b/docs/developer/core-concepts/calculators.mdx@@ -4,7 +4,7 @@ title: Calculators## Overview-Spree makes extensive use of the `Spree::Calculator` model and there are several subclasses provided to deal with various types of calculations \(flat rate, percentage discount, sales tax, VAT, etc.\) All calculators extend the `Spree::Calculator` class and must provide the following methods:+Spree makes extensive use of the `Spree::Calculator` model and there are several subclasses provided to deal with various types of calculations flat rate, percentage discount, sales tax, VAT, etc. All calculators extend the `Spree::Calculator` class and must provide the following methods:```rubydef self.description@@ -63,7 +63,7 @@ This calculator is typically used for promotional discounts when you want a specThis calculator takes three preferences:-* `first_item`: The discounted price of the first item\(s\).+* `first_item`: The discounted price of the first items.* `additional_item`: The discounted price of subsequent items.* `max_items`: The maximum number of items this discount applies to.@@ -90,7 +90,7 @@ This calculator takes two preferences:* `amount`: The amount per item to calculate.* `currency`: The currency for this calculator.-This calculator depends on its `calculable` responding to a `promotion` method, which should return a `Spree::Promotion` \(or similar\) object. This object should then return a list of rules, which should respond to a `products` method. This is used to return a result of matching products.+This calculator depends on its `calculable` responding to a `promotion` method, which should return a `Spree::Promotion` or similar object. This object should then return a list of rules, which should respond to a `products` method. This is used to return a result of matching products.The list of matching products is compared against the line items for the order being calculated. If any of the matching products are included in the order, they are eligible for this calculator. The calculation is this:@@ -98,9 +98,9 @@ The list of matching products is compared against the line items for the order bEvery matching product within an order will add to the calculator's total. For example, assuming the calculator has an `amount` of 5 and there's an order with the following line items:-* Product A: $15.00 x 2 \(within matching products\)-* Product B: $10.00 x 1 \(within matching products\)-* Product C: $20.00 x 4 \(excluded from matching products\)+* Product A: $15.00 x 2 within matching products+* Product B: $10.00 x 1 within matching products+* Product C: $20.00 x 4 excluded from matching productsThe calculation would be:@@ -117,9 +117,9 @@ The Percent Per Item calculator works in a near-identical fashion to the [Per ItAssuming a calculator amount of 10% and an order such as this:-* Product A: $15.00 x 2 \(within matching products\)-* Product B: $10.00 x 1 \(within matching products\)-* Product C: $20.00 x 4 \(excluded from matching products\)+* Product A: $15.00 x 2 within matching products+* Product B: $10.00 x 1 within matching products+* Product C: $20.00 x 4 excluded from matching productsThe calculation would be:@@ -172,7 +172,7 @@ class CustomCalculator < Spree::ShippingCalculatorend```-The second thing is to register this calculator as a tax, shipping, or promotion adjustment calculator by calling code like this at the end of `config/initializers/spree.rb` inside your application \(`config` variable defined for brevity\):+The second thing is to register this calculator as a tax, shipping, or promotion adjustment calculator by calling code like this at the end of `config/initializers/spree.rb` inside your application `config` variable defined for brevity:```rubyconfig = Rails.application.configdiff --git a/docs/developer/core-concepts/inventory.mdx b/docs/developer/core-concepts/inventory.mdxindex a321d86142..e20dee696a 100644--- a/docs/developer/core-concepts/inventory.mdx+++ b/docs/developer/core-concepts/inventory.mdx@@ -16,7 +16,7 @@ New products created in the system can be given a starting "on hand" inventory lStock Locations are the locations where your inventory is shipped from. Each `StockLocation` has many `stock_items` and `stock_movements`.-Stock Locations can be created in the admin panel \(Configuration → Stock Locations\) or via Platform API.+Stock Locations can be created in the admin panel Configuration → Stock Locations or via Platform API.Stock Locations have several attributes that define their properties and behavior within the Spree system. Below is a table outlining these attributes:diff --git a/docs/developer/core-concepts/orders.mdx b/docs/developer/core-concepts/orders.mdxindex 0da428fb41..9d0280a2e2 100644--- a/docs/developer/core-concepts/orders.mdx+++ b/docs/developer/core-concepts/orders.mdx@@ -142,7 +142,7 @@ When a variant is added to an order, the price of that item is tracked along wit## Addresses-An order can link to two `Address` objects. The shipping address indicates where the order's product\(s\) should be shipped to. This address is used to determine which shipping methods are available for an order.+An order can link to two `Address` objects. The shipping address indicates where the order's products should be shipped to. This address is used to determine which shipping methods are available for an order.The billing address indicates where the user who's paying for the order is located. This can alter the tax rate for the order, which in turn can change how much the final order total can be.@@ -150,7 +150,7 @@ For more information about addresses, please read the [Addresses](/developer/cor## Adjustments-Adjustments are used to affect an order's final cost, either by decreasing it \([Promotions](promotions)\) or by increasing it \([Shipping](shipments), [Taxes](taxation)\).+Adjustments are used to affect an order's final cost, either by decreasing it [Promotions](promotions) or by increasing it [Shipping](shipments), [Taxes](taxation).For more information about adjustments, please see the [Adjustments](adjustments) guide.@@ -162,7 +162,7 @@ For more information, please read the [Payments](payments) guide.## Return Authorizations-An order can have many `ReturnAuthorization` objects. These records keeps track of which items have been authorized for return and how the user will be compensated -- either via exchanging the item\(s\) or a reimbursement.+An order can have many `ReturnAuthorization` objects. These records keeps track of which items have been authorized for return and how the user will be compensated -- either via exchanging the items or a reimbursement.## Updating an Orderdiff --git a/docs/developer/core-concepts/payments.mdx b/docs/developer/core-concepts/payments.mdxindex 3a26456dbf..c365cb69e9 100644--- a/docs/developer/core-concepts/payments.mdx+++ b/docs/developer/core-concepts/payments.mdx@@ -126,7 +126,7 @@ We don't store the full credit card number, only the last 4 digits and the card### Processing Walkthrough-When an order is completed in spree, each `Payment` object associated with the order has the `process!` method called on it \(unless `payment_required?` for the order returns `false`\), in order to attempt to automatically fulfill the payment required for the order. If the payment method requires a source (eg. `Spree::CreditCard`), and the payment has a source associated with it, then Spree will attempt to process the payment. Otherwise, the payment will need to be processed manually.+When an order is completed in spree, each `Payment` object associated with the order has the `process!` method called on it unless `payment_required?` for the order returns `false`, in order to attempt to automatically fulfill the payment required for the order. If the payment method requires a source (eg. `Spree::CreditCard`), and the payment has a source associated with it, then Spree will attempt to process the payment. Otherwise, the payment will need to be processed manually.If the `PaymentMethod` object is configured to auto-capture payments, then the `Payment#purchase!` method will be called, which will call `PaymentMethod#purchase` like this:@@ -142,7 +142,7 @@ payment_method.authorize(<amount>, <source>, <gateway options>)How the payment is actually put through depends on the `PaymentMethod` sub-class' implementation of the `purchase` and `authorize` methods.-The returned object from both the `purchase` and `authorize` methods on the payment method objects must be an [ActiveMerchant::Billing::Response](https://github.com/activemerchant/active_merchant/blob/master/lib/active_merchant/billing/response.rb) object. This response object is then stored \(in YAML\) in the `spree_log_entries` table. Log entries can be retrieved with a call to the `log_entries` association on any `Payment` object, eg.+The returned object from both the `purchase` and `authorize` methods on the payment method objects must be an [ActiveMerchant::Billing::Response](https://github.com/activemerchant/active_merchant/blob/master/lib/active_merchant/billing/response.rb) object. This response object is then stored in YAML in the `spree_log_entries` table. Log entries can be retrieved with a call to the `log_entries` association on any `Payment` object, eg.```rubypayment.log_entries@@ -169,15 +169,15 @@ payment.log_entries.first.detailsAccess to a number of payment gateways is handled with the usage of the [Spree Gateway](https://github.com/spree/spree_gateway) extension. This extension currently supports the following gateways:* Authorize.net-* Apple Pay \(via Stripe\)+* Apple Pay via Stripe* BanWire-* Bambora \(previously Beanstream\)+* Bambora previously Beanstream* Braintree* CyberSource* ePay* eWay* maxipago-* MasterCard Payment Gateway Service \(formerly MiGS\)+* MasterCard Payment Gateway Service formerly MiGS* Moneris* PayJunction* Payflow@@ -187,9 +187,9 @@ Access to a number of payment gateways is handled with the usage of the [Spree G* sage Pay* SecurePay* Spreedly-* Stripe \(with Stripe Elements\)+* Stripe with Stripe Elements* USAePay-* Worldpay \(previously Cardsave\)+* Worldpay previously CardsaveWith the `spree_gateway` gem included in your application's `Gemfile`, these gateways will be selectable in the admin backend for payment methods.diff --git a/docs/developer/core-concepts/shipments.mdx b/docs/developer/core-concepts/shipments.mdxindex 05184661d9..37a185f8e4 100644--- a/docs/developer/core-concepts/shipments.mdx+++ b/docs/developer/core-concepts/shipments.mdx@@ -21,7 +21,7 @@ Shipments have the following attributes:| Attribute | Description | Example Value ||--------------------|-----------------------------------------------------------------------------------------------|------------------------------|| `number` | The unique identifier for this shipment. It begins with the letter H and ends in an 11-digit number. This number is shown to the users, and can be used to find the order by calling `Spree::Shipment.find_by(number: number)`. | H12345678901 |-| `tracking` | The identifier given for the shipping provider \(i.e. FedEx, UPS, etc\). | 1Z999AA10123456784 |+| `tracking` | The identifier given for the shipping provider i.e. FedEx, UPS, etc. | 1Z999AA10123456784 || `shipped_at` | The time when the shipment was shipped. | 2021-07-21T14:36:00.000Z || `state` | The current state of the shipment. | `shipped` || `stock_location_id`| The ID of the Stock Location where the items for this shipment will be sourced from. | 3 |@@ -53,8 +53,8 @@ Explaining each piece of the shipment world inside of Spree separately and how eConsider you sell T-shirts to the US and Europe and ship from a single location, and you work with 2 deliverers:-* USPS Ground \(to US\)-* FedEx \(to EU\)+* USPS Ground to US+* FedEx to EUand their pricing is as follow:@@ -65,21 +65,21 @@ To achieve this setup you need the following configuration:* Shipping Categories: All your products are the same, so you only need to define one default shipping category. Each of your products would then need to be assigned to this shipping category.* 1 Stock Location: You are shipping all items from the same location, so you can use the default.-* 2 Shipping Methods \(Configuration->Shipping Methods\) as follows:+* 2 Shipping Methods Configuration->Shipping Methods as follows:| Name | Zone | Calculator || ---: | ---: | ---: |-| USPS Ground | US | Flexi Rate\($5,$2\) |-| FedEx | EU_VAT | FlatRate-per-item\($10\) |+| USPS Ground | US | Flexi Rate$5,$2 |+| FedEx | EU_VAT | FlatRate-per-item$10 |### Advanced Setup-Consider you sell products to a single zone \(US\) and you ship from 2 locations \(Stock Locations\):+Consider you sell products to a single zone US and you ship from 2 locations Stock Locations:* New York* Los Angeles-and you work with 3 deliverers \(Shipping Methods\):+and you work with 3 deliverers Shipping Methods:* FedEx* DHL@@ -112,14 +112,14 @@ USPS charges:To achieve this setup you need the following configuration:* 4 Shipping Categories: Default, Light, Regular and Heavy-* 3 Shipping Methods \(Configuration->Shipping Methods\): FedEx, DHL, USPS-* 2 Stock Locations \(Configuration->Stock Locations\): New York, Los Angeles+* 3 Shipping Methods Configuration->Shipping Methods: FedEx, DHL, USPS+* 2 Stock Locations Configuration->Stock Locations: New York, Los Angeles| S. Category / S. Method | DHL | FedEx | USPS || ---: | ---: | ---: | ---: |-| Light | Per Item \($5\) | Flat Rate \($10\) | Per Item \($8\) |-| Regular | Per Item \($5\) | Per Item \($2\) | Per Item \($8\) |-| Heavy | Per Item \($50\) | Flexi Rate\($20,$15\) | Per Item \($20\) |+| Light | Per Item $5 | Flat Rate $10 | Per Item $8 |+| Regular | Per Item $5 | Per Item $2 | Per Item $8 |+| Heavy | Per Item $50 | Flexi Rate$20,$15 | Per Item $20 |## Design & Functionality@@ -128,7 +128,7 @@ To properly leverage Spree's shipping system's flexibility you must understand a* Shipping Methods* Zones* Shipping Categories-* Calculators \(through Shipping Rates\)+* Calculators through Shipping Rates### Shipping Methods@@ -140,7 +140,7 @@ Shipping methods are the actual services used to send the product. For example:* FedEx Overnight* DHL International-Each shipping method is only applicable to a specific `Zone`. For example, you wouldn't be able to get a package delivered internationally using a domestic-only shipping method. You can't ship from Dallas, USA to Rio de Janeiro, Brazil using UPS Ground \(a US-only carrier\).+Each shipping method is only applicable to a specific `Zone`. For example, you wouldn't be able to get a package delivered internationally using a domestic-only shipping method. You can't ship from Dallas, USA to Rio de Janeiro, Brazil using UPS Ground a US-only carrier.If you are using shipping categories, these can be used to qualify or disqualify a given shipping method.@@ -154,17 +154,17 @@ The Shipping Address entered during checkout will define the zone the customer i### Shipping Categories-Shipping Categories are useful if you sell products whose shipping pricing vary depending on the type of product \(TVs and Mugs, for instance\).+Shipping Categories are useful if you sell products whose shipping pricing vary depending on the type of product TVs and Mugs, for instance.- For simple setups, where shipping for all products is priced the same \(ie. T-shirt-only shop\), all products would be assigned to the default shipping category for the store.+ For simple setups, where shipping for all products is priced the same ie. T-shirt-only shop, all products would be assigned to the default shipping category for the store.Some examples of Shipping Categories would be:-* Light \(for lightweight items like stickers\)+* Light for lightweight items like stickers* Regular-* Heavy \(for items over a certain weight\)+* Heavy for items over a certain weight-Shipping Categories are created in the admin interface \(`Configuration` -> `Shipping Categories`\) and then assigned to products \(`Products` -> `Edit`\).+Shipping Categories are created in the admin interface `Configuration` -> `Shipping Categories` and then assigned to products `Products` -> `Edit`.During checkout, the shipping categories of the products in your order will determine which calculator will be used to price its shipping for each Shipping Method.@@ -174,8 +174,8 @@ A Calculator is the component responsible for calculating the shipping price forSpree ships with 5 default Calculators:-* Flat rate \(per order\)-* Flat rate \(per item/product\)+* Flat rate per order+* Flat rate per item/product* Flat percent* Flexible rate* Price sack@@ -194,11 +194,11 @@ After entering a shipping address, the system displays the available shipping opThe customer must choose a shipping method for each shipment before proceeding to the next stage. At the confirmation step, the shipping cost will be shown and included in the order's total.- You can enable collection of extra _shipping instructions_ by setting the option \`Spree::Config.shipping_instructions\` to \`true\`. This is set to \`false\` by default. See \[Shipping Instructions\]\(\#shipping-instructions\) below.+ You can enable collection of extra _shipping instructions_ by setting the option \`Spree::Config.shipping_instructions\` to \`true\`. This is set to \`false\` by default. See \[Shipping Instructions\]\#shipping-instructions below.### What the Order's Administrator Sees-`Shipment` objects are created during checkout for an order. Initially each records just the shipping method and the order it applies to. The administrator can update the record with the actual shipping cost and a tracking code, and may also \(once only\) confirm the dispatch. This confirmation causes a shipping date to be set as the time of confirmation.+`Shipment` objects are created during checkout for an order. Initially each records just the shipping method and the order it applies to. The administrator can update the record with the actual shipping cost and a tracking code, and may also once only confirm the dispatch. This confirmation causes a shipping date to be set as the time of confirmation.## Advanced Shipping Methods@@ -224,7 +224,7 @@ Each product has a `ShippingCategory`, which adds product-specific information t* Variants and quantities* Weight and dimension information, if given, for a variant-`ShippingCategory` is basically a wrapper for a string. One use is to code up specific rates, eg. "Fixed $20" or "Fixed $40", from which a calculator could extract imposed prices \(and not go through its other calculations\).+`ShippingCategory` is basically a wrapper for a string. One use is to code up specific rates, eg. "Fixed $20" or "Fixed $40", from which a calculator could extract imposed prices and not go through its other calculations.### Variant Configurationdiff --git a/docs/developer/core-concepts/taxes.mdx b/docs/developer/core-concepts/taxes.mdxindex f6eb6d26a3..e37e2b9eea 100644--- a/docs/developer/core-concepts/taxes.mdx+++ b/docs/developer/core-concepts/taxes.mdx@@ -34,9 +34,9 @@ A `tax_category` can have many `tax_rates`, which indicate the rate at which the| `name` | The name of the tax rate. | California Sales Tax || `show_rate_in_label` | Indicates if the tax rate (8%) should be shown in the label. | `true` |-A tax rate links to a particular Zone \(see [Addresses](/developer/core-concepts/addresses) for more information about zones\). When an order is placed in a specific zone, any of the products for that order which have a tax zone that matches the order's tax zone will be taxed.+A tax rate links to a particular Zone see [Addresses](/developer/core-concepts/addresses) for more information about zones. When an order is placed in a specific zone, any of the products for that order which have a tax zone that matches the order's tax zone will be taxed.-The standard sales tax policies commonly found in the USA can be modeled as well as Value Added Tax \(VAT\) which is commonly used in Europe. These are not the only types of tax rules that you can model in Spree. Once you obtain a sufficient understanding of the basic concepts you should be able to model the tax rules of your country or jurisdiction.+The standard sales tax policies commonly found in the USA can be modeled as well as Value Added Tax VAT which is commonly used in Europe. These are not the only types of tax rules that you can model in Spree. Once you obtain a sufficient understanding of the basic concepts you should be able to model the tax rules of your country or jurisdiction.<Note>Taxation within the United States can get exceptionally complex, with different states, countries and even cities having different taxation rates. If you are shipping interstate within the United States, we would strongly advise you to use the [Spree Avatax](https://github.com/spree-contrib/spree_avatax_official) or [Spree TaxJar](https://github.com/spree-contrib/spree_taxjar) extension so that you get correct tax rates.@@ -46,7 +46,7 @@ Taxation within the United States can get exceptionally complex, with differentLet's say you need to charge 5% tax for all items that ship to New York and 6% on only clothing items that ship to Pennsylvania. This will mean you need to construct two different zones: one zone containing just the state of New York and another zone consisting of the single state of Pennsylvania.-Here's another hypothetical scenario. You would like to charge 10% tax on all electronic items and 5% tax on everything else. This tax should apply to all countries in the European Union \(EU\). In this case you would construct just a single zone consisting of all the countries in the EU. The fact that you want to charge two different rates depending on the type of good does not mean you need two zones.+Here's another hypothetical scenario. You would like to charge 10% tax on all electronic items and 5% tax on everything else. This tax should apply to all countries in the European Union EU. In this case you would construct just a single zone consisting of all the countries in the EU. The fact that you want to charge two different rates depending on the type of good does not mean you need two zones.Please see the [Addresses guide](/developer/core-concepts/addresses) for more information on constructing a zone.@@ -54,7 +54,7 @@ Here's another hypothetical scenario. You would like to charge 10% tax on all elSpree also has the concept of a default tax zone. When a user is adding items to their cart we do not yet know where the order will be shipped to, and so it's assumed that the cart is within the default tax zone until later. In some cases we may want to estimate the tax for the order by assuming the order falls within a particular tax zone.-Why might we want to do this? The primary use case for this is for countries where there is already tax included in the price. In the EU, for example, most products have a Value Added Tax \(VAT\) included in the price. There are cases where it may be desirable to show the portion of the product price that includes tax. In order to calculate this tax amount we need to know the zone \(and corresponding Tax Rate\) that was assumed in the price.+Why might we want to do this? The primary use case for this is for countries where there is already tax included in the price. In the EU, for example, most products have a Value Added Tax VAT included in the price. There are cases where it may be desirable to show the portion of the product price that includes tax. In order to calculate this tax amount we need to know the zone and corresponding Tax Rate that was assumed in the price.We may also reduce the order total by the tax amount if the order is being shipped outside the tax jurisdiction. Again, this requires us to know the zone assumed in making the original tax calculation so that the tax amount can be backed out.@@ -75,14 +75,14 @@ Spree::Config[:tax_using_ship_address] = falseIn order to charge tax in Spree you also need a `Spree::Calculator`. In most cases you should be able to use Spree's [DefaultTax calculator](https://github.com/spree/spree/blob/main/core/app/models/spree/calculator/default_tax.rb). It is suitable for both sales tax and price-inclusive tax scenarios. For more information, please read the [Calculators guide](calculators).<Note>- The `DefaultTax` calculator uses the item total \(exclusive of shipping\) when computing sales tax.+ The `DefaultTax` calculator uses the item total exclusive of shipping when computing sales tax.</Note>## Tax Types-There are two basic types of tax that a store owner might need to contend with. In the United States \(and some other countries\) store owners sometimes need to charge what is known as "sales tax." In the European Union \(EU\) and other countries stores owners need to deal with "tax inclusive" pricing which is often called Value Added Tax \(VAT\).+There are two basic types of tax that a store owner might need to contend with. In the United States and some other countries store owners sometimes need to charge what is known as "sales tax." In the European Union EU and other countries stores owners need to deal with "tax inclusive" pricing which is often called Value Added Tax VAT.-Most taxes can be considered one of these two types. For instance, in Australia customers pay a Goods and Services Tax \(GST\). This is basically equivalent to VAT in Europe.+Most taxes can be considered one of these two types. For instance, in Australia customers pay a Goods and Services Tax GST. This is basically equivalent to VAT in Europe.In some cases you may need to charge one type of tax for orders falling within one zone and another type of tax for orders falling within a different zone. There are even some rare situations where you may need to charge both types of tax in the same zone. Spree supports all of these scenarios.@@ -92,37 +92,37 @@ Sales tax is the default tax type for any tax rate in Spree.Let's take an example of a sales tax situation for the United States. Imagine that we have a zone that covers all of North America and that the zone is used for a tax rate which applies a 5% tax on products with the tax category of "Clothing".-If the customer purchases a single clothing item for $17.99 and they live in the United States \(which is within the North America zone we defined\) they are eligible to pay sales tax.+If the customer purchases a single clothing item for $17.99 and they live in the United States which is within the North America zone we defined they are eligible to pay sales tax.The sales tax calculation is $17.99 x 5% for a total tax of $0.8995, which is rounded up to two decimal places, to $0.90. This tax amount is then applied to the order as an adjustment.- See the \[Adjustments Guide\]\(/developer/core-concepts/adjustments.html\) if you need more information on adjustments.+ See the \[Adjustments Guide\]/developer/core-concepts/adjustments.html if you need more information on adjustments.-If the quantity of the item is changed to 2, then the tax amount doubles: \($17.99 x 2\) x 0.05 is $1.799, which is again rounded up to two decimal places, applying a tax adjustment of $1.80.+If the quantity of the item is changed to 2, then the tax amount doubles: $17.99 x 2 x 0.05 is $1.799, which is again rounded up to two decimal places, applying a tax adjustment of $1.80.Let's now assume that we have another product that's a coffee mug, which doesn't have the "Clothing" tax category applied to it. Let's also assume this product costs $13.99, and there's no default tax category set up for the system. Under these circumstances, the coffee mug will not be taxed when it's added to the order.-Finally, if the taxable address \(either the shipping or billing, depending on the `Spree::Config[:tax_using_ship_address]` setting\) is changed for the order to outside this taxable zone, then the tax adjustment on the order will be removed. If the address is changed back, the tax rate will be applied once more.+Finally, if the taxable address either the shipping or billing, depending on the `Spree::Config[:tax_using_ship_address]` setting is changed for the order to outside this taxable zone, then the tax adjustment on the order will be removed. If the address is changed back, the tax rate will be applied once more.### Tax Included-Many jurisdictions have what is commonly referred to as a Value Added Tax \(VAT.\) In these cases the tax is typically applied to the price. This means that prices for items are "inclusive of tax" and no additional tax needs to be applied during checkout.+Many jurisdictions have what is commonly referred to as a Value Added Tax VAT. In these cases the tax is typically applied to the price. This means that prices for items are "inclusive of tax" and no additional tax needs to be applied during checkout.In the case of tax inclusive pricing the store owner can enter all prices inclusive of tax if their home country is the default zone. If there is no default zone set, any taxes that are included in the price will be added to the net prices on the fly depending on the current order's tax zone.-If the current order's tax zone is outside the default zone, prices will be shown and used with only the included taxes for that zone applied. If there is no VAT for that zone \(for example when the current order's shipping address is outside the EU\), the net price will be shown and used.+If the current order's tax zone is outside the default zone, prices will be shown and used with only the included taxes for that zone applied. If there is no VAT for that zone for example when the current order's shipping address is outside the EU, the net price will be shown and used.- Keep in mind that each order records the price a customer paid \(including the tax\) as part of the line item record. This means you don't have to worry about changing prices or tax rates affecting older orders.+ Keep in mind that each order records the price a customer paid including the tax as part of the line item record. This means you don't have to worry about changing prices or tax rates affecting older orders.-When tax is included in the price there is no order adjustment needed \(unlike the sales tax case\). Stores are, however, typically interested in showing the amount of tax the user paid. These totals are for informational purposes only and do not affect the order total.+When tax is included in the price there is no order adjustment needed unlike the sales tax case. Stores are, however, typically interested in showing the amount of tax the user paid. These totals are for informational purposes only and do not affect the order total.-Let's start by looking at an example where there is a 5% included on all products and it's included in the price. We'll further assume that this tax should only apply to orders within the United Kingdom \(UK\).+Let's start by looking at an example where there is a 5% included on all products and it's included in the price. We'll further assume that this tax should only apply to orders within the United Kingdom UK.In the case where the order address is within the UK and we purchase a single clothing item for £17.99 we see an order total of £17.99. The tax rate adjustment applied is £17.99 x 5%, which is £0.8995, and that is rounded up to two decimal places, becoming £0.90.Now let's increase the quantity on the item from 1 to 2. The order total changes to £35.98 with a tax total of £1.799, which is again rounded up to now being £1.80.-Next we'll add a different clothing item costing £19.99 to our order. Since both items are clothing and taxed at the same rate, they can be reduced to a single total, which means there's a single adjustment still applied to the order, calculated like this: \(£17.99 + £19.99\) x 0.05 = £1.899, rounded up to two decimal places: £1.90.+Next we'll add a different clothing item costing £19.99 to our order. Since both items are clothing and taxed at the same rate, they can be reduced to a single total, which means there's a single adjustment still applied to the order, calculated like this: £17.99 + £19.99 x 0.05 = £1.899, rounded up to two decimal places: £1.90.Now let's assume an additional tax rate of 10% on a "Consumer Electronics" tax category. When we add a product with this tax category to our order with a price of £16.99, there will be a second adjustment added to the order, with a calculated total of £16.99 x 10%, which is £1.699. Rounded up, it's £1.70.@@ -140,6 +140,6 @@ As of January 1st, 2015, digital products sold within the EU must have the VAT o4. Add tax rates that are "included in tax" for the tax category "Physical goods" for all EU countries.5. Add two tax rates for the tax category "Physical products": 1. One for your home country, with your home country's VAT 2. One for the rest of the EU, also with your home country's VAT-If you change the tax zone of the current order \(by changing the relevant address\), prices will now be shown and used including the correct VAT for the current order.+If you change the tax zone of the current order by changing the relevant address, prices will now be shown and used including the correct VAT for the current order.All of the examples in this guide are meant to be used for illustrative purposes. They are not meant to be used as definitive interpretations of tax law. You should consult your accountant or attorney for guidance on how much tax to collect and under what circumstances.\ No newline at end of filediff --git a/docs/developer/customization/authentication.mdx b/docs/developer/customization/authentication.mdxindex e78a374982..72f85ca772 100644--- a/docs/developer/customization/authentication.mdx+++ b/docs/developer/customization/authentication.mdx@@ -29,18 +29,18 @@ To use your own authentication system with Spree, please follow these steps:</Accordion><Accordion title="2. Generate Spree Authentication Helpers">- Next, you need to run the custom user generator for Spree which will create two files. The first is a migration that will add the necessary Spree fields to your users table, and the second is an extension \(that lives at `lib/spree/authentication_helpers.rb`\) to the `Spree::Core::AuthenticationHelpers` module inside of Spree.+ Next, you need to run the custom user generator for Spree which will create two files. The first is a migration that will add the necessary Spree fields to your users table, and the second is an extension that lives at `lib/spree/authentication_helpers.rb` to the `Spree::Core::AuthenticationHelpers` module inside of Spree.Run this generator with this command:```bash- bundle exec rails g spree:custom_user User+ bin/rails g spree:custom_user User```This will tell the generator that you want to use the `User` class as the class that represents users in Spree. Run the new migration by running this:```bash- bundle exec rails db:migrate+ bin/rails db:migrate```Next you will need to define some methods to tell Spree where to find your application's authentication routes.diff --git a/docs/developer/customization/checkout.mdx b/docs/developer/customization/checkout.mdxindex 8028cd690d..1e85f35891 100644--- a/docs/developer/customization/checkout.mdx+++ b/docs/developer/customization/checkout.mdx@@ -1,22 +1,49 @@---title: Checkout Flow-section: customization-order: 5+description: Learn how to customize the checkout process in Spree.----# Checkout+## OverviewThe 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 customization of the flow of the checkout can be done by using Spree's `checkout_flow` DSL, described in the [Checkout Flow DSL](checkout#the-checkout-flow-dsl) section below.+## 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 StepsThe 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\)+* 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\)+* Delivery Options Shipping Method* Payment* Confirmation@@ -24,9 +51,13 @@ The following sections will provide a walk-through of checkout from a user's per### 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 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:+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@@ -37,29 +68,31 @@ The method is defined like this:```rubydef check_registrationreturn unless Spree::Auth::Config[:registration_step]- return if spree_current_user or current_order.email+ return if spree_current_user || current_order.emailstore_locationredirect_to spree.checkout_registration_pathend```-The configuration of the guest checkout option is done via [Preferences](/developer/core-concepts/preferences). Spree will allow guest checkout by default. Use the `allow_guest_checkout` preference to change the default setting.+#### Disabling guest checkout-### Address Information+To completely disable guest checkout and require registration for checkout, you need to change Spree configuration in `config/initializers/spree.rb`:-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. Selecting this option will have the effect of hiding the shipping address fields using JavaScript. If users have disabled JavaScript, the section will not disappear but it will copy over the address information once submitted. If you would like to automatically copy the address information via JavaScript on the client side, that is an exercise left to the developer. We have found the server side approach to be simpler and easier to maintain.+```ruby+Spree::Config[:allow_guest_checkout] = false+```-The address fields include a select box for choosing state/province. The list of states will be populated via JavaScript and will contain all of the states listed in the database for the currently selected country. If there are no states configured for a particular country, or if the user has JavaScript disabled, the select box will be replaced by a text field instead.+### Address Information- The default "seed" data for Spree only includes the U.S. states. It's easy enough to add states or provinces for other countries but beyond the scope of the Spree project to maintain such a list.+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 state field can be disabled entirely by using the \`Spree::Config\[:address_requires_state\]\` preference. You can also allow for an "alternate phone" field by using the \`Spree::Config\[:alternative_shipping_phone\]\` and \`Spree::Config\[:alternative_shipping\]\` fields.+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 an extension 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). 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. This is one of the reasons why it is difficult to support single page checkout for customers who have disabled JavaScript.+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@@ -79,95 +112,102 @@ For more information about payments, please see the [Payments guide](/developer/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 \(except for payment methods that support payment profiles\), but can be enabled by overriding the `confirmation_required?` method in `Spree::Order`.--## Checkout Architecture--The following is a detailed summary of the checkout architecture. A complete understanding of this architecture will allow you to be able to customize the checkout process to handle just about any scenario you can think of. Feel free to skip this section and come back to it later if you require a deeper understanding of the design in order to customize your checkout.--### The Order Model and State Machine--The `Spree::Order` state machine is the foundation of the checkout process. Spree makes use of the [state_machines](https://github.com/state-machines/state_machines) gem in the `Spree::Order` model as well as in several other places \(such as `Spree::Shipment` and `Spree::InventoryUnit`.\)+This step is disabled by default, but can be enabled by two ways:-The default checkout flow for the `Spree::Order` model is defined in `app/models/spree/order/checkout.rb` of spree_core.+1. globally for all orders by setting a preference in `config/initializers/spree.rb`:-An `Spree::Order` object has an initial state of 'cart'. From there any number of events transition the `Spree::Order` to different states. Spree does not have a separate model or database table for the shopping cart. What the user considers a "shopping cart" is actually an in-progress `Spree::Order`. An order is considered in-progress, or incomplete when its `completed_at` attribute is `nil`. Incomplete orders can be easily filtered during reporting and it's also simple enough to write a quick script to periodically purge incomplete orders from the system. The end result is a simplified data model along with the ability for store owners to search and report on incomplete/abandoned orders.+ ```ruby+ Spree::Config[:always_include_confirm_step] = true+ ```- For more information on the state machines gem please see the \[README\]\(https://github.com/state-machines/state_machines\)+2. conditionally for specific orders by overriding the `confirmation_required?` method in `Spree::Order`, eg.-## Checkout Customization+ ```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+ ```-It is possible to override the default checkout workflow to meet your store's needs.--### Adding Logic Before or After a Particular Step+## Adding Logic Before or After a Particular StepThe [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-Spree::Order.state_machine.before_transition to: :delivery, do: :valid_zip_code?+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.-## The Checkout Flow DSL+## Modifying the checkout flow-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.+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 default checkout flow for Spree is defined like this, adequately demonstrating the abilities of this new system:+The `insert_checkout_step` method takes a `before` or `after` option to determine where to insert the step:```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.--### Modifying the checkout flow--To add or remove steps to the checkout flow, you can use the `insert_checkout_step` and `remove_checkout_step` helpers respectively.--The `insert_checkout_step` takes a `before` or `after` option to determine where to insert the step:--```ruby-insert_checkout_step :new_step, before: :address-# or-insert_checkout_step :new_step, after: :address+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-remove_checkout_step :address-remove_checkout_step :delivery+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.+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-checkout_flow do- go_to_state :payment- go_to_state :complete+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```-diff --git a/docs/developer/customization/decorators.mdx b/docs/developer/customization/decorators.mdxnew file mode 100644index 0000000000..8b024b2152--- /dev/null+++ b/docs/developer/customization/decorators.mdx@@ -0,0 +1,145 @@+---+title: Decorators+description: Decorators allow you to add behavior to Spree classes in your application.+---++<Warning>+ It is highly recommended to use [Dependencies](dependencies) instead of decorators. Decorators should be used as a last resort. They can make upgrading Spree more difficult.+</Warning>++## Overview++All of Spree's models, controllers, helpers, etc can easily be extended or overridden to meet your exact requirements using standard Ruby idioms.++Standard practice for including such changes in your application or extension is to create a file within the relevant **app/models/spree** or **app/controllers/spree** directory with the original class name with **_decorator** appended.++## Decorating Models++### Changing behavior of existing methods++Changing the behavior of existing methods is the most common use case for decorators.++Let's say you want to change the behavior of the `available?` in the [Product](https://github.com/spree/spree/blob/master/core/app/models/spree/product.rb) model.++1. Let's start with creating a file in `app/models/spree/product_decorator.rb`++ ```bash+ mkdir -p app/models/spree && touch app/models/spree/product_decorator.rb+ ```++2. And add the following code to the file:++ ```ruby+ module Spree+ module ProductDecorator+ def available?+ # your code here+ end+ end++ Product.prepend(ProductDecorator)+ end+ ```++### Adding a new method to the model++You can also add a new method to the model. Or even add validations or any other rails magic methods, see example below.++```ruby+module Spree+ module ProductDecorator+ def self.prepended(base)+ base.before_validation :strip_whitespaces+ end++ protected++ def strip_whitespaces+ self.name = name.strip+ end+ end++ Product.prepend(ProductDecorator)+end+```++### Adding new associations to Spree models++Assume you want to add a new model called `Video` associated to `Spree::Product`. Let's start with creating a database migration:++```bash+bin/rails g migration CreateVideos url:string product:references+bin/rails db:migrate+```++In the model code add the association to `Spree::Product`:++```ruby+class Video < ApplicationRecord+ belongs_to :product, class_name: 'Spree::Product'++ has_one_attached :video_file+end+```++Finally add the association in `ProductDecorator` in `app/models/spree/product_decorator.rb`:++```ruby+module Spree+ module ProductDecorator+ def self.prepended(base)+ base.has_many :videos, class_name: 'Video', foreign_key: 'product_id', dependent: :destroy+ end+ end++ Product.prepend(ProductDecorator)+end+```++## Decorating Controllers++Adding a custom action to the [ProductsController](https://github.com/spree/spree/blob/master/frontend/app/controllers/spree/products_controller.rb)++1. Create a file in `app/controllers/spree/products_controller_decorator.rb`++ ```bash+ mkdir -p app/controllers/spree && touch app/controllers/spree/products_controller_decorator.rb+ ```++2. Add the following code:++ ```ruby+ module Spree+ module ProductsControllerDecorator+ def some_action+ # your code here+ end+ end++ ProductsController.prepend(ProductsControllerDecorator)+ end+ ```++The exact same format can be used to redefine an existing method.++### Accessing Product Data++If you extend the Products controller with a new method, you may very well want to access product data in that method. You can do so by using the `:load_data before_action`.++```ruby+module Spree+ module ProductsControllerDecorator+ def self.prepended(base)+ base.before_action :load_data, only: :some_action+ end++ def some_action+ # your code here+ end+ end++ ProductsController.prepend(ProductsControllerDecorator)+end+```++`:load_data` will use `params[:id]` to lookup the product by its permalink.\ No newline at end of filediff --git a/docs/developer/customization/deface_overrides_tutorial.mdx b/docs/developer/customization/deface_overrides_tutorial.mdxindex 4f06868cc0..ea490fa8f7 100644--- a/docs/developer/customization/deface_overrides_tutorial.mdx+++ b/docs/developer/customization/deface_overrides_tutorial.mdx@@ -6,12 +6,12 @@ section: advanced# Deface<Warning>-Using Deface is no longer recommended+Using Deface is no longer recommended, we strongly encourage you to use other ways to customize Spree.</Warning>## What is Deface?-Deface is a standalone Rails library that enables you to customize Erb templates without needing to directly edit the underlying view file. Deface allows you to use standard CSS3 style selectors to target any element \(including Ruby blocks\), and perform an action against all the matching elements.+Deface is a standalone Rails library that enables you to customize Erb templates without needing to directly edit the underlying view file. Deface allows you to use standard CSS3 style selectors to target any element including Ruby blocks, and perform an action against all the matching elements.## Improving Our Extension Using Deface@@ -31,7 +31,7 @@ First, let's create the overrides directory with the following command:mkdir app/overrides```-So we want to override `spree/admin/products/_form.html.erb`. Here is the part of the file we are going to add content to \(you can also view the [full file](https://github.com/spree/spree/blob/master/backend/app/views/spree/admin/products/_form.html.erb)\):+So we want to override `spree/admin/products/_form.html.erb`. Here is the part of the file we are going to add content to you can also view the [full file](https://github.com/spree/spree/blob/master/backend/app/views/spree/admin/products/_form.html.erb):```erb<div class="right four columns omega" data-hook="admin_product_form_right">@@ -71,11 +71,11 @@ module Spreeend```-Now, when we head to `http://localhost:3000/admin/products` and edit a product, we should be able to set a sale price for the product and be able to view it on our sale page, `http://localhost:3000/sale`. Note that you will likely need to restart our example Spree application \(created in the [Getting Started tutorial](../getting-started/installation)\).+Now, when we head to `http://localhost:3000/admin/products` and edit a product, we should be able to set a sale price for the product and be able to view it on our sale page, `http://localhost:3000/sale`. Note that you will likely need to restart our example Spree application created in the [Getting Started tutorial](../getting-started/installation).### Available actions-Deface applies an **action** to element\(s\) matching the supplied CSS selector. These actions are passed when defining a new override are supplied as the key while the CSS selector for the target element\(s\) is the value, for example:+Deface applies an **action** to elements matching the supplied CSS selector. These actions are passed when defining a new override are supplied as the key while the CSS selector for the target elements is the value, for example:```rubyremove: "p.junk"@@ -114,9 +114,9 @@ Deface supports three options for supplying content to be used by an override:### Targeting elements-While Deface allows you to use a large subset of CSS3 style selectors \(as provided by Nokogiri\), the majority of Spree's views have been updated to include a custom HTML attribute \(data-hook\), which is designed to provide consistent targets for your overrides to use.+While Deface allows you to use a large subset of CSS3 style selectors as provided by Nokogiri, the majority of Spree's views have been updated to include a custom HTML attribute data-hook, which is designed to provide consistent targets for your overrides to use.-As Spree views are changed over coming versions, the original HTML elements maybe edited or be removed. We will endeavour to ensure that data-hook / id combination will remain consistent within any single view file \(where possible\), thus making your overrides more robust and upgrade proof.+As Spree views are changed over coming versions, the original HTML elements maybe edited or be removed. We will endeavour to ensure that data-hook / id combination will remain consistent within any single view file where possible, thus making your overrides more robust and upgrade proof.For example, spree/products/show.html.erb looks as follows:@@ -202,7 +202,7 @@ You can also use a combination of both styles of selectors in a single override### Targeting ruby blocks-Deface evaluates all the selectors passed against the original erb view contents \(and importantly not against the finished / generated HTML\). In order for Deface to make ruby blocks contained in a view parseable they are converted into a pseudo markup as follows.+Deface evaluates all the selectors passed against the original erb view contents and importantly not against the finished / generated HTML. In order for Deface to make ruby blocks contained in a view parseable they are converted into a pseudo markup as follows.Given the following Erb file:diff --git a/docs/developer/customization/dependencies.mdx b/docs/developer/customization/dependencies.mdxindex 2998b85e38..e6ff67c571 100644--- a/docs/developer/customization/dependencies.mdx+++ b/docs/developer/customization/dependencies.mdx@@ -1,14 +1,71 @@----title: Dependency system+title: Dependenciessection: customization-order: 3----# Dependencies-## Overview-With Dependencies, you can easily replace parts of Spree internals with your custom classes. You can replace [Services](https://github.com/spree/spree/tree/master/core/app/services/spree), Abilities, and [Serializers](https://github.com/spree/spree/tree/master/api/app/serializers/spree/v2). More will come in the future.+With Dependencies, you can easily replace parts of Spree core with your custom classes. You can replace [Services](https://github.com/spree/spree/tree/master/core/app/services/spree), CanCanCan Abilities (user for [Permissions](permissions)), and [API Serializers](https://github.com/spree/spree/tree/master/api/app/serializers/spree/v2) (used for generating JSON API responses).++We plan to expand this feature to include more classes in the future.++## Application (global) customization++This will change every aspect of the application (both APIs, Admin Panel, and default Rails frontend if you're using it).++In your `config/initializers/spree.rb` file, you can set the following:++```ruby+Spree::Dependencies.cart_add_item_service = 'MyAddToCartService'+```++or++```ruby+Spree.dependencies do |dependencies|+ dependencies.cart_add_item_service = 'MyAddToCartService'+end+```++Now let's create your custom service.++```bash+mkdir app/services -f && touch app/services/my_add_to_cart_service.rb+```++And add the following code to it:++```ruby+module MyAddToCartService < Spree::Cart::AddItem+ def call(order:, variant:, quantity: nil, public_metadata: {}, private_metadata: {}, options: {})+ ApplicationRecord.transaction do+ run :add_to_line_item+ run Spree::Dependencies.cart_recalculate_service.constantize+ run :send_notification+ end+ end++ private++ def send_notification(new_order_line_item)++ end+end+```++This code will:++1. Inherit from `Spree::Cart::AddItem`+2. Override the `call` method to add your custom logic+3. Call `run :add_to_line_item` to add the item to the cart+4. Call `run Spree::Dependencies.cart_recalculate_service.constantize` to recalculate the cart+5. Call `run :send_notification` to send a notification++<Warning>+Values set in the initializer have to be strings, eg. `'MyNewAwesomeAddItemToCart'`+</Warning>++## Controller level customization@@ -49,24 +106,6 @@ Spree::Api::Dependencies.storefront_cart_add_item_service = 'MyNewAwesomeAddItemThis will swap the default Cart serializer and Add Item to Cart service for your custom ones within all Storefront API endpoints that use those classes.-Values set in the initializer have to be strings, eg. \`'MyNewAwesomeAddItemToCart'\`--## Application (global) customization--You can also inject classes globally into the entire Spree stack. Be careful about this though as this touches every aspect of the application (both APIs, Admin Panel, and default Rails frontend if you're using it).--```ruby-Spree::Dependencies.cart_add_item_service = 'MyNewAwesomeAddItemToCart'-```--or--```ruby-Spree.dependencies do |dependencies|- dependencies.cart_add_item_service = 'MyNewAwesomeAddItemToCart'-end-```-You can mix and match both global and API-level customizations:```ruby@@ -76,8 +115,6 @@ Spree::Api::Dependencies.storefront_cart_add_item_service = 'AnotherAddItemToCarThe second line will have precedence over the first one, and the Storefront API will use `AnotherAddItemToCart` and the rest of the application will use `MyNewAwesomeAddItemToCart`-Values set in the initializer have to be strings, eg. `'MyNewAwesomeAddItemToCart'`-## Default valuesBy default values can be easily checked by looking at the source code of Dependencies classes:diff --git a/docs/developer/customization/emails.mdx b/docs/developer/customization/emails.mdxindex 13432f3779..b75c875bde 100644--- a/docs/developer/customization/emails.mdx+++ b/docs/developer/customization/emails.mdx@@ -15,7 +15,7 @@ Spree uses [postmark templates](https://github.com/wildbit/postmark-templates),Spree offers an emails preview generator for development purposes. To generate them, use the command:```bash-bundle exec rails g spree:emails:install+bin/rails g spree:emails:install```After that, start the rails server locally and go to: `localhost:3000/rails/mailers`diff --git a/docs/developer/customization/images.mdx b/docs/developer/customization/images.mdxindex 73e86fca4b..965128c038 100644--- a/docs/developer/customization/images.mdx+++ b/docs/developer/customization/images.mdx@@ -6,9 +6,16 @@ title: ImagesThis guide explains how to change Product Images dimensions and different storage options for [ActiveStorage](https://edgeguides.rubyonrails.org/active_storage_overview.html) which is the default attachment storage system in Spree.-### Image dimensions-To change the default image dimensions or add new ones you need to create a decorator file `app/models/spree/image_decorator.rb`:+## Dimensions++To change the default image dimensions or add new ones you need to create a decorator file:++```bash+mkdir -p app/models/spree && touch app/models/spree/image_decorator.rb+```++with the following content:```rubymodule Spree@@ -16,10 +23,13 @@ module Spreemodule ClassMethodsdef styles{+ # change existing default sizes used in Admin Panel and APImini: '48x48>',small: '100x100>',product: '240x240>',- large: '600x600>',+ large: '600x600>',+ # add your new size here, which will be automatically available in the API+ my_custom_size: '1000x1000>'}endend@@ -34,15 +44,42 @@ module Spreeend```-You can also create image variations on the fly in your templates, eg.+## Using image variations in templates++You can also create [image variations on the fly in your templates](https://guides.rubyonrails.org/active_storage_overview.html), eg.```erb<%= image_tag(main_app.url_for(@product.images.first.attachment.variant(resize: '150x150'))) %>```-### Using Amazon S3 as storage system+## Storage service-Please refer to the official [Active Storage documentation](https://guides.rubyonrails.org/active_storage_overview.html#amazon-s3-service)+By default Spree will use the storage service you have set in your environment file eg. `config/environments/development.rb`:-You can also use [Microsoft Azure Storage](https://guides.rubyonrails.org/active_storage_overview.html#microsoft-azure-storage-service) or [Google Cloud Storage](https://guides.rubyonrails.org/active_storage_overview.html#google-cloud-storage-service)+```ruby+config.active_storage.service = :amazon+```++If you have multiple storage services you can customize which storage service to use for images. This is done in the `config/initializers/spree.rb`:++```ruby+Spree.public_storage_service_name = :amazon+```+The storage name needs to match the name you configured in `config/storage.yml`.++## Using CDNs++To use a CDN service such as AWS Cloudfront or Cloudflare, you need to set `Spree.cdn_host` to the hostname of your CDN service. This is done in the `config/initializers/spree.rb`:++```ruby+Spree.cdn_host = 'https://mycloudfrontserviceid.cloudfront.net'+```++Spree will handle the rest as we have a built-in reverse proxy for ActiveStorage.++To use CDN in your templates please use `cdn_image_url` helper:++```erb+<%= main_app.cdn_image_url(@product.images.first.attachment.variant(resize: '150x150')) %>+```diff --git a/docs/developer/customization/logic.mdx b/docs/developer/customization/logic.mdxindex 7d797e6f36..258fd05142 100644--- a/docs/developer/customization/logic.mdx+++ b/docs/developer/customization/logic.mdx@@ -12,7 +12,7 @@ It is highly recommended to use [Dependencies](dependencies) and [Extensions](..## Extending Classes-All of Spree's business logic \(models, controllers, helpers, etc\) can easily be extended or overridden to meet your exact requirements using standard Ruby idioms.+All of Spree's business logic models, controllers, helpers, etc can easily be extended or overridden to meet your exact requirements using standard Ruby idioms.Standard practice for including such changes in your application or extension is to create a file within the relevant **app/models/spree** or **app/controllers/spree** directory with the original class name with **_decorator** appended.@@ -47,8 +47,8 @@ endAssume you want to add a new model called `Video` associated to `Spree::Product`. Let's start with creating a database migration:```bash-bundle exec rails g migration CreateVideos url:string product:references-bundle exec rails db:migrate+bin/rails g migration CreateVideos url:string product:references+bin/rails db:migrate```Add new model to `app/models/videos.rb`:diff --git a/docs/developer/customization/permissions.mdx b/docs/developer/customization/permissions.mdxindex 37034a387f..11196b2ccf 100644--- a/docs/developer/customization/permissions.mdx+++ b/docs/developer/customization/permissions.mdx@@ -22,7 +22,7 @@ For authorization Spree uses [CanCanCan](https://github.com/CanCanCommunity/canc## Adding custom permissions-Let's assume you would like to add a new Role `customer_service` with some limited access to Admin Panel \(only Orders section\).+Let's assume you would like to add a new Role `customer_service` with some limited access to Admin Panel only Orders section.Create a new file called `app/models/customer_service_ability.rb`@@ -56,7 +56,7 @@ end## Replacing all permissions-As we've mentioned earlier, Spree uses the main Ability class. You can change that to use your own custom Ability class via [Dependencies](dependencies) in Spree initializer \(`config/initializers/spree.rb`\), eg.+As we've mentioned earlier, Spree uses the main Ability class. You can change that to use your own custom Ability class via [Dependencies](dependencies) in Spree initializer `config/initializers/spree.rb`, eg.```rubySpree::Dependencies.ability_class = 'CustomAbility'diff --git a/docs/developer/customization/quickstart.mdx b/docs/developer/customization/quickstart.mdxindex 8a26467937..7f339c9031 100644--- a/docs/developer/customization/quickstart.mdx+++ b/docs/developer/customization/quickstart.mdx@@ -8,8 +8,8 @@ Spree is a very flexible platform allowing you to customize every part of it, toThere are several ways you can achieve this:<AccordionGroup>- <Accordion title="Admin Panel">- There's a lot of Store settings you can change in the admin panel.+ <Accordion title="Store settings">+ There's a lot of Store settings you can change in the admin panel without touching the code.Changing currency, shipping zones, languages - it's very easy to do.@@ -55,4 +55,62 @@ There are several ways you can achieve this:end```</Accordion>++ <Accordion title="Authentication">+ Spree allows you to use your own authentication system.++ To do this, you need to create a new authentication system and configure Spree to use it.++ 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.++ Please see [Checkout flow customization section](checkout) for more information.+ </Accordion>++ <Accordion title="Dependencies">+ Spree allows you to swap core classes and services with your own, eg. you want to handle adding to cart differently.++ In your `config/initializers/spree.rb` file, you can set the following:++ ```ruby+ Spree::Dependencies.cart_add_item_service = "MyCartAddItemService"+ ```++ which would use `MyCartAddItemService` to handle adding to cart.++ You can find more information in the [Dependencies](dependencies) section.+ </Accordion>++ <Accordion title="Decorators">+ Decorators allow you to add behavior to Spree classes in your application. We're using a neat feature of Ruby language called [Module.prepend](https://ruby-doc.org/core-2.6.3/Module.html#method-i-prepend) to add the behavior to the model.++ For example, to add a method that returns the product name in uppercase, you would add the following to your decorator:++ ```ruby+ module Spree+ module ProductDecorator+ def custom_name+ name.upcase+ end+ end++ Product.prepend(ProductDecorator)+ end+ ```++ <Warning>+ Decorators should be used as a last resort. They can make upgrading Spree more difficult.+ </Warning>++ Please see [Decorators](decorators) section for more information.+ </Accordion></AccordionGroup>diff --git a/docs/developer/deployment/aws.mdx b/docs/developer/deployment/aws.mdxindex 9b5a750fe3..7b9f105d79 100644--- a/docs/developer/deployment/aws.mdx+++ b/docs/developer/deployment/aws.mdx@@ -1,18 +1,15 @@---title: Amazon Web Services (AWS)section: deployment-order: 0----# AWS-Amazon Web Services offers reliable, scalable, and inexpensive cloud computing services. Free to join, pay only for what you use.AWS is also one of the most popular choices for hosting a Spree application. There are several services you can use to host Spree on AWS, here we briefly touch upon those options.## AWS Elastic Beanstalk-The easiest way to run Spree or any other Ruby on Rails application on AWS is through AWS Elastic Beanstalk which is comparable to Heroku PaaS \(Platform as a Service\).+The easiest way to run Spree or any other Ruby on Rails application on AWS is through AWS Elastic Beanstalk which is comparable to Heroku PaaS Platform as a Service.This is the recommended approach if you're just starting up. Please follow [Beanstalk Deployment guide](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/ruby-rails-tutorial.html) for more details.@@ -29,8 +26,6 @@ This is more advanced than Beanstalk and will require DevOps knowledge. For buil## Recommended AWS services* [AWS S3](https://aws.amazon.com/s3/) - object storage service to store and read your uploaded files such as Product images, etc. We **do not recommend** keeping your uploads on the same instance as the application.-* [AWS RDS](https://aws.amazon.com/rds/) - Amazon Relational Database Service \(Amazon RDS\) makes it easy to set up, operate, and scale a relational database in the cloud. Spree works great with multiple databases: [Amazon Aurora \(both MySQL and PostgreSQL variants\)](https://aws.amazon.com/rds/aurora/), [RDS PostgreSQL](https://aws.amazon.com/rds/postgresql/), [RDS MySQL](https://aws.amazon.com/rds/mysql/) and [RDS MariaDB](https://aws.amazon.com/rds/mariadb/)+* [AWS RDS](https://aws.amazon.com/rds/) - Amazon Relational Database Service Amazon RDS makes it easy to set up, operate, and scale a relational database in the cloud. Spree works great with multiple databases: [Amazon Aurora both MySQL and PostgreSQL variants](https://aws.amazon.com/rds/aurora/), [RDS PostgreSQL](https://aws.amazon.com/rds/postgresql/), [RDS MySQL](https://aws.amazon.com/rds/mysql/) and [RDS MariaDB](https://aws.amazon.com/rds/mariadb/)* [AWS ElastiCache Redis](https://aws.amazon.com/elasticache/redis/?nc=sn&loc=2&dn=1) - we recommend setting up a Redis database for the [Active Job background queue](https://guides.rubyonrails.org/active_job_basics.html), which we use for sending out transactional emails-* [AWS ElastiCache Memcached](https://aws.amazon.com/elasticache/memcached/?nc=sn&loc=2&dn=1) - we recommend using [Memcached as cache storage](https://guides.rubyonrails.org/caching_with_rails.html) to increase the performance and scalability of your Spree application-* [AWS CloudFront](https://aws.amazon.com/cloudfront/) - fast content delivery network \(CDN\) to speed up your asset \(images/stylesheets/javascript\) delivery. This will greatly enhance your application responsiveness.-+* [AWS CloudFront](https://aws.amazon.com/cloudfront/) - fast content delivery network CDN to speed up your asset images/stylesheets/javascript delivery. This will greatly enhance your application responsiveness.diff --git a/docs/developer/deployment/heroku.mdx b/docs/developer/deployment/heroku.mdxindex ef1b5b8639..a464db7387 100644--- a/docs/developer/deployment/heroku.mdx+++ b/docs/developer/deployment/heroku.mdx@@ -20,7 +20,7 @@ We recommend you start and stick to Heroku if you do not have DevOps-skilled teaThere are 2 types of dynos:-* **Web** - for running the web interface of yuour Store \(Storefront, API, Admin Panel\)+* **Web** - for running the web interface of yuour Store Storefront, API, Admin Panel* **Worker** - for running background jobs via [Active Job](https://guides.rubyonrails.org/active_job_basics.html) such as email send out, report generation, etc### Recommended sizing@@ -45,7 +45,7 @@ There are 2 types of dynos:| Memcached Cloud | Free | 1 GB || Papertrail | Choklad | Fixa || Redis Cloud | Free | 250 MB |-| Scout APM | Free | Free \(small traffic\) or Eldora \(medium traffic\) |+| Scout APM | Free | Free small traffic or Eldora medium traffic || Sendgrid | Free | Bronze || Sentry | Free | Small |diff --git a/docs/developer/deployment/performance.mdx b/docs/developer/deployment/performance.mdxindex 1d58123874..f97c2b36fd 100644--- a/docs/developer/deployment/performance.mdx+++ b/docs/developer/deployment/performance.mdx@@ -24,7 +24,7 @@ There are several configuration options you can put in `config/initializers/spreSpree::Api::Config[:api_v2_cache_ttl] = 3600 # TTL for cached resources in seconds```-This is the time when API objects will be available in cache storage. Objects such as Products also auto-expire when they are updated or one of their associated resources \(eg. Variants\) are updated also.+This is the time when API objects will be available in cache storage. Objects such as Products also auto-expire when they are updated or one of their associated resources eg. Variants are updated also.### Background jobsdiff --git a/docs/developer/extending-spree/3rd-party-extensions.mdx b/docs/developer/extending-spree/3rd-party-extensions.mdxindex 70263323e5..e2aa2f7642 100644--- a/docs/developer/extending-spree/3rd-party-extensions.mdx+++ b/docs/developer/extending-spree/3rd-party-extensions.mdx@@ -45,7 +45,7 @@ description: >-title="Analytics Trackers"href="https://github.com/spree-contrib/spree_analytics_trackers">- Adds support for Analytics Trackers \(Google Analytics & Segment\).+ Adds support for Analytics Trackers Google Analytics & Segment.</Card><Cardtitle="MailChimp E-Commerce"@@ -114,13 +114,13 @@ description: >-title="Volume Pricing"href="https://github.com/spree-contrib/spree_volume_pricing">- Spree extension which supports sales volume-based pricing \(quantity discounts\).+ Spree extension which supports sales volume-based pricing quantity discounts.</Card><Cardtitle="Products Q&A"href="https://github.com/TruemarkDev/spree_products_qa">- Q&A Sections for products. Logged in users can ask a question, and then admins are able to answer it. All answered \(and accepted\) questions are displayed on a product page.+ Q&A Sections for products. Logged in users can ask a question, and then admins are able to answer it. All answered and accepted questions are displayed on a product page.</Card></Accordion>@@ -168,7 +168,7 @@ description: >-title="Avatax"href="https://github.com/spree-contrib/spree_avatax_official">- The new officially certified Spree Avatax \(Avalara\) extension.+ The new officially certified Spree Avatax Avalara extension.</Card><Cardtitle="TaxJar"diff --git a/docs/developer/customization/api_v2.mdx b/docs/developer/extending-spree/api_v2.mdxsimilarity index 100%rename from docs/developer/customization/api_v2.mdxrename to docs/developer/extending-spree/api_v2.mdxdiff --git a/docs/developer/security/authentication_and_authorization.mdx b/docs/developer/security/authentication_and_authorization.mdxindex a7e3636792..d77247cf67 100644--- a/docs/developer/security/authentication_and_authorization.mdx+++ b/docs/developer/security/authentication_and_authorization.mdx@@ -9,20 +9,20 @@ order: 2If you install spree_auth_devise when setting up your app, we use a third party authentication library for Ruby known as [Devise](https://github.com/plataformatec/devise). This library provides a host of useful functionality that is in turn available to Spree, including the following features:* Authentication-* Strong password encryption \(with the ability to specify your own algorithms\)+* Strong password encryption with the ability to specify your own algorithms* "Remember Me" cookies* "Forgot my password" emails-* Token-based/oAuth 2.0 access \(for REST API\)+* Token-based/oAuth 2.0 access for REST API## Devise Configuration- A default Spree install comes with the \[Spree Auth Devise\]\(https://github.com/spree/spree_auth_devise\) gem, which provides authentication for Spree using Devise. This section of the guide covers the default setup. If you're using your own authentication, please consult the manual for that authentication engine.+ A default Spree install comes with the \[Spree Auth Devise\]https://github.com/spree/spree_auth_devise gem, which provides authentication for Spree using Devise. This section of the guide covers the default setup. If you're using your own authentication, please consult the manual for that authentication engine.We have configured Devise to handle only what is needed to authenticate with a Spree site. The following details cover the default configurations:* Passwords are stored in the database encrypted with the salt.* User authentication is done through the database query.-* User registration is enabled and the user's login is available immediately \(no validation emails\).+* User registration is enabled and the user's login is available immediately no validation emails.* There is a remember me and password recovery tool built in and enabled through Devise.These configurations represent a reasonable starting point for a typical e-commerce site. Devise can be configured extensively to allow for a different feature set but that is currently beyond the scope of this document. Developers are encouraged to visit the [Devise wiki](https://github.com/plataformatec/devise/wiki) for more details.diff --git a/docs/developer/upgrades/3.0-to-3.1.mdx b/docs/developer/upgrades/3.0-to-3.1.mdxindex e9994c7e03..8e3b1b37bb 100644--- a/docs/developer/upgrades/3.0-to-3.1.mdx+++ b/docs/developer/upgrades/3.0-to-3.1.mdx@@ -13,7 +13,7 @@ bundle update## Copy and run migrations-Copy over the migrations from Spree \(and any other engine\) and run them using these commands:+Copy over the migrations from Spree and any other engine and run them using these commands:```bashrake railties:install:migrationsdiff --git a/docs/developer/upgrades/3.4-to-3.5.mdx b/docs/developer/upgrades/3.4-to-3.5.mdxindex b4c9957f72..3c75f78ef4 100644--- a/docs/developer/upgrades/3.4-to-3.5.mdx+++ b/docs/developer/upgrades/3.4-to-3.5.mdx@@ -36,7 +36,7 @@ bundle add spree_analytics_trackers2. Copy and run migrations:```bash-bundle exec rails g spree_analytics_trackers:install+bin/rails g spree_analytics_trackers:install```## Read the release notesdiff --git a/docs/developer/upgrades/3.7-to-4.0.mdx b/docs/developer/upgrades/3.7-to-4.0.mdxindex 3b8f507829..5d81199a12 100644--- a/docs/developer/upgrades/3.7-to-4.0.mdx+++ b/docs/developer/upgrades/3.7-to-4.0.mdx@@ -69,7 +69,7 @@ and runbundle update```-## Replace `class_eval` with `Module.prepend` \(only for Rails 6\)+## Replace `class_eval` with `Module.prepend` only for Rails 6Rails 6.0 ships with a [new code autoloader called Zeitwerk](https://medium.com/@fxn/zeitwerk-a-new-code-loader-for-ruby-ae7895977e73) which has some [strict rules in terms of file naming and contents](https://github.com/fxn/zeitwerk#file-structure). If you used `class_eval` to extend and modify Spree classes you will need to rewrite those with `Module.prepend`. Eg.diff --git a/docs/developer/upgrades/4.1-to-4.2.mdx b/docs/developer/upgrades/4.1-to-4.2.mdxindex c173a41e6d..361dd9f7b9 100644--- a/docs/developer/upgrades/4.1-to-4.2.mdx+++ b/docs/developer/upgrades/4.1-to-4.2.mdx@@ -21,7 +21,7 @@ Run the following command to update your gems to 4.2:bundle update```-## Remove SpreeMultiCurrency \(optional\)+## Remove SpreeMultiCurrency optionalIf you used that gem in the past you need to remove it. Multi-Currency is now incorporated into Spree core and you cannot use that gem anymore.@@ -31,20 +31,20 @@ If you used that gem in the past you need to remove it. Multi-Currency is now inbundle remove spree_multi_currency```-2. Remove these preferences from your Spree initializer \(`config/initializers/spree.rb`\):+2. Remove these preferences from your Spree initializer `config/initializers/spree.rb`:* `allow_currency_change`* `show_currency_selector`* `supported_currencies`3. Remove `//= require spree/frontend/spree_multi_currency` from `vendor/assets/javascripts/spree/frontend/all.js`4. Remove `//= require spree/backend/spree_multi_currency` from `vendor/assets/javascripts/spree/backend/all.js`-## \(Optional\) Remove SpreeI18n config+## Optional Remove SpreeI18n configAll international configuration is now kept on the `Store` model in the database rather than in initializer files.If you used `spree_i18n` gem before please remove any `SpreeI18n::Config`references from your `config/initializers/spree.rb` file.-## \(Optional\) Add `deface` gem+## Optional Add `deface` gemIf you used [Deface overrides](../../advanced/deface_overrides_tutorial#organizing-overrides) you will need to include `deface` in your `Gemfile` as it was removed from Spree / Spree Auth Devise / Spree Gateway dependencies.@@ -88,9 +88,9 @@ Please follow [this guide to migrate your custom serializers](https://github.comOnly if you've added new Admin Panel pages with Select2 dropdown - [this guide will help](https://select2.org/upgrading/migrating-from-35)-### Make sure you've got up to date Spree templates \(Storefront\)+### Make sure you've got up to date Spree templates Storefront-If you're using Spree default Storefront \(`spree_frontend` gem\) make sure to update your templates, especially:+If you're using Spree default Storefront `spree_frontend` gem make sure to update your templates, especially:* [app/views/spree/shared/_head.html.erb](https://github.com/spree/spree/blob/4-2-stable/frontend/app/views/spree/shared/_head.html.erb)* [app/views/spree/shared/_locale_and_currency.html.erb](https://github.com/spree/spree/blob/4-2-stable/frontend/app/views/spree/shared/_locale_and_currency.html.erb)@@ -103,7 +103,7 @@ If you're using Spree default Storefront \(`spree_frontend` gem\) make sure to u* [app/views/spree/shared/_nav_bar.html.erb](https://github.com/spree/spree/blob/4-2-stable/frontend/app/views/spree/shared/_nav_bar.html.erb)* [app/views/spree/shared/_line_item.html.erb](https://github.com/spree/spree/blob/4-2-stable/frontend/app/views/spree/shared/_line_item.html.erb)-Or simply run `bundle exec rails g spree:frontend:copy_storefront`+Or simply run `bin/rails g spree:frontend:copy_storefront`## Read the release notesdiff --git a/docs/developer/upgrades/4.2-to-4.3.mdx b/docs/developer/upgrades/4.2-to-4.3.mdxindex 8a9cfb05fa..62c212c2d5 100644--- a/docs/developer/upgrades/4.2-to-4.3.mdx+++ b/docs/developer/upgrades/4.2-to-4.3.mdx@@ -28,7 +28,7 @@ bundle add spree_emails spree_backend spree_frontendThese gems were merged into Spree Core in version 4.3. All of their functionality is now included in the `spree` gem so you can remove them.-### \(Optional\) Remove SpreeMultiDomain+### Optional Remove SpreeMultiDomainIf you used that gem in the past you need to remove it. Multi-Store is now incorporated into Spree core and you cannot use that gem anymore.@@ -41,7 +41,7 @@ If you used that gem in the past you need to remove it. Multi-Store is now incor2. Remove `//= require spree/frontend/spree_multi_domain` from `vendor/assets/javascripts/spree/frontend/all.js`3. Remove `//= require spree/backend/spree_multi_domain` from `vendor/assets/javascripts/spree/backend/all.js`-### \(Optional\) Remove Spree Editor+### Optional Remove Spree EditorSpree 4.3 includes TinyMCE 5 editor built-in. It's not recommended to use `spree_editor` gem anymore.@@ -49,7 +49,7 @@ Spree 4.3 includes TinyMCE 5 editor built-in. It's not recommended to use `spreebundle remove spree_editor```-### \(Optional\) Remove Spree Static Content+### Optional Remove Spree Static ContentSpree 4.3 includes a built-in CMS. It's not recommended to use `spree_static_content`diff --git a/docs/developer/upgrades/quickstart.mdx b/docs/developer/upgrades/quickstart.mdxindex 9aa1fd8ac3..f009294403 100644--- a/docs/developer/upgrades/quickstart.mdx+++ b/docs/developer/upgrades/quickstart.mdx@@ -23,7 +23,7 @@ Only bug fixes, no API changes, no new features. Except as necessary for securit**Minor Y, eg. 4.2.0**-New features, may contain API changes \(Serve as major versions of Semver\). Breaking changes are paired with deprecation notices in the previous minor or major release.+New features, may contain API changes Serve as major versions of Semver. Breaking changes are paired with deprecation notices in the previous minor or major release.**Major X, eg. 4.0.0**diff --git a/docs/mint.json b/docs/mint.jsonindex 8115d8494d..b6a3639975 100644--- a/docs/mint.json+++ b/docs/mint.json@@ -98,7 +98,11 @@"pages": ["developer/customization/quickstart","developer/customization/authentication",- "developer/customization/permissions"+ "developer/customization/images",+ "developer/customization/checkout",+ "developer/customization/permissions",+ "developer/customization/dependencies",+ "developer/customization/decorators"]},