my_dashboard

Gem Version Issue Count Code Climate Coverage Status Build Status Dependency Status

my_dashboard is the Rails Engine version of Dashing by Shopify who uses flexbox instead gridster. This is totally inspired by Dashing-Rails. A huge thanks to Shopify and Pierre-Louis Gottfrois for their great work.

Introduction

my_dashboard is a Rails engine that lets you build beautiful dashboards with flexbox.

Check out our demo over here.

Key features:

  • Use premade widgets, or fully create your own with scss, html, and javascript.
  • Dashboards tottally responsive's using all the power of FlexBox.
  • 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 'my_dashboard'
  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 my_dashboard: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/my_dashboard/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 my_dashboard project comes with sample widgets & sample dashboards for you to explore. The directory is setup as follows:

  • app/views/my_dashboard/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/my_dashboard/widgets/ — A widget's name .js file containing your widget's js.
  • app/assets/stylesheets/my_dashboard/widgets/ — A widget's name .scss file containing your widget's css.
  • app/views/my_dashboard/widgets/ — A widget's name .html file containing your widget's html.
  • app/views/layouts/my_dashboard/ — 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

my_dashboard uses rufus-scheduler to schedule jobs. You can make a new job with rails g my_dashboard: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
MyDashboard.scheduler.every '1m', first_in: 1.second.since do |job|
  MyDashboard.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:

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

my_dashboard uses Redis to push and pull data and feed your widgets. Since my_dashboard 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 my_dashboard redis credentials in config/initializers/my_dashboard.rb:

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

By default my_dashboard subscribed to the following namespace in redis:

my_dashboard_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 my_dashboard uses the following namespace:

redis.publish("my_dashboard_events.create", {})

You can configure the redis namespace in config/initializers/my_dashboard.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 /my_dashboard/widgets/widget_id. For security, you will also have to include your auth_token (which you can generate in config/initializers/my_dashboard.rb).

Example:

curl -X PUT http://localhost:3000/my_dashboard/widgets/welcome -d "widget[text]=my_dashboard is awesome"

or

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

or

HTTParty.post('http://localhost:3000/my_dashboard/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 my_dashboard, simply follow the following steps:

  1. Run $ rails g my_dashboard:widget my_widget

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

  3. Edit app/assets/javascripts/my_dashboard/widgets/my_widget.js

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

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 Pierre-Louis Gottfrois for his Dashing-rails.

All contributions are more than welcome; especially new widgets with supports for flexbox and responsive.

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

License

my_dashboard is released under the MIT license