Extending Admin Dashboard 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:

Ensure you have the proper directory to store your templates:
```
mkdir -p app/views/spree/admin/shared
```
Create a new partial template file (partial templates file names start with underscore)
```
touch app/views/spree/admin/shared/_additional_footer.html.erb
```

Add your own code to the partial

<div class="mx-auto bg-light p-3 rounded-lg text-center w-10">
  Copyright <%= current_store.name %> <%= Time.current.year %>
</div>

Register your partial in config/initializers/spree.rb
```
Rails.application.config.spree_admin.body_end_partials << 'spree/admin/shared/additional_footer'
```
The key is the name of the injection point, eg. body_end_partials.

Remember to use the correct path to your partial and skip the _ prefix.
Restart your web server and you should see your new footer.

Making further changes to the partial template will not require you to restart the web server. They will be picked up automatically.

Admin Dashboard injection points

Here’s a list of all places you can inject your custom code:

Layout

<head>

<body>

</body>

Dashboard

Analytics

dashboard_analytics_partials

Injects code into the dashboard analytics section, eg.

<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>

Sidebar

dashboard_sidebar_partials

Injects code into the dashboard sidebar, eg.

<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>

Orders

Orders List Filters

orders_filters_partials

Variables

ActionView::Helpers::FormBuilder

The ActionView::Helpers::FormBuilder object.

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.

<%= f.text_field :q_number_cont, class: "form-control", data: { filters_target: :input } %>

q_number_cont - The name of the filter field. For filtering we’re using 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.
form-control - A bootstrap class for styling the input field.
data: { filters_target: :input } - Needed for the Stimulus Filters controller to work.

Order Page Dropdown

order_page_dropdown_partials

Variables

order

Spree::Order

The Spree::Order object.

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:

<%= link_to "View Order in ERP", "https://erp.com/orders/#{order.number}", class: "dropdown-item", target: "_blank" %>

dropdown-item is a bootstrap class for styling the dropdown item
target: "_blank" is used to open the link in a new tab

Order Page Header

order_page_header_partials

Variables

order

Spree::Order

The Spree::Order object.

Injects code into the order page header.

To add an additional action button near the ... button, you can use the following code:

Injects code into the order page header.

To add an additional action button near the ... button, you can use the following code:

<%= 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:

<%= 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 %>

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).

Order Page Body

order_page_body_partials

Variables

order

Spree::Order

The Spree::Order object.

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:

<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>

Order Page Sidebar

Products

Products List Filters

products_filters_partials

Variables

ActionView::Helpers::FormBuilder

The ActionView::Helpers::FormBuilder object.

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:

<%= f.text_field :q_name_cont, class: "form-control", data: { filters_target: :input } %>

q_name_cont is the name of the filter field. For filtering we’re using 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.
form-control is a bootstrap class for styling the input field.
data: { filters_target: :input } is needed for the Stimulus Filters controller to work.

Products Page Dropdown

product_dropdown_partials

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:

<%= link_to "View Product in WMS", "https://wms.com/products/#{product.id}", class: "dropdown-item", target: "_blank" %>

Your code will be placed before the dropdown divider.

Products Page Form

product_form_partials

Variables

ActionView::Helpers::FormBuilder

The ActionView::Helpers::FormBuilder object.

product

Spree::Product

The Spree::Product object.

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:

<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>

The partial will be displayed for both new product form and edit product form.

If you want to display the partial only on the edit product form, you can use the following code:

<% if product.persisted? %>
  <%# ... your code ... %>
<% end %>

And similarly for the new product form.

<% if product.new_record? %>
  <%# ... your code ... %>
<% end %>

Products Page Sidebar

product_form_sidebar_partials

Variables

ActionView::Helpers::FormBuilder

The ActionView::Helpers::FormBuilder object.

product

Spree::Product

The Spree::Product object.

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:

<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>

The partial will be displayed for both new product form and edit product form.

If you want to display the partial only on the edit product form, you can use the following code:

<% if product.persisted? %>
  <%# ... your code ... %>
<% end %>

And similarly for the new product form.

<% if product.new_record? %>
  <%# ... your code ... %>
<% end %>

Shipping Methods

Shipping Methods Form

shipping_method_form_partials

Variables

ActionView::Helpers::FormBuilder

The ActionView::Helpers::FormBuilder object.

shipping_method

Spree::ShippingMethod

The Spree::ShippingMethod object.

Injects code into the shipping method form. This partial has access to the f variable, which is the form builder for the shipping method form, and the shipping_method variable.

To add a new section to the shipping method form, you can use the following code:

<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_shipping_method_id, class: "form-control" %>
  </div>
</div>

Store Settings

Store Settings Form

store_form_partials

Variables

ActionView::Helpers::FormBuilder

The ActionView::Helpers::FormBuilder object.

store

Spree::Store

The Spree::Store object.

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:

<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>

Getting started

Customizing Spree

Use Cases

Deployment

Upgrading

Contributing

Security

Advanced

How it works

Admin Dashboard injection points

Layout

Dashboard

Orders

Variables

Variables

Variables

Variables

Products

Variables

Variables

Variables

Shipping Methods

Variables

Store Settings

Variables

Getting started

Customizing Spree

Use Cases

Deployment

Upgrading

Contributing

Security

Advanced

​How it works

​Admin Dashboard injection points

​Layout

​Dashboard

​Orders

​Products

​Shipping Methods

​Store Settings

How it works

Admin Dashboard injection points

Layout

Dashboard

Orders

Products

Shipping Methods

Store Settings