Here's a sample dashboard with 2 widgets. With a name of
sample.erb
, it becomes accessible at
/sample
.
Each widget is represented by a div
element needing data-id
and data-view
attributes. The wrapping <li>
tags are used for layout.
data-id
: Sets the widget ID which will be used when pushing data to the widget. Two widgets can have the same widget id, allowing you to have the same widget in multiple dashboards. Push data to that id, and each instance will be updated.
data-view
: Specifies the type of widget that will be used.
Both these widgets are of the same type: Number
. However, using different data-
attributes lets you customize them. You can use any arbitrary attribute you want — each one will be available for you within the widget logic.
Anatomy of a widget
- an HTML file used for layout and bindings
- a SCSS file for styles
- a coffeescript file which allows you to handle incoming data & functionality
Number
widget's HTML:
Widgets use batman bindings in order to update their contents. Whenever the data changes, the DOM will automatically reflect the changes.
You may notice the piping '|' characters in some of the data-bind
's above. These are Batman Filters, and let you easily format the representation of data.
Number
widget's Coffeescript:
By default, whenever a widget receives JSON data, it mixes in the received data onto itself. This means that if you pass in data with a title
attribute, the widget's title
variable will change, and so will all DOM elements bound to it. No need to handle that yourself.
Laying out the widgets
Dashing uses gridster.js to create a layout for your widgets. Each widget is part of an unordered list. The <li>
element for a widget contains:
data-row
: What row the widget is on.
data-col
: What column the widget is on
data-sizex
: Integer size for the width of a widget
data-sizey
: Integer size for the height of a widget
For both data-row
and data-col
, you can leave them as 1, and gridster will automatically position your widgets.
If you want to customize the layout easily, simply navigate to your running dashboard, and drag the widgets with your mouse. You will be prompted to save the layout when you're finished. Follow the on-screen instructions.
For data-sizex
and data-sizey
, these are multiples of the widget dimensions you can configure in application.coffee