Create a new Widget - gottfrois/dashing-rails GitHub Wiki

Anatomy of a widget

A Widget is composed of 3 files:

  • an HTML file used for layout and bindings
  • a SCSS file for styles
  • a coffeescript file which allows you to handle incoming data & functionality

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.

To create a new Widget within your dashing application, simply do:

rails g dashing:widget sample_widget

The above command will create 3 new files:

  • app/assets/javascripts/dashing/widgets/sample_widget.coffee
  • app/assets/stylesheets/dashing/widgets/sample_widget.scss
  • app/views/dashing/widgets/sample_widget.html

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