Implementing a Solidus store, you may need to change how the Admin Panel works. Solidus allows the full customization of your store Admin Panel (also referred to as backend) and this page shows how to implement frequently requested changes.
At the moment there are two ways of changing an Admin Panel view:
You can override original views by creating a file in your host application with the same path of the one you want to change, copy/pasting the content of the original file into the new one and editing it.
For example, if you want to customize
, you have
to create a new file at
the original content into it and change the relevant part.
Please, be sure to copy the file corresponding to the version of Solidus that you are using: 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.
The disadvantages of this approach are that, if that view changes in a future version of Solidus, you could have problems since your view code does not match with the rest of the Solidus codebase at the newer version.
Deface is a gem that allows changing part of your views without overriding them entirely and it was born to fix the issue described in the previous approach.
Suppose you want to customize backend/app/views/spree/admin/orders/index.html.erb , changing the following block:
<div class="no-objects-found"> <%= render 'spree/admin/shared/no_objects_found', resource: Spree::Order, new_resource_url: spree.new_admin_order_path %> </div>
<div class="no-objects-found"> <h2>No Order found</h2> </div>
With deface you can to create a new file at
that will describe the change you want to make to original erb file, For example:
<!-- replace_contents ".no-objects-found" --> <div class="no-objects-found"> <h2>No Order found</h2> </div>
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.
Upgrading to a newer version of Solidus, view modifications done with Deface are less likely to break your store, since only a small part of the view has been changed, but this approach has some downsides as well:
Often, when adding new pages to the Admin Panel, there's the 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( [:section], 'icon-name', url: 'https://solidus.io/' ) end
See Spree::BackendConfiguration::MenuItem documentation for more information about menu items customizations.
Admin UI has a search form in nearly all pages that list resources items, for
These forms come with a set of fields that we can use to perform the 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
add a new form input wherever you think it fits better.
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, you need to add the following field in the search form:
<div class="field"> <%= label_tag :q_last_ip_address_eq, t('spree.email_contains') %> <%= f.text_field :last_ip_address_eq %> </div>
last_ip_address_eq is part of a matchers DSL provided by
see its documentation for more information.
Additionally, for security reasons, you need to whitelist the new attribute
needed for the search using a specific method provided by
This can be easily done by adding the following line into the
Spree::Order.whitelisted_ransackable_attributes << 'last_ip_address'
Solidus is an open source platform supported by the community. We encourage everyone using Solius to contribute back to the documentation and the code.