appboard

appboard is real-time dashboard for your application and business.

Dashboards tell people what's happening and should help them immediately recognize what needs their attention. Just like the dashboard of a car, which provides easily monitored measures of speed, remaining fuel, oil level, battery strength, engine trouble, and so on, a application and business information dashboard provides an overview that can be assimilated quickly.

Gem Installation

Install the appboard gem if you haven't already:

$ gem install appboard

Note that appboard does not require ActiveSupport or Rails. You can safely use it in your own Ruby projects.

Local setup

Before using appboard in your application, you need to let appboard know your API key, you do this (e.g. in an initializer):

require 'rubygems'
require 'appboard'

Appboard.settings ({ :apiKey => "abcd1234" })

or you could define API key in call block:

require 'rubygems'
require 'appboard'

Appboard.setup {
    apiKey "abcd1234"

    ...         
}

or,

require 'rubygems'
require 'appboard'

Appboard.push {
    apiKey "abcd1234"

    ...         
}

Deploying to Heroku

To use appboard on Heroku, install the appboard add-on:

$ heroku addons:add appboard

You can also do this from the Resources section of your application's configuration page on Heroku.

This will automatically create you an appboard.me account and create an default dashboard, and fill will set the Heroku configuration variables variables ENV['APPBOARD_API_URL'] and ENV['APPBOARD_API_KEY'].

Access your dashboard

Now you could access your dashboard (with default configuration) by following url: http://appboard.me/a/appName

Where,

appName - is name of application in Heroku.

e.g. for application quiet-sky-73 url will be http://appboard.me/a/quiet-sky-73

or, throw Heroku dashboard:

open Heroku dashboard
go to Resources of your application
on bottom of the page in Installed Add-ons section you will find Appboard Test, click on it. And you will redirected on your appboard dashboard.

Getting apiKey

You will need apiKey to setup or push data from local environment, application deployed on Heroku will get it from configuration variables.

Steps are following:

open Heroku dashboard
go to Resources of your application
on bottom of the page in Installed Add-ons section you will find Appboard Test, click on it. And you will redirected on your appboard dashboard.
on top of the page you will see gear, clock on it. Dasboard control pannel will appear, and on it you will find apiKey.

Usage

Setup Dashboard

After creating account (or deploying addon on Heroku) simple dashboard will be created for you with clocks :)

In order to update or create new dashboard you will need to setup it, and the moment this supported only via Ruby GEM.

You will need to define dashboard and place widgets in it. And there is supported widget parameters:

size: 1x1, 1x2, 1x3, 2x1, 2x2, 2x3, 3x1, 3x2 and 3x3.
type: Clock, Single Number, Alert, Bubble Chart, Funnel Chart, Line Chart, Bar Chart, Column Chart, Pie Chart, Radial Gauge, Filler Gauge. Check out list of available widgets.

We are continue working over new nice widgets!

There is simple example that updates default dashboard with new configuration:

require 'rubygems'
require 'appboard'

Appboard.settings = { :apiKey => '...' }    # required only for local environment
                                            # for Heroku will be taken from environment variables
Appboard.setup() {
    dashboard('My Dashboard') {
        width 5                             # defines widht of dashboard as 5 widgets

        widget('clock') {
            type "Clock"
            size "1x1"
        }

        widget('my indicator 1') {
            type "Single Number"
            size "1x1"
        }

        widget('my indicator 2') {
            type "Alert"
            size "1x1"
        }
    }
}

As result of this operation dashboard with three widgets (Clock, Simple Number and Alert) will be set. Server will return in result widget's uid (unique identifier) and this data will be stored in Appboard class.

You can access this data easily:

uidMyIndicator1 = Appboard.widget('my indicator1').uid

Note: If you are running this on local environment you will need to define apiKey before calling Appboard.setup, on Heroku apiKey will be injected during deploying appboard addon.

Appboard.settings = { :apiKey => '...', :debug => true }

You can find more examples for dashboard setup in our Git repository: one, two and three

Pushing your data to Widget

in context of Appboard - after dashboard is set by Appboard.setup configuration is stored in Appboard class, and you can easily push data to widget by widget name:

require 'rubygems'
require 'appboard'

Appboard.settings = { :apiKey => '...' }

Appboard.setup() {
    dashboard('My Dashboard') {
        widget('clock') {
            type "Clock"
            size "1x1"
        }

        widget('my indicator 1') {
            type "Single Number"
            size "1x1"
        }
    }
}

Appboard.widget('my indicator 1') {
    data do
        {
            :current => 100
        }
    end
}

by widget uid (unique identifier) - other way to push data to widget is define widget uid:

require 'rubygems'
require 'appboard'

Appboard.settings = { :apiKey => '...' }

Appboard.push {
    widget() {
        uid "[widgetUid]"
        data do
            {
                ...
            }
        end
    }
}

Each widget has its own page on this site. That page contains all the information you need in order to start working with the widget, including descriptions of data model (a piece that represents some kind of data).

More examples for different widgets you could find in our repository on GitHub.

NOTE: Don't forget to specify your apiKey and widget identifier.

What Should My Request Look Like?

Each widget has its own page on our documentation. That page contains all the information you need in order to start working with the widget, including descriptions of data model (a piece that represents some kind of data).