@spree/docs 0.1.75 → 0.1.77

package/dist/developer/customization/v4/checkout.md

@@ -1,212 +0,0 @@
----
-title: Checkout Flow
-description: Learn how to customize the checkout process in Spree.
-version: v4
----
-
-## Overview
-
-The Spree checkout process has been designed for maximum flexibility. It's been redesigned several times now, each iteration has benefited from the feedback of real-world deployment experience. It is relatively simple to customize the checkout process to suit your needs. Secure transmission of customer information is possible via SSL and credit card information is never stored in the database.
-
-## The Checkout Flow DSL
-
-Spree comes with a new checkout DSL that allows you to succinctly define the different steps of your checkout. This new DSL allows you to customize _just_ the checkout flow, while maintaining the unrelated admin states, such as "canceled" and "resumed", that an order can transition to. Ultimately, it provides a shorter syntax compared with overriding the entire state machine for the `Spree::Order` class.
-
-The default checkout flow for Spree is defined like this, adequately demonstrating the abilities of this new system:
-
-```ruby
-checkout_flow do
-  go_to_state :address
-  go_to_state :delivery
-  go_to_state :payment, if: ->(order) {
-    order.update_totals
-    order.payment_required?
-  }
-  go_to_state :confirm, if: ->(order) { order.confirmation_required? }
-  go_to_state :complete
-  remove_transition from: :delivery, to: :confirm
-```
-
-we can pass a block on each checkout step definition and work some logic to figure if the step is required dynamically. e.g. the confirm step might only be necessary for payment gateways that support payment profiles.
-
-These conditional states present a situation where an order could transition from delivery to one of payment, confirm or complete. In the default checkout, we never want to transition from delivery to confirm, and therefore have removed it using the `remove_transition` method of the Checkout DSL. The resulting transitions between states look like the image below:
-
-These two helper methods are provided on `Spree::Order` instances for your convenience:
-
-* `checkout_steps` - returns a list of all the potential states of the checkout.
-* `has_step?` - Used to check if the current order fulfills the requirements for a specific state.
-
-If you want a list of all the currently available states for the checkout, use the `checkout_steps` method, which will return the steps in an array.
-
-## Default Checkout Steps
-
-The Spree checkout process consists of the following steps. With the exception of the Registration step, each of these steps corresponds to a state of the [Order object](../../core-concepts/orders.md):
-
-* Registration Optional - only if using [spree_auth_devise](https://github.com/spree/spree_auth_devise) extension, can be toggled through the `Spree::Auth::Config[:registration_step]` configuration setting
-* Address Information
-* Delivery Options Shipping Method
-* Payment
-* Confirmation
-
-The following sections will provide a walk-through of checkout from a user's perspective, and offer some information on how to configure the default behavior of the various steps.
-
-### Registration
-
-> **INFO:** This section only applies when using `spree_frontend` and `spree_auth_devise` gems.
-
-Prior to beginning the checkout process, the customer will be prompted to create a new account or to log in to their existing account. By default, there is also a "guest checkout" option that allows users to specify only their email address if they do not wish to create an account.
-
-Technically, the registration step is not an actual state in the `Spree::Order` state machine. The `spree_auth_devise` gem (an extension that comes with Spree Starter by default) adds the `check_registration` before filter to all actions of `Spree::CheckoutController` except for obvious reasons the `registration` and `update_registration` actions, which redirects to a registration page unless one of the following is true:
-
-* `Spree::Auth::Config[:registration_step]` preference is not `true`
-* user is already logged in
-* the current order has an email address associated with it
-
-The method is defined like this:
-
-```ruby
-def check_registration
-  return unless Spree::Auth::Config[:registration_step]
-  return if spree_current_user || current_order.email
-  store_location
-  redirect_to spree.checkout_registration_path
-end
-```
-
-#### Disabling guest checkout
-
-To completely disable guest checkout and require registration for checkout, you need to change Spree configuration in `config/initializers/spree.rb`:
-
-```ruby
-Spree::Config[:allow_guest_checkout] = false
-```
-
-### Address Information
-
-This step allows the customer to add both their billing and shipping information. Customers can click the "use billing address" option to use the same address for both.
-
-The address fields include a select box for choosing state/province. If there are no states configured for a particular country, the select box will be replaced by a text field instead.
-
-The list of countries that appear in the country select box can also be configured. Spree will list all countries by default, but you can configure exactly which countries you would like to appear. The list can be limited to a specific set of countries by [setting the Store's checkout zone](../../core-concepts/stores.md#checkout-configuration). Spree assumes that the list of billing and shipping countries will be the same. You can always change this logic via class decorator if this does not suit your needs.
-
-### Delivery Options
-
-During this step, the user may choose a delivery method. Spree assumes the list of shipping methods to be dependent on the shipping address.
-
-### Payment
-
-This step is where the customer provides payment information. This step is intentionally placed last in order to minimize security issues with credit card information. Credit card information is never stored in the database so it would be impossible to have a subsequent step and still be able to submit the information to the payment gateway. Spree submits the information to the gateway before saving the model so that the sensitive information can be discarded before saving the checkout information.
-
-Spree stores only the last four digits of the credit card number along with the expiration information. The full credit card number and verification code are never stored in the Spree database.
-
-Several gateways such as ActiveMerchant and Beanstream provide a secure method for storing a "payment profile" in your database. This approach typically involves the use of a "token" which can be used for subsequent purchases but only with your merchant account. If you are using a secure payment profile it would then be possible to show a final "confirmation" step after payment information is entered.
-
-If you do not want to use a gateway with payment profiles then you will need to customize the checkout process so that your final step submits the credit card information. You can then perform authorization before the order is saved. This is perfectly secure because the credit card information is not ever saved. It's transmitted to the gateway and then discarded like normal.
-
- Spree discards the credit card number after this step is processed. If you do not have a gateway with payment profiles enabled then your card information will be lost before it's time to authorize the card.
-
-For more information about payments, please see the [Payments guide](../../core-concepts/payments.md).
-
-### Confirmation
-
-This is the final opportunity for the customer to review their order before submitting it to be processed. Users have the opportunity to return to any step in the process using either the back button or by clicking on the appropriate step in the "progress breadcrumb."
-
-This step is disabled by default, but can be enabled by two ways:
-
-1. globally for all orders by setting a preference in `config/initializers/spree.rb`:
-
-    ```ruby
-    Spree::Config[:always_include_confirm_step] = true
-    ```
-
-2. conditionally for specific orders by overriding the `confirmation_required?` method in `Spree::Order`, eg.
-
-    ```ruby
-    module Spree
-      module OrderDecorator
-        # require confirmation for orders with a US billing address
-        def confirmation_required?
-          billing_address&.country_iso == 'US'
-        end
-      end
-    end
-    ```
-
-## Adding Logic Before or After a Particular Step
-
-The [state_machines](https://github.com/state-machines/state_machines) gem allows you to implement callbacks before or after transitioning to a particular step. These callbacks work similarly to [Active Record Callbacks](http://guides.rubyonrails.org/active_record_callbacks.html) in that you can specify a method or block of code to be executed prior to or after a transition. If the method executed in a before_transition returns false, then the transition will not execute.
-
-So, for example, if you wanted to verify that the user provides a valid zip code before transitioning to the delivery step, you would first implement a `valid_zip_code?` method, and then tell the state machine to run this method before that transition, placing this code in a file called `app/models/spree/order_decorator.rb`:
-
-```ruby
-module Spree
-  module OrderDecorator
-    def self.prepended(base)
-      base.state_machine.before_transition to: :delivery, do: :valid_zip_code?
-    end
-    
-    def valid_zip_code?
-      # logic to check if the zip code is valid
-    end
-  end
-
-  Order.prepend(OrderDecorator)
-end
-```
-
-This callback would prevent transitioning to the `delivery` step if `valid_zip_code?` returns false.
-
-## Modifying the checkout flow
-
-To add or remove steps to the checkout flow, you can use the 
-[insert_checkout_step](https://github.com/spree/spree/blob/a39ed2b69f1f2b2f413b7f46090bd0deeb439d61/core/app/models/spree/order/checkout.rb#L138) and [remove_checkout_step](https://github.com/spree/spree/blob/a39ed2b69f1f2b2f413b7f46090bd0deeb439d61/core/app/models/spree/order/checkout.rb#L157) helpers respectively.
-
-The `insert_checkout_step` method takes a `before` or `after` option to determine where to insert the step:
-
-```ruby
-module Spree
-  module OrderDecorator
-    def self.prepended(base)
-      base.insert_checkout_step :new_step, before: :address
-      # or
-      # base.insert_checkout_step :new_step, after: :address
-    end
-  end
-
-  Order.prepend(OrderDecorator)
-end
-```
-
-The `remove_checkout_step` will remove just one checkout step at a time:
-
-```ruby
-module Spree
-  module OrderDecorator
-    def self.prepended(base)
-      base.remove_checkout_step :address
-      base.remove_checkout_step :delivery
-    end
-  end
-
-  Order.prepend(OrderDecorator)
-end
-```
-
-What will happen here is that when a user goes to checkout, they will be asked to potentially fill in their payment details and then potentially confirm the order. This is the default behavior of the payment and the confirm steps within the checkout. If they are not required to provide payment or confirmation for this order then checking out this order will result in its immediate completion.
-
-To completely re-define the flow of the checkout, use the `checkout_flow` helper:
-
-```ruby
-module Spree
-  module OrderDecorator
-    def self.prepended(base)
-      base.checkout_flow do
-        go_to_state :payment
-        go_to_state :complete
-      end
-    end
-  end
-
-  Order.prepend(OrderDecorator)
-end
-```

package/dist/developer/customization/v4/deface.md

@@ -1,251 +0,0 @@
----
-title: Deface Overrides
-version: v4
----
-
-> **WARNING:** Using Deface is no longer recommended, we strongly encourage you to use other ways to customize Spree.
-
-## 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.
-
-## Improving Our Extension Using Deface
-
-### The Goal
-
-Our goal is to add a field to the product edit admin page that allows the `sale_price` to be added or updated. We could do this by overriding the view Spree provides, but there are potential problems with this technique. If Spree updates the view in a new release we won't get the updated view as we are already overriding it. We would need to update our view with the new content from Spree and then add our customizations back in to stay fully up to date.
-
-Let's do this instead using Deface, which we just learned about. Using Deface will allow us to keep our view customizations in one spot, `app/overrides`, and make sure we are always using the latest implementation of the view provided by Spree.
-
-### The Implementation
-
-We want to override the product edit admin page, so the view we want to modify in this case is the product form partial. This file's path will be `spree/admin/products/_form.html.erb`.
-
-First, let's create the overrides directory with the following command:
-
-```bash
-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/main/backend/app/views/spree/admin/products/_form.html.erb):
-
-```erb
-<div class="right four columns omega" data-hook="admin_product_form_right">
-  <%= f.field_container :price do %>
-    <%= f.label :price, raw(Spree.t(:master_price) + required_span_tag) %>
-    <%= f.text_field :price, value: number_to_currency(@product.price, unit: '')%>
-    <%= f.error_message_on :price %>
-  <% end %>
-</div>
-```
-
-We want our override to insert another field container after the price field container. We can do this by creating a new file `app/overrides/add_sale_price_to_product_edit.rb` and adding the following content:
-
-```ruby
-Deface::Override.new(virtual_path: 'spree/admin/products/_form',
-  name: 'add_sale_price_to_product_edit',
-  insert_after: "erb[loud]:contains('text_field :price')",
-  text: "
-    <%%= f.field_container :sale_price do %>
-      <%%= f.label :sale_price, raw(Spree.t(:sale_price) + content_tag(:span, ' *')) %>
-      <%%= f.text_field :sale_price, value:
-        number_to_currency(@product.sale_price, unit: '') %>
-      <%%= f.error_message_on :sale_price %>
-    <%% end %>
-  ")
-```
-
-We also need to delegate `sale_price` to the master variant in order to get the updated product edit form working.
-
-We can do this by creating a new file `app/models/spree/product_decorator.rb` and adding the following content to it:
-
-```ruby
-module Spree
-  Product.class_eval do
-    delegate :sale_price, :sale_price=, to: :master
-  end
-end
-```
-
-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/quickstart.md).
-
-### Available actions
-
-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:
-
-```ruby
-remove: "p.junk"
-
-insert_after: "div#wow p.header"
-
-insert_bottom: "ul#giant-list"
-```
-
-Deface currently supports the following actions:
-
-* :remove - Removes all elements that match the supplied selector
-* :replace - Replaces all elements that match the supplied selector, with the content supplied
-* :replace_contents - Replaces the contents of all elements that match the supplied selector
-* :surround - Surrounds all elements that match the supplied selector, expects replacement markup to contain &lt;%%= render_original %&gt; placeholder
-* :surround_contents - Surrounds the contents of all elements that match the supplied selector, expects replacement markup to contain &lt;%%= render_original %&gt; placeholder
-* :insert_after - Inserts after all elements that match the supplied selector
-* :insert_before - Inserts before all elements that match the supplied selector
-* :insert_top - Inserts inside all elements that match the supplied selector, as the first child
-* :insert_bottom - Inserts inside all elements that match the supplied selector, as the last child
-* :set_attributes - Sets attributes on all elements that match the supplied selector, replacing existing attribute value if present or adding if not. Expects :attributes option to be passed.
-* :add_to_attributes - Appends value to attributes on all elements that match the supplied selector, adds attribute if not present. Expects :attributes option to be passed.
-* :remove_from_attributes - Removes value from attributes on all elements that match the supplied selector. Expects :attributes option to be passed.
-
- Not all actions are applicable to all elements. For example, \`:insert_top\` and \`:insert_bottom\` expects a parent element with children.
-
-### Supplying content
-
-Deface supports three options for supplying content to be used by an override:
-
-* :text - String containing markup
-* :partial - Relative path to a partial
-* :template - Relative path to a template
-
- As Deface operates on the Erb source the content supplied to an override can include Erb, it is not limited to just HTML. You also have access to all variables accessible in the original Erb context.
-
-### 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.
-
-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:
-
-```erb
-<div data-hook="product_show" itemscope itemtype="http://schema.org/Product">
-  <%% body_id = 'product-details' %>
-  <div class="columns six alpha" data-hook="product_left_part">
-    <div class="row" data-hook="product_left_part_wrap">
-      <div id="product-images" data-hook="product_images">
-        <div id="main-image" data-hook>
-          <%%= render 'image' %>
-        </div>
-
-        <div id="thumbnails" data-hook>
-          <%%= render 'thumbnails', product: product %>
-        </div>
-      </div>
-
-      <div data-hook="product_properties">
-        <%%= render 'properties' %>
-      </div>
-
-    </div>
-  </div>
-
-  <div class="columns ten omega" data-hook="product_right_part">
-    <div class="row" data-hook="product_right_part_wrap">
-
-      <div id="product-description" data-hook="product_description">
-
-        <h1 class="product-title" itemprop="name"><%%= accurate_title %></h1>
-
-        <div itemprop="description" data-hook="description">
-          <%%= product_description(product) rescue Spree.t(:product_has_no_description) %>
-        </div>
-
-        <div id="cart-form" data-hook="cart_form">
-          <%%= render 'cart_form' %>
-        </div>
-      </div>
-
-      <%%= render 'taxons' %>
-    </div>
-  </div>
-</div>
-```
-
-As you can see from the example above the `data-hook` can be present in a number of ways:
-
-* On elements with **no** `id` attribute the `data-hook` attribute
-
-  contains a value similar to what would be included in the `id`
-
-  attribute.
-
-* On elements with an `id` attribute the `data-hook` attribute does
-
-  **not** normally contain a value.
-
-* Occasionally on elements with an `id` attribute the `data-hook` will
-
-  contain a value different from the elements id. This is generally to
-
-  support migration from the old 0.60.x style of hooks, where the old
-
-  hook names were converted into `data-hook` versions.
-
-The suggested way to target an element is to use the `data-hook` attribute wherever possible. Here are a few examples based on **products/show.html.erb** above:
-
-```ruby
-replace: "[data-hook='product_show']"
-
-insert_top: "#thumbnails[data-hook]"
-
-remove: "[data-hook='cart_form']"
-```
-
-You can also use a combination of both styles of selectors in a single override to ensure maximum protection against changes:
-
-```ruby
- insert_top: "[data-hook='thumbnails'], #thumbnails[data-hook]"
-```
-
-### 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.
-
-Given the following Erb file:
-
-```erb
-<%% if products.empty? %>
- <%%= Spree.t(:no_products_found) %>
-<%% elsif params.key?(:keywords) %>
-  <h3><%%= Spree.t(:products) %></h3>
-<%% end %>
-```
-
-Would be seen by Deface as:
-
-```markup
-<!-- <html>
-  <erb[silent]> if products.empty? </erb>
-  <erb[loud]> Spree.t(:no_products_found) </erb>
-  <erb[silent]> elsif params.key?(:keywords) </erb>
-
-  <h3><erb[loud]> Spree.t(:products) </erb></h3>
-
-  <erb[silent]> end </erb>
-</html> -->
-```
-
-So you can target ruby code blocks with the same standard CSS3 style selectors, for example:
-
-```ruby
-replace: "erb[loud]:contains('t(:products)')"
-
-insert_before: "erb[silent]:contains('elsif')"
-```
-
-### View upgrade protection
-
-To ensure upgrading between versions of Spree is as painless as possible, Deface supports an `:original` option that can contain a string of the original content that's being replaced. When Deface is applying the override it will ensure that the current source matches the value supplied and will output to the Rails application log if they are different.
-
-These warnings are a good indicator that you need to review the source and ensure your replacement is adequately replacing all the functionality provided by Spree. This will help reduce unexpected issues after upgrades.
-
-Once you've reviewed the new source you can update the `:original` value to new source to clear the warning.
-
- Deface removes all whitespace from both the actual and \`:original\` source values before comparing, to reduce false warnings caused by basic whitespace differences.
-
-### Organizing Overrides
-
-The suggested method for organizing your overrides is to create a separate file for each override inside the **app/overrides** directory, naming each file the same as the **:name** specified within.
-
-### More information on Deface
-
-For more information and sample overrides please refer to its [README](https://github.com/spree/deface) file on GitHub.

package/dist/developer/customization/v4/images.md

@@ -1,86 +0,0 @@
----
-title: Images
-version: v4
----
-
-## Overview
-
-This 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.
-
-
-## 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:
-
-```ruby
-module Spree
-  module ImageDecorator
-    module ClassMethods
-      def styles
-        {
-          # change existing default sizes used in Admin Panel and API
-          mini:    '48x48>',
-          small:   '100x100>',
-          product: '240x240>',
-          large:   '600x600>', 
-          # add your new size here, which will be automatically available in the API
-          my_custom_size: '1000x1000>'
-        }
-      end
-    end
-
-    def self.prepended(base)
-      base.inheritance_column = nil
-      base.singleton_class.prepend ClassMethods
-    end
-  end
-
-  Image.prepend(ImageDecorator)
-end
-```
-
-## 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'))) %>
-```
-
-## Storage service
-
-By default Spree will use the storage service you have set in your environment file eg. `config/environments/development.rb`:
-
-```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')) %>
-```