Skip to content

armgit / spree

Public Imported from GitHub
0

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

Admin Dashboard documentation (#12751)

Damian Legawiece873ea5a41a7
diff --git a/core/lib/spree/core/controller_helpers/currency.rb b/core/lib/spree/core/controller_helpers/currency.rb
index d59ef343bb..ff63c218a6 100644
--- a/core/lib/spree/core/controller_helpers/currency.rb
+++ b/core/lib/spree/core/controller_helpers/currency.rb
@@ -14,6 +14,8 @@ module Spree
end
end
+ # Returns the currently selected currency.
+ # @return [String] the currently selected currency, eg. `USD`
def current_currency
@current_currency ||= if defined?(session) && session.key?(:currency) && supported_currency?(session[:currency])
session[:currency]
@@ -26,10 +28,14 @@ module Spree
end&.upcase
end
+ # Returns the list of supported currencies for the current store.
+ # @return [Array<Money::Currency>] the list of supported currencies
def supported_currencies
@supported_currencies ||= current_store&.supported_currencies_list
end
+ # Returns the list of supported currencies for all stores.
+ # @return [Array<String>] the list of supported currencies, eg. `["USD", "EUR"]`
def supported_currencies_for_all_stores
@supported_currencies_for_all_stores ||= begin
(
@@ -39,12 +45,17 @@ module Spree
end
end
+ # Checks if the given currency is supported.
+ # @param currency_iso_code [String] the ISO code of the currency, eg. `USD`
+ # @return [Boolean] `true` if the currency is supported, `false` otherwise
def supported_currency?(currency_iso_code)
return false if supported_currencies.nil?
supported_currencies.map(&:iso_code).include?(currency_iso_code.upcase)
end
+ # Returns the currency parameter from the request.
+ # @return [String] the currency parameter, eg. `USD`
def currency_param
return if current_currency == current_store.default_currency
diff --git a/docs/developer/admin/admin.mdx b/docs/developer/admin/admin.mdx
new file mode 100644
index 0000000000..8044ada90b
--- /dev/null
+++ b/docs/developer/admin/admin.mdx
@@ -0,0 +1,49 @@
+---
+title: Admin Dashboard
+sidebarTitle: Overview
+---
+
+Spree Admin Dashboard is the main interface for managing your store. It's built with Ruby on Rails and is installable as a `spree_admin` gem. If you're using Spree Starter, this is already installed for you.
+
+## Overview
+
+Admin Dashboard can be fully customized to your liking. You can extend the UI, include custom CSS and JavaScript, and you can add new sections to the dashboard or modify existing ones.
+
+The basis of the admin dashboard is same as with any Ruby on Rails application:
+
+## Templates (aka Views)
+
+Views are the HTML templates that are used to generate the user interface. They are responsible for displaying the data to the user. Views use standard [Ruby on Rails ERB template system](https://guides.rubyonrails.org/action_view_overview.html#erb), eg.
+
+```erb
+<%# Example of a simple view %>
+<div>
+ <h1>Welcome to the <%= current_store.name %></h1>
+</div>
+```
+
+In views you can use Ruby code and also helper methods defined in
+
+Spree Admin provides a way for you to inject your own templates into existing screens, eg. adding additional fields to forms or adding new navigation elements.
+
+## Controllers
+
+Controllers are the Ruby classes that handle requests from the user. They are responsible for processing the data and returning the appropriate response. Controllers use standard [Ruby on Rails controller system](https://guides.rubyonrails.org/action_controller_overview.html).
+
+### Namespace
+
+Every Admin controller should be placed in `Spree::Admin` namespace and [app/controllers/spree/admin](https://github.com/spree/spree/tree/main/admin/app/controllers/spree/admin) directory, eg. `Spree::Admin::ProductsController`.
+
+### BaseController
+
+The main Admin Controller is [Spree::Admin::BaseController](https://github.com/spree/spree/blob/main/admin/app/controllers/spree/admin/base_controller.rb). It provides a lot of functionality out of the box, such as authentication, authorization, and breadcrumbs.
+
+### ResourceController
+
+For easier and faster development Spree provides [Spree::Admin::ResourceController](https://github.com/spree/spree/blob/main/admin/app/controllers/spree/admin/resource_controller.rb) which provides all the necessary CRUD (Create, Read, Update, Delete) functionality for managing resources in a RESTful way so you can focus on building your application.
+
+You will learn more about this in the [Creating new Admin sections guide](/developer/admin/new-admin-sections).
+
+## JavaScript
+
+Interactitivy in Spree Admin is handled by [Hotwire](https://hotwire.dev/) which is the default Ruby on Rails frontend framework. JavaScript bundling is done via [Importmaps](https://github.com/rails/importmap-rails), which is a modern JavaScript bundling solution that is easy to use and integrates well with Rails. Also, it doesn't require node at all.
diff --git a/docs/developer/admin/custom-css.mdx b/docs/developer/admin/custom-css.mdx
new file mode 100644
index 0000000000..a7e7eecf98
--- /dev/null
+++ b/docs/developer/admin/custom-css.mdx
@@ -0,0 +1,57 @@
+---
+title: Admin Dashboard Custom CSS
+sidebarTitle: Custom CSS
+---
+
+<Warning>
+ This guide is still work in progress!
+</Warning>
+
+Spree Admin Dashboard stylesheet system is built in top [Bootstrap](https://getbootstrap.com/) and uses [SASS](https://sass-lang.com/) preprocessor to compile custom stylesheets. To be precise we're using DART-SASS (so you don't need to install Node.js).
+
+You can find the stylesheets files in [app/assets/stylesheets/spree/admin](https://github.com/spree/spree/tree/main/admin/app/assets/stylesheets/spree/admin) directory.
+
+The main entry point file is [application.scss](https://github.com/spree/spree/blob/main/admin/app/assets/stylesheets/spree/admin/application.scss) which uses SASS `@import` directive to include other stylesheets.
+
+## Overriding existing SASS code
+
+<Warning>
+ This section will be added soon!
+</Warning>
+
+## Adding custom CSS
+
+Besides SASS you can still include standard CSS files. To do so:
+
+
+1. Create a new file in your application `app/assets/stylesheets` directory:
+
+ ```bash
+ touch app/assets/stylesheets/custom_spree_admin.css
+ ```
+2. Add some CSS rules to the file:
+
+ ```css
+ .custom-class {
+ color: red;
+ }
+ ```
+3. Create a template file in your application `app/views/spree/admin/shared` directory:
+
+ ```bash
+ touch app/views/spree/admin/shared/custom_spree_admin_stylesheets.html.erb
+ ```
+
+4. Use standard Ruby on Rails [stylesheet_link_tag](https://api.rubyonrails.org/v7.2/classes/ActionView/Helpers/AssetTagHelper.html#method-i-stylesheet_link_tag)
+
+ ```erb
+ <%= stylesheet_link_tag 'custom_spree_admin' %>
+ ```
+
+5. Register this template in the Spree initializer (`config/initializers/spree.rb`):
+
+ ```ruby
+ Rails.application.config.spree_admin.head_partials << 'spree/admin/shared/custom_spree_admin_stylesheets'
+ ```
+
+That's it! Now you're custom CSS code will be included after loading the standard Admin stylesheets.
diff --git a/docs/developer/admin/custom-javascript.mdx b/docs/developer/admin/custom-javascript.mdx
new file mode 100644
index 0000000000..9a006452fe
--- /dev/null
+++ b/docs/developer/admin/custom-javascript.mdx
@@ -0,0 +1,107 @@
+---
+title: Custom JavaScript for Admin Dashboard
+sidebarTitle: Custom JavaScript
+description: Learn how to add custom JavaScript to your Spree Admin Dashboard
+---
+
+## Extending Admin Dashboard with JavaScript
+
+Spree Admin Dashboard can be easily extended with custom JavaScript. Most of the JavaScript in the Admin Dashboard is powered by a framework called [Stimulus.js](https://stimulus.hotwired.dev/) which is the Ruby on Rails default. It's a very simple and minimalistic framework only enhancing our server-side rendered HTML with a bit of interactivity.
+
+### 3rd party JavaScript libraries
+
+Spree Admin Dashboard comes with a few 3rd party JavaScript libraries already included.
+
+Main libraries we're using:
+
+* [Stimulus.js](https://stimulus.hotwired.dev/)
+* [Turbo](https://turbo.hotwired.dev/)
+* [EasyPick](https://easepick.com/) (date picker)
+* [TomSelect](https://tom-select.js.org/) (autocomplete/dropdowns)
+* [Sortable.js](https://github.com/SortableJS/Sortable) - sortable drag and drop lists
+* [Uppy](https://uppy.io/) - file uploader
+
+You can find them in the [app/assets/javascripts/vendor](https://github.com/spree/spree/blob/main/admin/vendor/javascript) directory.
+
+### Managing JavaScript dependencies
+
+You're probably wondering why these libraries are in the `vendor` directory, and not in `node_modules`.
+
+That's because we're not using Node.js at all. So no Yarn or npm. We're using a different approach to manage dependencies.
+
+We're using a tool called [Importmaps](https://github.com/rails/importmap-rails) to manage dependencies which is the Ruby on Rails default.
+
+<Info>
+If you want to use a different JavaScript package manager you can do so by using [jsbundling-rails](https://github.com/rails/jsbundling-rails) gem.
+</Info>
+
+#### Install dependencies
+
+To install dependencies you need to run the following command:
+
+```bash
+bin/rails importmap pin react
+```
+
+This will install the dependencies, download the files to your `vendor/javascript` directory and add them to your `config/importmap.rb` file, eg.
+
+```ruby
+pin "react" # @19.1.0
+```
+
+Now you can just import the library in your application entry point, eg. `application.js`:
+
+```js
+import "react";
+```
+
+### Application entry point
+
+Mentioned above, the application entry point is the `application.js` file. It's located in the `app/javascript` directory.
+
+If you want to add custom JavaScript to your Spree Admin Dashboard, you can do so by adding a new file to the `app/javascript` directory.
+
+### Stimulus Controllers
+
+Stimulus controllers are a way to add interactivity to your Spree Admin Dashboard. Admin Dashboard controllers can be found in the Spree repository in the [Admin Dashboard/app/javascript/spree/admin/controllers](https://github.com/spree/spree/tree/main/admin/app/javascript/spree/admin/controllers) directory.
+
+You can find more information about Stimulus controllers in the [Stimulus.js documentation](https://stimulus.hotwired.dev/handbook/controllers).
+
+To add a new controller you need to create a new file in the `app/javascript/controllers` directory. It will be automatically picked up by the application.
+
+```js
+// app/javascript/controllers/hello_controller.js
+import { Controller } from '@hotwired/stimulus'
+
+export default class extends Controller {
+ connect() {
+ console.log("Hello Spree Commerce Stimulus!", this.element);
+ }
+}
+```
+
+To use the controller in your HTML you need to add the `data-controller` attribute to your element, eg.
+
+```html
+<div data-controller="hello">
+ Hello Spree Commerce Stimulus!
+</div>
+```
+
+## JavaScript snippets
+
+If you need to add a small piece of JavaScript code (eg. tracking, marketing, analytics, customer service etc.) you can do this by:
+
+1. Declaring a new head partial in the `config/initializers/spree.rb` file, eg.
+
+ ```ruby
+ Rails.application.config.spree_admin.head_partials << 'spree/admin/shared/my_tracking_code'
+ ```
+
+2. Creating a new file in the `app/views/spree/admin/shared/my_tracking_code.html.erb`, where you can add your tracking code, eg.
+
+ ```erb
+ <script>
+ console.log("I'm a spy!");
+ </script>
+ ```
\ No newline at end of file
diff --git a/docs/developer/admin/extending-ui.mdx b/docs/developer/admin/extending-ui.mdx
new file mode 100644
index 0000000000..e597401161
--- /dev/null
+++ b/docs/developer/admin/extending-ui.mdx
@@ -0,0 +1,494 @@
+---
+title: Extending Admin Dashboard UI
+sidebarTitle: Extending UI
+---
+
+Spree Admin Dashboard allows you easily extend existing pages and screens with your own code, without any need to modify the core codebase. This allows you to easily inject your custom UI elements without compromising the integrity of the core codebase. Which in effect allows you to safely update your Spree installation to the latest version.
+
+## How it works
+
+The entire system works on the basis of injection points which are declared throughout the admin dashboard and allows you to push your own code there. Each injection point is identified by a key, eg. `body_end_partials`.
+
+Let's say you want to add a new footer to the admin dashboard. You'll need to generate a template in your application:
+
+1. Ensure you have the proper directory to store your templates:
+
+ ```bash
+ mkdir -p app/views/spree/admin/shared
+ ```
+
+2. Create a new partial template file (partial templates file names start with underscore)
+
+ ```bash
+ touch app/views/spree/admin/shared/_additional_footer.html.erb
+ ```
+
+3. Add your own code to the partial
+
+ ```erb
+ <div class="mx-auto bg-light p-3 rounded-lg text-center w-10">
+ Copyright <%= current_store.name %> <%= Time.current.year %>
+ </div>
+ ```
+
+4. Register your partial in `config/initializers/spree.rb`
+
+ ```ruby
+ Rails.application.config.spree_admin.body_end_partials << 'spree/admin/shared/additional_footer'
+ ```
+
+ <Info>
+ The key is the name of the injection point, eg. `body_end_partials`.
+ </Info>
+
+ <Info>
+ Remember to use the correct path to your partial and skip the `_` prefix.
+ </Info>
+
+5. Restart your web server and you should see your new footer.
+
+ <Frame>
+ <img src="/images/developer/admin/partial_injecting_example.png" />
+ </Frame>
+
+ <Info>
+ Making further changes to the partial template will not require you to restart the web server. They will be picked up automatically.
+ </Info>
+
+<Hint>
+ To summarize, we're injecting our code into the `body_end_partials` array. This is a list of partials that will be rendered at the end of the body tag (before the closing `</body>` tag). The order of the partials in the array is the order in which they will be rendered.
+</Hint>
+
+## Admin Dashboard injection points
+
+Here's a list of all places you can inject your custom code:
+
+### Layout
+
+<AccordionGroup>
+ <Accordion title="<head>">
+ `head_partials`
+
+ Injects code into the `<head>` tag
+ </Accordion>
+
+ <Accordion title="<body>">
+ `body_start_partials`
+
+ Injects code into the `<body>` tag, before the main content
+ </Accordion>
+
+ <Accordion title="</body>">
+ `body_end_partials`
+
+ Injects code into the `<body>` tag, after the main content
+ </Accordion>
+</AccordionGroup>
+
+### Dashboard
+
+<AccordionGroup>
+ <Accordion title="Analytics">
+ `dashboard_analytics_partials`
+
+ <Frame>
+ <img src="/images/developer/admin/dashboard_analytics_partials.png" />
+ </Frame>
+
+ Injects code into the dashboard analytics section, eg.
+
+ ```erb
+ <div class="card">
+ <div class="card-body">
+ <h5 class="card-title">Top ERP products</h5>
+ </div>
+ <div class="card-footer">
+ <%# ... my custom content ... %>
+ </div>
+ </div>
+ ```
+ </Accordion>
+
+ <Accordion title="Sidebar">
+ `dashboard_sidebar_partials`
+
+ <Frame>
+ <img src="/images/developer/admin/dashboard_sidebar_partials.png" />
+ </Frame>
+
+ Injects code into the dashboard sidebar, eg.
+
+ ```erb
+ <div class="card">
+ <div class="card-body">
+ <h5 class="card-title">Latest ERP syncs</h5>
+ </div>
+ <div class="card-footer">
+ <%# ... my custom content ... %>
+ </div>
+ </div>
+ ```
+ </Accordion>
+</AccordionGroup>
+
+### Orders
+
+<AccordionGroup>
+ <Accordion title="Orders List Filters">
+ `orders_filters_partials`
+
+ <Frame>
+ <img src="/images/developer/admin/orders_filters_partials.png" />
+ </Frame>
+
+ #### Variables
+
+ <ParamField path="f" type="ActionView::Helpers::FormBuilder">
+ The [ActionView::Helpers::FormBuilder](https://api.rubyonrails.org/classes/ActionView/Helpers/FormBuilder.html) object.
+ </ParamField>
+
+ Injects code into the orders list filters, to add custom filters.
+ This partial has access to the `f` variable, which is the form builder for the filters, eg.
+
+ ```erb
+ <%= f.text_field :q_number_cont, class: "form-control", data: { filters_target: :input } %>
+ ```
+
+ <Tip>
+ * `q_number_cont` - The name of the filter field. For filtering we're using [ransack](https://activerecord-hackery.github.io/ransack/) gem, so the name of the filter field is the name of the attribute we're filtering by. Learn more about [ransack search syntax](https://activerecord-hackery.github.io/ransack/getting-started/search-matches/).
+ * `form-control` - A bootstrap class for styling the input field.
+ * `data: { filters_target: :input }` - Needed for the [Stimulus Filters controller](https://github.com/spree/spree/blob/main/admin/app/javascript/spree/admin/controllers/filters_controller.js) to work.
+ </Tip>
+ </Accordion>
+
+ <Accordion title="Order Page Dropdown">
+ `order_page_dropdown_partials`
+
+ <Frame>
+ <img src="/images/developer/admin/order_page_dropdown_partials.png" />
+ </Frame>
+
+ #### Variables
+
+ <ParamField path="order" type="Spree::Order">
+ The [Spree::Order](https://github.com/spree/spree/blob/main/core/app/models/spree/order.rb) object.
+ </ParamField>
+
+ Injects code into the order page dropdown. This partial has access to the `order` variable.
+
+ To add an additional dropdown item, you can use the following code:
+
+ ```erb
+ <%= link_to "View Order in ERP", "https://erp.com/orders/#{order.number}", class: "dropdown-item", target: "_blank" %>
+ ```
+
+ <Tip>
+ * `dropdown-item` is a bootstrap class for styling the dropdown item
+ * `target: "_blank"` is used to open the link in a new tab
+ </Tip>
+ </Accordion>
+
+ <Accordion title="Order Page Header">
+ `order_page_header_partials`
+
+ <Frame>
+ <img src="/images/developer/admin/order_page_header_partials.png" />
+ </Frame>
+
+ #### Variables
+
+ <ParamField path="order" type="Spree::Order">
+ The [Spree::Order](https://github.com/spree/spree/blob/main/core/app/models/spree/order.rb) object.
+ </ParamField>
+
+ Injects code into the order page header.
+
+ To add an additional action button near the `...` button, you can use the following code:
+
+ <Frame>
+ <img src="/images/developer/admin/order_page_header_partials.png" />
+ </Frame>
+
+ Injects code into the order page header.
+
+ To add an additional action button near the `...` button, you can use the following code:
+
+ ```erb
+ <%= content_for :page_actions do %>
+ <%= link_to "Send to ERP", "#", class: "btn btn-primary" %>
+ <% end %>
+ ```
+
+ To add an inline alert to the order page, you can use the following code:
+
+ ```erb
+ <%= content_for :page_alerts do %>
+ <% if order.sent_to_erp_at.blank? %>
+ <div class="alert alert-success">Order sent to ERP at <%= local_time(order.sent_to_erp_at) %></div>
+ <% else %>
+ <div class="alert alert-danger">Order not sent to ERP</div>
+ <% end %>
+ <% end %>
+ ```
+
+ <Tip>
+ `local_time` is a helper for displaying the time in the user's timezone in a human readable **format** (based on the browser's timezone).
+ </Tip>
+ </Accordion>
+
+ <Accordion title="Order Page Body">
+ `order_page_body_partials`
+
+ <Frame>
+ <img src="/images/developer/admin/order_page_body_partials.png" />
+ </Frame>
+
+ #### Variables
+
+ <ParamField path="order" type="Spree::Order">
+ The [Spree::Order](https://github.com/spree/spree/blob/main/core/app/models/spree/order.rb) object.
+ </ParamField>
+
+ Injects code into the order page body. This partial has access to the `order` variable.
+
+ To add a new section to the order page, you can use the following code:
+
+ ```erb
+ <div class="card mb-4">
+ <div class="card-header">
+ <h5 class="card-title">ERP Integration</h5>
+ </div>
+ <div class="card-body">
+ <% if order.sent_to_erp_at.blank? %>
+ <p class="text-muted text-center">Order not sent to ERP</p>
+ <% else %>
+ <ul class="list-group list-group-flush">
+ <li class="list-group-item">
+ <strong>ERP Order ID:</strong> <%= order.erp_order_id %>
+ </li>
+ <li class="list-group-item">
+ <strong>Sent to ERP at:</strong> <%= local_time(order.sent_to_erp_at) %>
+ </li>
+ </ul>
+ <% end %>
+ </div>
+ </div>
+ ```
+ </Accordion>
+
+ <Accordion title="Order Page Sidebar">
+ `order_page_sidebar_partials`
+
+ <Frame>
+ <img src="/images/developer/admin/order_page_sidebar_partials.png" />
+ </Frame>
+
+ #### Variables
+
+ <ParamField path="order" type="Spree::Order">
+ The [Spree::Order](https://github.com/spree/spree/blob/main/core/app/models/spree/order.rb) object.
+ </ParamField>
+
+ Injects code into the order page sidebar. This partial has access to the `order` variable.
+ </Accordion>
+</AccordionGroup>
+
+### Products
+
+<AccordionGroup>
+ <Accordion title="Products List Filters">
+ `products_filters_partials`
+
+ <Frame>
+ <img src="/images/developer/admin/products_filters_partials.png" />
+ </Frame>
+
+ #### Variables
+
+ <ParamField path="f" type="ActionView::Helpers::FormBuilder">
+ The [ActionView::Helpers::FormBuilder](https://api.rubyonrails.org/classes/ActionView/Helpers/FormBuilder.html) object.
+ </ParamField>
+
+ Injects code into the products list filters. This partial has access to the `f` variable, which is the form builder for the filters.
+
+ To add a new filter field, you can use the following code:
+
+ ```erb
+ <%= f.text_field :q_name_cont, class: "form-control", data: { filters_target: :input } %>
+ ```
+
+ <Tip>
+ * `q_name_cont` is the name of the filter field. For filtering we're using [ransack](https://activerecord-hackery.github.io/ransack/) gem, so the name of the filter field is the name of the attribute we're filtering by. Learn more about [ransack search syntax](https://activerecord-hackery.github.io/ransack/getting-started/search-matches/).
+ * `form-control` is a bootstrap class for styling the input field.
+ * `data: { filters_target: :input }` is needed for the [Stimulus Filters controller](https://github.com/spree/spree/blob/main/admin/app/javascript/spree/admin/controllers/filters_controller.js) to work.
+ </Tip>
+ </Accordion>
+
+ <Accordion title="Products Page Dropdown">
+ `product_dropdown_partials`
+
+ <Frame>
+ <img src="/images/developer/admin/product_dropdown_partials.png" />
+ </Frame>
+
+ Injects code into the products page dropdown. This partial has access to the `product` variable.
+
+ To add an additional dropdown item, you can use the following code:
+
+ ```erb
+ <%= link_to "View Product in WMS", "https://wms.com/products/#{product.id}", class: "dropdown-item", target: "_blank" %>
+ ```
+
+ <Info>
+ Your code will be placed before the dropdown divider.
+ </Info>
+ </Accordion>
+
+ <Accordion title="Products Page Form">
+ `product_form_partials`
+
+ <Frame>
+ <img src="/images/developer/admin/product_form_partials.png" />
+ </Frame>
+
+ #### Variables
+
+ <ParamField path="f" type="ActionView::Helpers::FormBuilder">
+ The [ActionView::Helpers::FormBuilder](https://api.rubyonrails.org/classes/ActionView/Helpers/FormBuilder.html) object.
+ </ParamField>
+
+ <ParamField path="product" type="Spree::Product">
+ The [Spree::Product](https://github.com/spree/spree/blob/main/core/app/models/spree/product.rb) object.
+ </ParamField>
+
+ Injects code into the product form. This partial has access to the `f` variable, which is the form builder for the product form, and the `product` variable.
+
+ To add a new section to the product form, you can use the following code:
+
+ ```erb
+ <div class="card mb-4">
+ <div class="card-header">
+ <h5 class="card-title">ERP Integration</h5>
+ </div>
+ <div class="card-body">
+ <%= f.text_field :erp_product_id, class: "form-control" %>
+ </div>
+ </div>
+ ```
+
+ <Info>
+ The partial will be displayed for both new product form and edit product form.
+ </Info>
+
+ <Tip>
+ If you want to display the partial only on the edit product form, you can use the following code:
+
+ ```erb
+ <% if product.persisted? %>
+ <%# ... your code ... %>
+ <% end %>
+ ```
+
+ And similarly for the new product form.
+
+ ```erb
+ <% if product.new_record? %>
+ <%# ... your code ... %>
+ <% end %>
+ ```
+ </Tip>
+
+ </Accordion>
+
+ <Accordion title="Products Page Sidebar">
+ `product_form_sidebar_partials`
+
+ <Frame>
+ <img src="/images/developer/admin/product_form_sidebar_partials.png" />
+ </Frame>
+
+ #### Variables
+
+ <ParamField path="f" type="ActionView::Helpers::FormBuilder">
+ The [ActionView::Helpers::FormBuilder](https://api.rubyonrails.org/classes/ActionView/Helpers/FormBuilder.html) object.
+ </ParamField>
+
+ <ParamField path="product" type="Spree::Product">
+ The [Spree::Product](https://github.com/spree/spree/blob/main/core/app/models/spree/product.rb) object.
+ </ParamField>
+
+ Injects code into the product form sidebar. This partial has access to the `f` variable, which is the form builder for the product form, and the `product` variable.
+
+ To add a new section to the product form sidebar, you can use the following code:
+
+ ```erb
+ <div class="card mb-4">
+ <div class="card-header">
+ <h5 class="card-title">ERP Integration</h5>
+ </div>
+ <div class="card-body">
+ <%= f.text_field :erp_product_id, class: "form-control" %>
+ </div>
+ </div>
+ ```
+
+ <Info>
+ The partial will be displayed for both new product form and edit product form.
+ </Info>
+
+ <Tip>
+ If you want to display the partial only on the edit product form, you can use the following code:
+
+ ```erb
+ <% if product.persisted? %>
+ <%# ... your code ... %>
+ <% end %>
+ ```
+
+ And similarly for the new product form.
+
+ ```erb
+ <% if product.new_record? %>
+ <%# ... your code ... %>
+ <% end %>
+ ```
+ </Tip>
+ </Accordion>
+</AccordionGroup>
+
+### Store Settings
+
+<AccordionGroup>
+ <Accordion title="Store Settings Form">
+ `store_form_partials`
+
+ <Frame>
+ <img src="/images/developer/admin/store_form_partials.png" />
+ </Frame>
+
+ #### Variables
+
+ <ParamField path="f" type="ActionView::Helpers::FormBuilder">
+ The [ActionView::Helpers::FormBuilder](https://api.rubyonrails.org/classes/ActionView/Helpers/FormBuilder.html) object.
+ </ParamField>
+
+ <ParamField path="store" type="Spree::Store">
+ The [Spree::Store](https://github.com/spree/spree/blob/main/core/app/models/spree/store.rb) object.
+ </ParamField>
+
+ Injects code into the store settings form. This partial has access to the `f` variable, which is the form builder for the store form, and the `store` variable.
+
+ To add a new section to the store form, you can use the following code:
+
+ ```erb
+ <div class="card mb-4">
+ <div class="card-header">
+ <h5 class="card-title">ERP Integration</h5>
+ </div>
+ <div class="card-body">
+ <%= f.text_field :erp_store_id, class: "form-control" %>
+ </div>
+ </div>
+ ```
+ </Accordion>
+</AccordionGroup>
diff --git a/docs/developer/admin/helper-methods.mdx b/docs/developer/admin/helper-methods.mdx
new file mode 100644
index 0000000000..389b74f8c6
--- /dev/null
+++ b/docs/developer/admin/helper-methods.mdx
@@ -0,0 +1,188 @@
+---
+title: Admin Dashboard Helper Methods
+sidebarTitle: Helper Methods
+---
+
+Here you can find a list of helper methods that are available in the Admin Dashboard that you can use in every template.
+
+<Warning>
+The list is incomplete.
+</Warning>
+
+## `active_badge`
+
+Displays a badge with a color based on the condition.
+
+```erb
+<%= active_badge(order.sent_to_erp_at.blank?) %>
+```
+
+If the condition is true, it will render
+
+```html
+<span class="badge badge-success">Active</span>
+```
+
+If the condition is false, it will render
+
+```html
+<span class="badge badge-danger">Inactive</span>
+```
+
+You can also pass a custom label to the badge:
+
+<ParamField query="label" type="string">
+ Custom text to display in the badge. If not provided, will show "Active"/"Inactive" based on the condition.
+</ParamField>
+
+## `active_link_to_with_icon`
+
+Same as [link_to_with_icon](/developer/admin/helper-methods#link-to-with-icon), but it will add the `active` class if the current page is the same as the link.
+
+```erb
+<%= active_link_to_with_icon 'eye', "View Order in ERP", spree.admin_order_path(order), class: "btn btn-primary" %>
+```
+
+You can also pass a custom `active` condition.
+
+```erb
+<%= active_link_to_with_icon 'eye', "View Order in ERP", spree.admin_order_path(order), class: "btn btn-primary", active: order.sent_to_erp_at.blank? %>
+```
+
+## `currency_select`
+
+Available for forms to build a currency select dropdown. Provided via [currency_select gem](https://github.com/braingourmets/currency_select).
+
+```erb
+<div class="form-group">
+ <%= f.label :default_currency, Spree.t(:currency) %>
+ <%= f.currency_select :default_currency, preferred_currencies, {}, { data: { controller: 'autocomplete-select' } } %>
+</div>
+```
+
+Adding `data: { controller: 'autocomplete-select' }` will enable the autocomplete feature.
+
+## `current_currency`
+
+Returns the currently selected currency. By default in Admin Dashboard this will be `store.default_currency`. This can be changed in the `Settings -> Store Defaults` page.
+
+```erb
+<%= current_currency %>
+```
+
+will return
+
+```
+USD
+```
+
+## `current_store`
+
+Returns the current store [Spree::Store](https://github.com/spree/spree/blob/master/core/app/models/spree/store.rb) instance.
+
+```erb
+<%= current_store.name %>
+```
+
+## `current_vendor`
+
+<Info>
+ Only Spree Enterprise edition has this method.
+</Info>
+
+Returns the current vendor `Spree::Vendor` instance.
+
+```erb
+<%= current_vendor.name %>
+```
+
+## `icon`
+
+Displays an icon.
+
+```erb
+<%= icon('eye') %>
+```
+
+Will render
+
+```html
+<i class="ti ti-eye"></i>
+```
+
+We use [Tabler Icons](https://tabler.io/icons) library for icons.
+
+You can also pass additional options such as:
+
+<ParamField query="class" type="string">
+ Add additional CSS classes to the icon
+</ParamField>
+
+<ParamField query="style" type="string">
+ Add additional inline styles to the icon
+</ParamField>
+
+<ParamField query="height" type="integer">
+ Set the height of the icon in pixels
+</ParamField>
+
+```erb
+<%= icon('eye', class: 'mr-2', height: 20, style: 'color: red;') %>
+```
+
+will render
+
+```html
+<i class="ti ti-eye mr-2" style="font-size: 20px; color: red;"></i>
+```
+
+## `local_time`
+
+Displays a time in the user's timezone in a human readable format (based on the browser's timezone).
+
+```erb
+<%= local_time(order.sent_to_erp_at) %>
+```
+
+Provided by [local_time gem](https://github.com/basecamp/local_time).
+
+## `link_to_with_icon`
+
+Creates a link with an icon.
+
+```erb
+<%= link_to_with_icon 'eye', "View Order in ERP", "https://erp.com/orders/#{order.number}", class: "btn btn-primary" %>
+```
+
+* `eye` is the icon name.
+* `View Order in ERP` is the link text.
+* `https://erp.com/orders/#{order.number}` is the link url. For internal links, please use `spree.` routes helper, eg. `spree.admin_order_path(order)`.
+* `btn btn-primary` is the bootstrap class for styling the link
+
+## `supported_currencies`
+
+Returns the list of supported currencies for the current store as an array of strings.
+
+```erb
+<%= supported_currencies %>
+```
+
+will return
+
+```ruby
+["USD", "EUR"]
+```
+
+## `try_spree_current_user`
+
+Returns the current user object (class depends on the `Spree.admin_user_class` configuration). If the user is not signed in, it will return `nil`.
+
+```erb
+<%= try_spree_current_user.email %>
+```
+
+If you want to check if the user is signed in, you can use the following:
+
+```erb
+<%= try_spree_current_user.present? %>
+```
\ No newline at end of file
diff --git a/docs/developer/admin/navigation.mdx b/docs/developer/admin/navigation.mdx
new file mode 100644
index 0000000000..e69de29bb2
diff --git a/docs/developer/admin/permissions.mdx b/docs/developer/admin/permissions.mdx
new file mode 100644
index 0000000000..a583bab3e6
--- /dev/null
+++ b/docs/developer/admin/permissions.mdx
@@ -0,0 +1,54 @@
+---
+title: Admin Dashboard Permissions
+sidebarTitle: Permissions
+---
+
+## Overview
+
+Admin Dashboard utilizes [Spree's authorization system](/developer/customization/permissions) to control access to the different pages.
+
+## Restricting access to certain pages
+
+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`
+
+```ruby
+class CustomerServiceAbility
+ include CanCan::Ability
+
+ def initialize(user)
+ if user.respond_to?(:has_spree_role?) && user.has_spree_role?('customer_service')
+ can :manage, Spree::Order
+ end
+ end
+end
+```
+
+Please familiarize yourself with [CanCanCan](https://github.com/CanCanCommunity/cancancan) syntax to understand `can/cannot` methods more.
+
+Now we need to inform Spree to use this ability, create another file `app/models/spree/ability_decorator.rb` with contents:
+
+```ruby
+module Spree
+ module AbilityDecorator
+ def abilities_to_register
+ [CustomerServiceAbility]
+ end
+ end
+
+ Ability.prepend(AbilityDecorator)
+end
+```
+
+This will automatically remove all other pages/navigation items from the sidebar for the `customer_service` role.
+
+You can be even more granular with the permissions by using the `can` method.
+
+```ruby
+can :manage, Spree::Order
+can :read, Spree::Product
+can :update, Spree::Product
+```
+
+This will restrict the access to the `customer_service` role to only the Orders and Products pages. However they won't be able to delete products or add new ones, just update existing ones.
\ No newline at end of file
diff --git a/docs/developer/storefront/helper-methods.mdx b/docs/developer/storefront/helper-methods.mdx
new file mode 100644
index 0000000000..b133ea1254
--- /dev/null
+++ b/docs/developer/storefront/helper-methods.mdx
@@ -0,0 +1,68 @@
+---
+title: Storefront Helper Methods
+sidebarTitle: Helper Methods
+---
+
+Here you can find a list of helper methods provided by Spree that are available in the Storefront that you can use in every template.
+
+<Warning>
+The list is incomplete. We're working on it!
+</Warning>
+
+## `current_currency`
+
+Returns the currently selected currency. By default in the Storefront this will be `store.default_currency`. This can be changed in the `Settings -> Store Defaults` page.
+<%= current_currency %>
+```
+
+will return
+
+```
+USD
+```
+
+## `current_store`
+
+Returns the current store [Spree::Store](https://github.com/spree/spree/blob/master/core/app/models/spree/store.rb) instance.
+
+```erb
+<%= current_store.name %>
+```
+
+## `local_time`
+
+Displays a time in the user's timezone in a human readable format (based on the browser's timezone).
+
+```erb
+<%= local_time(order.sent_to_erp_at) %>
+```
+
+Provided by [local_time gem](https://github.com/basecamp/local_time).
+
+## `supported_currencies`
+
+Returns the list of supported currencies for the current store as an array of strings.
+
+```erb
+<%= supported_currencies %>
+```
+
+will return
+
+```ruby
+["USD", "EUR"]
+```
+
+## `try_spree_current_user`
+
+Returns the current user object (class depends on the `Spree.admin_user_class` configuration). If the user is not signed in, it will return `nil`.
+
+```erb
+<%= try_spree_current_user.email %>
+```
+
+If you want to check if the user is signed in, you can use the following:
+
+```erb
+<%= try_spree_current_user.present? %>
+```
\ No newline at end of file
diff --git a/docs/docs.json b/docs/docs.json
index 82e357f036..2acb36509e 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -1,7 +1,7 @@
{
"$schema": "https://mintlify.com/docs.json",
"name": "Spree Commerce documentation",
- "theme": "mint",
+ "theme": "maple",
"colors": {
"primary": "#0A2242",
"light": "#D7DFE9",
@@ -53,10 +53,24 @@
"developer/storefront/blocks",
"developer/storefront/links",
"developer/storefront/images",
+ "developer/storefront/helper-methods",
"developer/storefront/custom-javascript",
"developer/storefront/custom-css"
]
},
+ {
+ "group": "Admin Dashboard",
+ "icon": "gauge",
+ "pages": [
+ "developer/admin/admin",
+ "developer/admin/extending-ui",
+ "developer/admin/navigation",
+ "developer/admin/permissions",
+ "developer/admin/helper-methods",
+ "developer/admin/custom-javascript",
+ "developer/admin/custom-css"
+ ]
+ },
"developer/customization/authentication",
"developer/customization/checkout",
"developer/customization/permissions",
diff --git a/docs/images/developer/admin/dashboard_analytics_partials.png b/docs/images/developer/admin/dashboard_analytics_partials.png
new file mode 100644
index 0000000000..76a86dea99
Binary files /dev/null and b/docs/images/developer/admin/dashboard_analytics_partials.png differ
diff --git a/docs/images/developer/admin/dashboard_sidebar_partials.png b/docs/images/developer/admin/dashboard_sidebar_partials.png
new file mode 100644
index 0000000000..a2a5d6dbb5
Binary files /dev/null and b/docs/images/developer/admin/dashboard_sidebar_partials.png differ
diff --git a/docs/images/developer/admin/order_page_body_partials.png b/docs/images/developer/admin/order_page_body_partials.png
new file mode 100644
index 0000000000..679a20475d
Binary files /dev/null and b/docs/images/developer/admin/order_page_body_partials.png differ
diff --git a/docs/images/developer/admin/order_page_dropdown_partials.png b/docs/images/developer/admin/order_page_dropdown_partials.png
new file mode 100644
index 0000000000..e19d13914f
Binary files /dev/null and b/docs/images/developer/admin/order_page_dropdown_partials.png differ
diff --git a/docs/images/developer/admin/order_page_header_partials.png b/docs/images/developer/admin/order_page_header_partials.png
new file mode 100644
index 0000000000..078ab2db76
Binary files /dev/null and b/docs/images/developer/admin/order_page_header_partials.png differ
diff --git a/docs/images/developer/admin/order_page_sidebar_partials.png b/docs/images/developer/admin/order_page_sidebar_partials.png
new file mode 100644
index 0000000000..e9b01d2f77
Binary files /dev/null and b/docs/images/developer/admin/order_page_sidebar_partials.png differ
diff --git a/docs/images/developer/admin/order_page_summary_partials.png b/docs/images/developer/admin/order_page_summary_partials.png
new file mode 100644
index 0000000000..e09a8d8702
Binary files /dev/null and b/docs/images/developer/admin/order_page_summary_partials.png differ
diff --git a/docs/images/developer/admin/orders_filters_partials.png b/docs/images/developer/admin/orders_filters_partials.png
new file mode 100644
index 0000000000..d319017af3
Binary files /dev/null and b/docs/images/developer/admin/orders_filters_partials.png differ
diff --git a/docs/images/developer/admin/partial_injecting_example.png b/docs/images/developer/admin/partial_injecting_example.png
new file mode 100644
index 0000000000..1662c610f3
Binary files /dev/null and b/docs/images/developer/admin/partial_injecting_example.png differ
diff --git a/docs/images/developer/admin/product_dropdown_partials.png b/docs/images/developer/admin/product_dropdown_partials.png
new file mode 100644
index 0000000000..270b08b3f1
Binary files /dev/null and b/docs/images/developer/admin/product_dropdown_partials.png differ
diff --git a/docs/images/developer/admin/product_form_partials.png b/docs/images/developer/admin/product_form_partials.png
new file mode 100644
index 0000000000..b25aa27b15
Binary files /dev/null and b/docs/images/developer/admin/product_form_partials.png differ
diff --git a/docs/images/developer/admin/product_form_sidebar_partials.png b/docs/images/developer/admin/product_form_sidebar_partials.png
new file mode 100644
index 0000000000..55dab30230
Binary files /dev/null and b/docs/images/developer/admin/product_form_sidebar_partials.png differ
diff --git a/docs/images/developer/admin/products_filters_partials.png b/docs/images/developer/admin/products_filters_partials.png
new file mode 100644
index 0000000000..39e743cb0b
Binary files /dev/null and b/docs/images/developer/admin/products_filters_partials.png differ
diff --git a/docs/images/developer/admin/store_form_partials.png b/docs/images/developer/admin/store_form_partials.png
new file mode 100644
index 0000000000..ed52edeea4
Binary files /dev/null and b/docs/images/developer/admin/store_form_partials.png differ