/dashing-rails

The exceptionally handsome dashboard framework for Rails.

Primary LanguageRubyMIT LicenseMIT

Dashing

Code Climate Coverage Status Build Status Flattr Button Dependency Status codementor-button

Dashing-rails is the Rails Engine version of Dashing by Shopify. A huge thanks to Shopify for their great work with the Sinatra version.

Warning: To upgrade from 2.2.x to 2.3.x please read CHANGELOG.md.

Introduction

Dashing is a Rails engine that lets you build beautiful dashboards.

Click here for a video tutorial on how to use this gem:

dashing-rails-devcast

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

  • Ruby >=1.9.3
  • Rails 4
  • Redis
  • Multi Threaded server (puma, rainbows)

Getting Started

  1. Install the gem by adding the following in your Gemfile:
gem 'dashing-rails'
  1. Install puma server by adding the following in your Gemfile:
gem 'puma'
  1. Bundle install
$ bundle
  1. Install the dependencies using the following command:
$ rails g dashing:install
  1. Start redis server:
$ redis-server
  1. Open config/environments/development.rb and add:
config.allow_concurrency = true
  1. Start your server (must be a multi threaded server - See Requirements)
$ rails s
  1. Point your browser at http://localhost:3000/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 Server Sent Event 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/assets/javascripts/dashing/widgets/ — A widget's name .coffee file containing your widget's js.
  • app/assets/stylesheets/dashing/widgets/ — A widget's name .scss file containing your widget's css.
  • app/views/dashing/widgets/ — A widget's name .html file containing your widget's html.
  • 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: 1.second.since 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 credentials in config/initializers/dashing.rb:

config.redis_host     = '127.0.0.1'
config.redis_port     = '6379'
config.redis_password = '123456'

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 -X PUT http://localhost:3000/dashing/widgets/welcome -d "widget[text]=Dashing is awesome"

or

curl -X PUT http://localhost:3000/dashing/widgets/karma -d "widget[current]=100" -d "auth_token=YOUR_AUTH_TOKEN"

or

HTTParty.post('http://localhost:3000/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.

Create a new Widget

In order to create or add a custom widget to dashing-rails, simply follow the following steps:

  1. Run

     $ rails g dashing:widget my_widget

  2. Edit app/views/dashing/widgets/my_widget.html

  3. Edit app/assets/javascripts/dashing/widgets/my_widget.coffee

  4. Edit app/assets/stylesheets/dashing/widgets/my_widget.scss

You can also install pre-package widget compatible with dashing-rails. Here is a list of all Dashing-Rails compatible Widgets.

Note: the paths may be different depending on your dashing-rails configuration. Check your config/initializers/dashing.rb file.

Additional Resources

Check out the wiki for interesting tips such as hosting on Heroku, adding authentication or adding custom 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

Special thanks to Benjamin Roth for his ideas and support.

All contributions are more than welcome; especially new widgets!

Please add spec to your Pull Requests and run them using:

$ rake

License

Dashing is released under the MIT license

Bitdeli Badge