dashing

README

goDashing

goDashing is Golang based framework that lets you build beautiful dashboards. This project is a "fork" of the original project shopify/dashing and gigablah/dashing-go

Key features:

• Works out of the box, no server, runtime or dependency requiered.
• Use premade widgets, or fully create your own with css, html, and js.
• Pull Data from JIRA to your dashboard with a html attribute.
• Schedule and execute any script/binary file to feed data to your dashboard.
• Use the API to push data to your dashboards.

This dashing project was created at Shopify for displaying custom dashboards on TVs around the office.

Getting Started

1. Get the app here https://github.com/vjeantet/goDashing/releases

2. Start goDashing $ ./goDashing

3. Go to http://127.0.0.1:8080

   Your should see something like :

On the first start goDashing generates a demo dashboard and jobs to feed it.

Settings

• default http port is 8080
  • set a environnement variable PORT to change this.
• default working directory is the path where it starts
  • set WEBROOTenv var to change this.
• default api TOKEN is empty
  • set TOKENenv var to change this.

Create a new dashboard

create a name_here.gerb file in the dashboards folder

• every 20s, goDashing will switch to each dashboard it founds in this folder.
• you can group your dashboard in a folder.
  • example : dashboards/subfolder/dashboard1.gerb will be available to http://127.0.0.1:8080/subfolder/dashboard1.
  • doDash will auto switch dashboards it founds in the sub folder.

Customize layout

• modify dashboards/layout.gerb
  • if you add a layout.gerb in a dashboards/subfolder it will be used by goDashing when displaying a subfolder's dashboard.

Feed data to your dashboard

jobs folder usage

When you place a file in jobs folder Then goDashing will immediatly execute and schedule it according to this convention : NUMBEROFSECONDS_WIDGETID.ext

• the filename has 2 parts :
  • NUMBEROFSECONDS, interval in seconds for each execution of this file.
  • WIDGETID, the ID of the widget on your dashboard.

The output of the executed file should be a json representing the data to send to your widget, see examples in jobs folder.

2 cli arguments are provided to each executed file

1. The url of the current running goDashing
2. the token of the current running goDashing API

You can use this if you want to send data to multiple widgets. (see example)

PHP files

When you add a php file to the job folder, goDashing will assume php is available on your system, and will run it with it.

HTTP call usage (dashing API)

curl -d '{ "auth_token": "YOUR_AUTH_TOKEN", "text": "Hey, Look what I can do!" } http://127.0.0.1:8080/widgets/YOUR_WIDGET_ID

JIRA Jql and filters

Edit your .gerb dashboard to add jira attributes to your widget :

• jira-count-filter='17531' - goDashing will search jiras with this filter and feed the widget with issues count.
• jira-count-jql='resolution is EMPTY' - goDashing will search jiras with this JQL and feed the widget with issues count.
• jira-warning-over='10' - widget status will pass to warning when there is more dans 10 issues
• jira-danger-over='20' - widget status will pass to danger when there is more dans 20 issues

You don't need to restart goDashing when editing gerb files to take changes into account.

jira configuration

create a conf/jiraissuecount.ini file in goDashing working directory.

• set url, username, password, interval in the file,

url = "https://jira.atlassian.com/"
username = "" #if empty jira will be used anonymously
password =  ""
interval = 30

Use your custom assets, widgets...

• goDashing looks for assets in a public folder, when it can not found a file in this folder, it will use its embeded one.

Widgets

To add a custom widget "Test"

• create a widgets folder in working directory
  • create a Test folder
    • add the Test.js, Test.html, Test.css files in it.

goDashing will use them as soon as you set a widget with a data-view="Test"

Be sure to look at the list of third party widgets.

COFFEESCRIPT ? SCSS ? JS ? CSS ?

• convert coffeescript to js : http://js2.coffee
• convert scss to css : http://www.sassmeister.com

Documentation

Index

• func CamelCase(src string) string
• func Register(j Job)
• type Broker
  • func NewBroker() *Broker
  • func (b *Broker) Start()
• type Dashing
  • func NewDashing(root string, port string, token string) *Dashing
  • func (d *Dashing) ServeHTTP(w http.ResponseWriter, r *http.Request)
  • func (d *Dashing) Start() *Dashing
• type Event
  • func NewEvent(id string, data map[string]interface{}, target string) *Event
• type Job
• type Server
  • func NewServer(b *Broker) *Server
  • func (s *Server) DashboardEventHandler(w http.ResponseWriter, r *http.Request)
  • func (s *Server) DashboardHandler(w http.ResponseWriter, r *http.Request)
  • func (s *Server) EventsHandler(w http.ResponseWriter, r *http.Request)
  • func (s *Server) IndexHandler(w http.ResponseWriter, r *http.Request)
  • func (s *Server) NewRouter() http.Handler
  • func (s *Server) StaticHandler(w http.ResponseWriter, r *http.Request)
  • func (s *Server) WidgetEventHandler(w http.ResponseWriter, r *http.Request)
  • func (s *Server) WidgetHandler(w http.ResponseWriter, r *http.Request)
  • func (s *Server) WidgetsCSSHandler(w http.ResponseWriter, r *http.Request)
  • func (s *Server) WidgetsJSHandler(w http.ResponseWriter, r *http.Request)
• type Worker
  • func NewWorker(b *Broker) *Worker
  • func (w *Worker) Register(j Job)
  • func (w *Worker) Start()

Functions

func CamelCase

func CamelCase(src string) string

func Register

func Register(j Job)

Register a job to be kicked off upon starting a worker.

Types

type Broker

type Broker struct {
	// contains filtered or unexported fields
}

A Broker broadcasts events to multiple clients.

func NewBroker

func NewBroker() *Broker

NewBroker creates a Broker instance.

func (*Broker) Start

func (b *Broker) Start()

Start managing client connections and event broadcasts.

type Dashing

type Dashing struct {
	Broker *Broker
	Worker *Worker
	Server *Server
	Router http.Handler
	// contains filtered or unexported fields
}

Dashing struct definition.

func NewDashing

func NewDashing(root string, port string, token string) *Dashing

NewDashing sets up the event broker, workers and webservice.

func (*Dashing) ServeHTTP

func (d *Dashing) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP implements the HTTP Handler.

func (*Dashing) Start

func (d *Dashing) Start() *Dashing

Start actives the broker and workers.

type Event

type Event struct {
	ID     string
	Body   map[string]interface{}
	Target string
}

An Event contains the widget ID, a body of data, and an optional target (only "dashboard" for now).

func NewEvent

func NewEvent(id string, data map[string]interface{}, target string) *Event

type Job

type Job interface {
	Work(send chan *Event, webroot string, url string, token string)
}

A Job does periodic work and sends events to a channel.

type Server

type Server struct {
	// contains filtered or unexported fields
}

A Server contains webservice parameters and middlewares.

func NewServer

func NewServer(b *Broker) *Server

NewServer creates a Server instance.

func (*Server) DashboardEventHandler

func (s *Server) DashboardEventHandler(w http.ResponseWriter, r *http.Request)

DashboardEventHandler accepts dashboard events.

func (*Server) DashboardHandler

func (s *Server) DashboardHandler(w http.ResponseWriter, r *http.Request)

DashboardHandler serves the dashboard layout template.

func (*Server) EventsHandler

func (s *Server) EventsHandler(w http.ResponseWriter, r *http.Request)

EventsHandler opens a keepalive connection and pushes events to the client.

func (*Server) IndexHandler

func (s *Server) IndexHandler(w http.ResponseWriter, r *http.Request)

IndexHandler redirects to the default dashboard.

func (*Server) NewRouter

func (s *Server) NewRouter() http.Handler

NewRouter creates a router with defaults.

func (*Server) StaticHandler

func (s *Server) StaticHandler(w http.ResponseWriter, r *http.Request)

func (*Server) WidgetEventHandler

func (s *Server) WidgetEventHandler(w http.ResponseWriter, r *http.Request)

WidgetEventHandler accepts widget data.

func (*Server) WidgetHandler

func (s *Server) WidgetHandler(w http.ResponseWriter, r *http.Request)

WidgetHandler serves widget templates.

func (*Server) WidgetsCSSHandler

func (s *Server) WidgetsCSSHandler(w http.ResponseWriter, r *http.Request)

func (*Server) WidgetsJSHandler

func (s *Server) WidgetsJSHandler(w http.ResponseWriter, r *http.Request)

WidgetsJSHandler serves widget templates.

type Worker

type Worker struct {
	// contains filtered or unexported fields
}

A Worker contains a collection of jobs.

func NewWorker

func NewWorker(b *Broker) *Worker

NewWorker returns a Worker instance.

func (*Worker) Register

func (w *Worker) Register(j Job)

Register a job for a particular worker.

func (*Worker) Start

func (w *Worker) Start()

Start all jobs.