When developing a Solidus store you may need to change how the Admin Panel works. Solidus allows you to fully customize your store's Admin Panel (also referred to as the "backend"). This page shows you how to implement frequently requested changes.
There are two ways of changing an Admin Panel view:
You can override the original views by creating a file in your host application with the same path as the one you want to change. Copy and paste the contents of the original file into the new one and edit it.
For example, if you want to customize
create a new file at
app/views/spree/admin/orders/index.html.erb and copy
the original contents into it. Make any desired changes to the newly copied file. Solidus
will pick up the modified version of the file in your repository, and display
the changes in the backend.
It is important to be sure you are copying the file that corresponds to the version of Solidus that you are using. For example, if your production store uses Solidus 2.8, you must copy the files from the 2.8 branch. Once you've identified your version (usually through your Gemfile), you can switch to the right branch using the branch selector in the GitHub UI.
There is one disadvantage to this approach: If your modified view changes in a future version of Solidus, you could face unexpected problems since your view code does not match with the rest of the Solidus codebase in the newer version.
Deface is a gem that allows you to selectively change part of your views without overriding them entirely. It was created to fix the disadvantage described in the previous approach.
Suppose you want to customize backend/app/views/spree/admin/orders/index.html.erb , changing the following block:
<%= render 'spree/admin/shared/no_objects_found',
new_resource_url: spree.new_admin_order_path %>
<h2>No Order found</h2>
With deface you can create a new file at
and use Deface's DSL to change only part of the original erb file, like so:
<h2>No Order found</h2>
Before rendering the original view, Deface will modify its content following
the instructions contained in the
Check out the Deface documentation for more information about the provided DSL and other usage examples.
The benefit is that view modifications made with Deface are less likely to break your store when you upgrade to future versions of Solidus, since only a small part of the view has been changed. This approach has some downsides as well, though:
When adding new pages to the Admin Panel you will often need to add a new item in the main menu to reach the newly added pages.
It's easy to add new menu items. Just add the following lines in the
Spree::Backend::Config.configure do |config|
config.menu_items << config.class::MenuItem.new(
See Spree::BackendConfiguration::MenuItem documentation for more information about menu items customizations.
The admin UI has a search form in nearly every page that lists resource items. For
These forms come with a set of fields that we can use to search against. Technically, they are just an interface to use the ransack gem.
To add a new field you need to change the view that contains the search form.
In this case you change
and add a new form
input wherever you think it fits best.
Please read the Views paragraph to understand how to change the original template.
For example, if you want to add a search field that allows you to filter orders completed with a specific IP address, just add the following field in the search form:
<%= label_tag :q_last_ip_address_eq, t('spree.email_contains') %>
<%= f.text_field :last_ip_address_eq %>
last_ip_address_eq is part of a matchers DSL provided by
See the ransack documentation for more information.
Additionally, for security reasons you will need to whitelist the new attribute
needed for the search. You do this by using a specific method provided by
. The easiest way to achieve this is by adding a decorator
which will update the attributes. This ensures that the code is reloaded correctly
when needed - using an initializer does not work with Rails 6+ and Zeitwerk. For this
example, you would add the following code to
base.whitelisted_ransackable_attributes << 'last_ip_address'
Solidus is an open source platform supported by the community. We encourage everyone using Solidus to contribute back to the documentation and the code.