@spree/docs 0.1.0

package/dist/developer/customization/v4/admin-panel.md

@@ -0,0 +1,78 @@
+> **WARNING:** This section is only relevant for Spree 4
+
+Starting with Spree 4.7, we've introduced a new way of customizing the admin panel, that enables extensions to modify the admin panel UI without depending on the Deface gem. For Spree 4.6 and earlier, please see how to use [deface_overrides_tutorial.md](../advanced/deface_overrides_tutorial.md "mention") overrides.
+
+### Customizing the main menu
+
+When extending Spree with custom features, it's common to add new options to the menu on the left-hand side.
+
+The menu is built with [`Spree::Admin::MainMenu::Section`](https://github.com/spree/spree_backend/blob/main/app/models/spree/admin/main_menu/section.rb) and [`Spree::Admin::MainMenu::Item`](https://github.com/spree/spree_backend/blob/main/app/models/spree/admin/main_menu/item.rb) objects.
+
+Additionally, there are two builder classes [`Spree::Admin::MainMenu::SectionBuilder`](https://github.com/spree/spree_backend/blob/main/app/models/spree/admin/main_menu/section_builder.rb) and [`Spree::Admin::MainMenu::ItemBuilder`](https://github.com/spree/spree_backend/blob/main/app/models/spree/admin/main_menu/item_builder.rb) that make it easier to build more complex sections.
+
+The menu is available under `Rails.application.config.spree_backend.main_menu` and can be modified by both extensions as well as the Rails application code.
+
+#### Example: adding an additional section to the admin panel:
+
+```ruby
+Rails.application.config.after_initialize do
+  Rails.application.config.spree_backend.main_menu.add(
+    Spree::Admin::MainMenu::SectionBuilder.new('subscriptions', 'inbox-fill.svg').
+       with_admin_ability_check(Spree::Subscription).
+       with_items(
+         Spree::Admin::MainMenu::ItemBuilder.new('active', Spree::Core::Engine.routes.url_helpers.admin_active_subsciptions_path).build,
+         Spree::Admin::MainMenu::ItemBuilder.new('expired', Spree::Core::Engine.routes.url_helpers.admin_expired_subsciptions_path).build
+       ).
+       build
+  )
+end
+```
+
+For a more extensive example, take a look at how the [default menu is built](https://github.com/spree/spree_backend/blob/main/app/models/spree/admin/main_menu/default_configuration_builder.rb).
+
+### Customizing tabs
+
+In some cases you may need to add a new tab to a page for editing Orders, Products or Users.
+
+![](/images/Screenshot 2023-10-31 at 18.57.13.png)
+
+These tabs are built with [`Spree::Admin::Tabs::Tab`](https://github.com/spree/spree_backend/blob/main/app/models/spree/admin/tabs/tab.rb). You can also use [`Spree::Admin::Tabs::TabBuilder`](https://github.com/spree/spree_backend/blob/main/app/models/spree/admin/tabs/tab_builder.rb) class to construct new Tab objects. The tabs are attached to `Rails.application.config.spree_backend.tabs` and can be modified via an initializer.
+
+#### Example: adding an additional tab to the product edit admin page
+
+```ruby
+Rails.application.config.after_initialize do
+  Rails.application.config.spree_backend.tabs[:product].add(
+    Spree::Admin::Tabs::TabBuilder.new('discounts', ->(resource) { admin_product_discounts_path(product) }).
+      with_icon_key('view.svg').
+      with_active_check.
+      build
+  )
+end
+```
+
+### Customizing actions
+
+A common case for extensions is to add a new action button in the admin panel.
+
+Action buttons are built with [`Spree::Admin::Actions::Action`](https://github.com/spree/spree_backend/blob/main/app/models/spree/admin/actions/action.rb) or with a dedicated [`Spree::Admin::Actions::ActionBuilder`](https://github.com/spree/spree_backend/blob/main/app/models/spree/admin/actions/action_builder.rb) class. The action buttons are attached to `Rails.application.config.spree_backend.actions` and can be modified with an initializer.
+
+**Example: adding a new button to the order page**
+
+```ruby
+Rails.application.config.after_initialize do
+  Rails.application.config.spree_backend.actions[:order].add(
+    Spree::Admin::Actions::ActionBuilder.new('generate_export', admin_export_orders_path).
+      with_icon_key('list.svg').
+      with_style(Spree::Admin::Actions::ActionStyle::PRIMARY).
+      with_method(:post).
+      build
+  )
+end
+```
+
+### Customizing existing views and partials
+
+If you need a more extensive customization of any of the admin panel pages, you can just copy their .erb file from the `spree_backend` gem to your `app/views/` directory and modify it there. This allows you to fully override default views provided by the `spree_backend` gem.
+
+> **NOTE:** Note: This approach is not recommended for Spree extensions, as it may conflict with other extensions that modify the same view.

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

@@ -0,0 +1,210 @@
+---
+title: Authentication
+description: Learn how to use a custom authentication setup with Spree
+version: v4
+---
+
+This guide covers using a custom authentication setup with Spree, such as one provided by your own application. This is ideal in situations where you want to handle the sign-in or sign-up flow of your application uniquely, outside the realms of what would be possible with Spree or you have an existing authentication with user accounts present.
+
+This guide assumes that you have a pre-existing model inside your application that represents the users of your application already. This model could be provided by gems such as [Devise](https://github.com/plataformatec/devise). This guide also assumes that the application that this `User` model exists in is already a Spree application.
+
+> **NOTE:** This model **does not** need to be called `User`, but for the purposes of this guide the model we will be referring to **will** be called `User`. If your model is called something else, do some mental substitution wherever you see `User`.
+
+To use your own authentication system with Spree, please follow these steps:
+
+<details>
+<summary>1. Change the Spree.user_class</summary>
+
+To begin using your custom `User` class, you must first edit Spree's initializer located at `config/initializers/spree.rb` by changing this line:
+
+    ```ruby
+    Spree.user_class = 'Spree::User'
+    ```
+
+    To this:
+
+    ```ruby
+    Spree.user_class = 'User'
+    ```
+
+</details>
+
+
+  <details>
+<summary>2. Update User model</summary>
+
+Next, you need to run the custom user generator for Spree which will create a migration that will add the necessary Spree fields to your users table.
+
+    Run this generator with this command:
+
+    ```bash
+    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
+    bin/rails db:migrate
+    ```
+
+    This generator will also create a file at `lib/spree/current_user_helpers.rb` which will be automatically included in your application's controllers allowing you to override the `spree_current_user` method to return the current user of the request.
+
+</details>
+
+  <details>
+<summary>3. Include User concerns in your User model</summary>
+
+In your User Model please include the following lines:
+
+    ```ruby
+    include Spree::UserMethods
+    include Spree::UserAddress
+    include Spree::UserPaymentSource
+    ```
+
+    The first of these methods are the ones added for the `has_and_belongs_to_many` association called `spree_roles`. This association will retrieve all the roles that a user has for Spree.
+
+    The second of these is the `spree_orders` association. This will return all orders associated with the user in Spree. There's also a `last_incomplete_spree_order` method which will return the last incomplete spree order for the user. This is used internal to Spree to persist order data across a user's login sessions.
+
+    The third and fourth associations are for address information for a user. When a user places an order, the address information for that order will be linked to that user so that it is available for subsequent orders.
+
+    The next method is one called `has_spree_role?` which can be used to check if a user has a specific role. This method is used internally to Spree to check if the user is authorized to perform specific actions, such as accessing the admin section. Admin users of your system should be assigned the Spree admin role, like this:
+
+    ```ruby
+    user = User.find_by(email: 'master@example.com')
+    user.spree_roles << Spree::Role.where(name: 'admin').first_or_create
+    ```
+
+    To test that this has worked, use the `has_spree_role?` method, like this:
+
+    ```ruby
+    user.has_spree_role?('admin')
+    ```
+
+    If this returns `true`, then the user has admin permissions within Spree.
+
+</details>
+
+  <details>
+<summary>4. Customize Spree Authentication Helpers (Optional)</summary>
+
+> **NOTE:** This step is required if you're using **`spree_backend`** and/or `spree_frontend` gems.
+
+    Run a generator to create a file at `lib/spree/authentication_helpers.rb` which will contain the following code to help you do that:
+
+    ```bash
+    bin/rails g spree:custom_authentication
+    ```
+
+    This will create a file at `lib/spree/authentication_helpers.rb` which will contain the following code to help you do that:
+
+    ```ruby
+    module Spree
+      module AuthenticationHelpers
+        def self.included(receiver)
+          receiver.helper_method(
+            :spree_current_user,
+            :spree_login_path,
+            :spree_signup_path,
+            :spree_logout_path,
+            :spree_forgot_password_path,
+            :spree_edit_password_path,
+            :spree_admin_login_path,
+            :spree_admin_logout_path,
+          )
+        end
+
+        def spree_current_user
+          current_user
+        end
+
+        def spree_login_path(opts = {})
+          main_app.login_path(opts)
+        end
+
+        def spree_signup_path(opts = {})
+          main_app.signup_path(opts)
+        end
+
+        def spree_logout_path(opts = {})
+          main_app.logout_path(opts)
+        end
+
+        def spree_forgot_password_path(opts = {})
+          main_app.forgot_password_path(opts)
+        end
+
+        def spree_edit_password_path(opts = {})
+          main_app.edit_password_path(opts)
+        end
+
+        def spree_admin_login_path(opts = {})
+          main_app.admin_login_path(opts)
+        end
+
+        def spree_admin_logout_path(opts = {})
+          main_app.admin_logout_path(opts)
+        end
+      end
+    end
+    ```
+
+    Each of the methods defined in this module return values that are the most common in Rails applications today, but you may need to customize them. In order, they are:
+
+    * `spree_current_user` Used to tell Spree what the current user of a request is.
+    * `spree_login_path` The location of the login/sign in form in your application.
+    * `spree_signup_path` The location of the sign up form in your application.
+    * `spree_logout_path` The location of the logout feature of your application.
+    * `spree_forgot_password_path` The location to reset a user's password.
+    * `spree_edit_password_path` The location to edit a user's password.
+    * `spree_admin_login_path` The location of the login/sign in form for the admin panel.
+    * `spree_admin_logout_path` The location of the logout feature for the admin panel.
+
+     URLs inside the helpers **must** have `main_app` prefixed if they are inside your application. This is because Spree will otherwise attempt to route these paths to the Spree engine, which does not exist. By prefixing with `main_app`, you tell it to look at the application's routes.
+
+    You will need to define the `login_path`, `signup_path` and `logout_path` routes yourself, by using code like this inside your application's `config/routes.rb` if you're using Devise:
+
+    ```ruby
+    devise_for :users
+    devise_scope :user do
+      get '/login', to: "devise/sessions#new"
+      get '/signup', to: "devise/registrations#new"
+      delete '/logout', to: "devise/sessions#destroy"
+      get '/forgot_password', to: "devise/passwords#new"
+      get '/edit_password', to: "devise/registrations#edit"
+    end
+    ```
+
+    Of course, this code will be different if you're not using Devise. Simply **do not** use the `devise_scope` method and change the controllers and actions for these routes.
+
+    You can also customize these methods inside `lib/spree/authentication_helpers.rb` to use the routing helper methods already provided by the authentication setup you have, if you wish.
+
+     Any modifications made to `lib/spree/authentication_helpers.rb` while the server is running will require a restart, as with any other modification to other files in `lib`.
+
+</details>
+
+  <details>
+<summary>5. Remove Auth Devise gem</summary>
+
+The `spree_auth_devise` gem is not needed when using an existing application authentication unless the goal is to have two separate authentication methods.
+
+    You can remove the `spree_auth_devise` gem by running this command:
+
+    ```bash
+    bundle remove spree_auth_devise
+    ```
+
+</details>
+
+
+## Admin Panel authentication
+
+By default Spree uses the same model for the admin panel as the storefront. However you can customize it to use a different model.
+
+To do this, you need to add the following code to your `config/initializers/spree.rb` file:
+
+```ruby
+Spree.admin_user_class = 'AdminUser'
+```
+
+This will tell Spree to use the `AdminUser` model for the admin panel. You will need to create this model in your application and ensure that it includes the necessary Spree fields.

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

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