Custom JavaScript for 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. 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
• Turbo
• EasyPick (date picker)
• TomSelect (autocomplete/dropdowns)
• Sortable.js - sortable drag and drop lists
• Uppy - file uploader

You can find them in the app/assets/javascripts/vendor 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 to manage dependencies.

Install dependencies

To install dependencies you need to run the following command:

bin/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.

pin "react" # @19.1.0

Now you can just import the library in your application entry point, eg. application.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 directory.

You can find more information about Stimulus controllers in the Stimulus.js documentation.

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.

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

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

   <Tabs> <Tab title="Spree 5.2+"> ```ruby config/initializers/spree.rb Rails.application.config.after_initialize do Spree.admin.partials.head << 'spree/admin/shared/my_tracking_code' end ``` </Tab> <Tab title="Spree 5.1 and below"> ```ruby config/initializers/spree.rb Rails.application.config.spree_admin.head_partials << 'spree/admin/shared/my_tracking_code' ``` </Tab> </Tabs>

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.

   erbCopy

   <script>
     console.log("I'm a spy!");
   </script>