Dashing
Dashing-rails is the Rails Engine version of Dashing by Shopify. A huge thanks to Shopify for their great work with the Sinatra version.
Introduction
Dashing is a Rails engine that lets you build beautiful dashboards.
Check out a demo over here. Here's another one, optimized for 1080p screens.
Key features:
- Use premade widgets, or fully create your own with scss, html, and coffeescript.
- Widgets harness the power of data bindings to keep things DRY and simple. Powered by batman.js.
- Use the API to push data to your dashboards, or make use of a simple ruby DSL for fetching data.
- Drag & Drop interface for re-arranging your widgets.
- Host your dashboards on Heroku in less than 30 seconds.
Requirements
Getting Started
-
Install the gem by adding the following in your
Gemfile
:gem 'dashing-rails'
-
Install puma server by adding the following in your
Gemfile
:gem 'puma'
-
Bundle install
$ bundle
-
Install the dependecies using the following command:
$ rails g dashing:install
-
Restart your server (must be a multi threaded server - See Requirements)
$ puma
-
Start redis server:
$ redis-server
-
Open
config/development.rb
and add:config.allow_concurrency = true
-
Point your browser at http://0.0.0.0:9292/dashing/dashboards and have fun!
Important Note: We need to update the configuration in development to handle multiple requests at the same time. One request for the page we’re working on, and another request for the SSE controller.
Every new Dashing project comes with sample widgets & sample dashboards for you to explore. The directory is setup as follows:
app/views/dashing/dashboards
— One .erb file for each dashboard that contains the layout for the widgets.app/jobs
— Your ruby jobs for fetching data (e.g for calling third party APIs like twitter).app/views/dashing/widgets
— All the html/css/coffee for individual widgets.app/views/layouts/dashing/
— All your custom layouts where your dashboards and widgets will be included.
Getting Data Into Your Widgets
Providing data to widgets is easy. You specify which widget you want using a widget id, and then pass in the JSON data. There are two ways to do this:
Jobs
Dashing uses rufus-scheduler to schedule jobs. You can make a new job with rails g dashing:job sample_job
, which will create a file in the jobs directory called sample_job.rb
.
Example:
# :first_in sets how long it takes before the job is first run. In this case, it is run immediately
Dashing.scheduler.every '1m', :first_in => 0 do |job|
Dashing.send_event('karma', { current: rand(1000) })
end
This job will run every minute, and will send a random number to ALL widgets that have data-id
set to 'karma'.
You send data using the following method:
Dashing.send_event(widget_id, json_formatted_data)
Jobs are where you put stuff such as fetching metrics from a database, or calling a third party API like Twitter. Since the data fetch is happening in only one place, it means that all instances of widgets are in sync.
Server Sent Events are used in order to stream data to the dashboards.
Redis
Dashing uses Redis to push and pull data and feed your widgets. Since Dashing Requirements can be quite frustrating, I thought it might be useful to use redis.
This way you can have a seperate Rails 4 application (with puma) running your dashboards and push your data to redis from your main Rails 3 application for example.
You can specify Dashing redis connection in config/initializers/dashing.rb
:
config.redis = your_redis_instance
By default Dashing subscribed to the following namespace in redis:
dashing_events.*
where *
can be anything. This give you all the flexibility you need to push to redis. For example the send_event
method provided by Dashing uses the following namespace:
redis.publish("dashing_events.create", {})
You can configure the redis namespace in config/initializers/dashing.rb
:
config.redis_namespace = 'your_redis_namespace'
API
Widgets
Your widgets can be updated directly over HTTP. Post the data you want in json to /dashing/widgets/widget_id
. For security, you will also have to include your auth_token
(which you can generate in config/initializers/dashing.rb
).
Example:
curl -d '{ "auth_token": "YOUR_AUTH_TOKEN", "current": 100 }' http://0.0.0.0:9292/dashing/widgets/karma
or
HTTParty.post('http://0.0.0.0:9292/dashing/widgets/karma',
body: { auth_token: "YOUR_AUTH_TOKEN", current: 1000 }.to_json)
Dasboards
The reload
action provided by Shopify Dashing is currently not available.
Additional Resources
Check out the wiki for interesting tips such as hosting on Heroku, or adding authentication.
For more information on Dashboards and Widgets HTML/CSS/JS, please read Shopify Dashing documentation.
Be sure to look at the list of third party widgets.
Browser Compatibility
Tested in Chrome, Safari 6+, and Firefox 15+.
Does not work in Internet Explorer because it relies on Server Sent Events.
Contributors
All contributions are more than welcome; especially new widgets!
License
Dashing is released under the MIT license