Statusboard

The statusboard gem provides a simple, expressive DSL which was purpose-built to feed your Panic-powered Status Board with data that matters to you. The DSL handles table, graph and DIY widgets in a way that renders messing around with raw data unnecessary.

The included server module makes serving the data to the app a simple and straight-forward process that doesn't require you to write any server-related code. The Rack-compliance of the server module makes the integration with existing systems a breeze.

Visit the Panic website for more information about the Status Board app.

Install the gem by either running gem install statusboard or by adding the line gem "statusboard" to your Gemfile and running the bundle command.

Create a file called statusboard.rb with the following contents:

require "statusboard/main"

widget "yequalsx", :graph do
	title "My first graph"
	type :line

	data do
		data_sequence do
			title "f(x) = x"

			(0..15).each do |n|
				datapoint n, n
			end
		end
	end
end

and run ruby statusboard.rb. A webserver which serves the widget will automatically be started on port 8080. In your Status Board App, add a graph widget and set the URL to your.ip:8080/widget/yequalsx. A graph widget containing the plot of the mathematical function f(x) = x will be displayed.

For further and more complex examples take a look at the examples directory.

The statusboard gem features a simple and expressive DSL which is used to configure and feed the widgets with data. Supported statements of the DSL are explained in the following paragraphs.

The widget statement is used to define a new widget with a specified name and type. The widgets name is used as the identifier of the widget and hence has to be unique. A block containing further DSL statements which describe the widget and its contents must be specified.

widget name, type do
	...
end

Supported types are :table, :diy and :graph. The specified type directly translates to the corresponding class, e.g. :table will use the class Statusboard::TableWidget.

Example:

widget :sales, :graph do
	...
end

The above code will define a graph-widget with the name sales. The widget will be available at the URL http://your.ip:8080/widget/sales/.

• Custom widget types are supported: Create a subclass of Statusboard::WidgetBase in the Statusboard module with a name like MycustomWidget (replace Mycustom). Then use the corresponding identifier (e.g. :mycustom) with the widget statement.
• You can create a widget manually (by instanciating the widgets class) and pass the resulting object directly to the widget statement as the second parameter. In this case, the block must not be specified.

my_diy = Statusboard::DiyWidget.new do
	...
end

widget :mycustom1, my_diy

A table widget provides one top-level statement: data, which accepts either a block or a proc. The specified block/proc should contain the code which is responsible to fetche the data which should be displayed. The block/proc will be executed every time the content of the widget is requested by the app. Within the block/proc, the DSL can be used to specify the data:

The row statement creates a new row. A block must be specified in which the cells of the row are specified. The only statement that is accepted within row is the cell statement.

The cell statement creates a cell within a row. A cell can have different properties (represented by the corresponding DSL statements) as listed below:

The following cell types are supported:

Example:

data_proc = Proc.new do
	row do
		cell do
			type :text
			content "First row with 20%"
		end

		cell do
			type :percentage
			percentage 20
		end
	end

	row do
		cell do
			type :text
			content "Second row with 80%"
		end

		cell do
			type :percentage
			percentage 80
		end
	end
end

widget :testtable, :table do
	data data_proc
end

A graph widget provides seven top-level statements:

The data statement is used to feed the graph widget with data. It provides exactly one statement: data_sequence. The statement defines a new data sequence, which is a collection of data points that belong together. The data points of a sequence taken together yield to the corresponding line in the graph.The statement can be called multiple times if multiple data sequences should be specified.

The data_sequence again takes a block which is used to configure the data sequence and to specify the data which should be displayed:

The following statement(s) are supported to configure the behavior of the X axis.

The following statement(s) are supported to configure the behavior of the Y axis.

widget "yequalsx", :graph do
	title "My first graph"
	type :line

	data do
		data_sequence do
			title "f(x) = x"

			(0..15).each do |n|
				datapoint n, n
			end
		end
	end
end

The DIY widget allows to create completely custom-made, HTML-based widgets. As a further abstraction is not possible, the widgets offers only one top-level statement: content. content awaits either a block, a proc or an arbitrary object which can be converted to a string.

Example:

widget "custom", :diy do
	content do
		%w[this is a test].join(" ")
	end
end

The gem can be deployed in three different ways:

In this scenario, the gem is used to create a standalone server application whose only purpose is to serve data to the Status Board app. As this is the prevalent case, the gem was designed to support this scenario without having to write any code other than the code that acts as the data source.

If this scenario fits your needs best, just add the line

require "statusboard/main"

to the top of your application file and define the widgets you want your Status Board to display using the DSL:

widget "widget-name", :widget-type do
	... use the DSL to describe the widget here
end

Run the file and a server is started automatically.

In this scenario, the gem is used within an existing, Rack-based server application. The included Rack module is mounted in the application (e.g. using the routes.rb file of a rails app).

To create a server instance which can be used in a Rack-based environment, include the required files by adding the line

require "statusboard"

to your application file.

Afterwards create the server instance and use its constructors block to describe the widgets which should be served:

app = Statusboard::StatusboardServer.new do
	widget ... do
    	...
    end
end

Use app as a parameter to the mount call to integrate the Status Board serving with your existing app.

The gem can be used to describe a widget and construct the Status Board compatible ouput without using any of its server components. This allows for an easy integration into existing applications like non-Rack-based web servers or the generation of data which is used and/or served statically later on.

To use only the data construction capabilities of the statusboard gem, add the following line to your application file:

require "statusboard"

Afterwards you can instanciate the classes Statusboard::DiyWidget, Statusboard::GraphWidget or Statusboard::TableWidget by passing a block containing the DSL statements to the constructor. Call the render method on a newly created object to retrieve the Status Board compatible output:

my_widget = Statusboard::DiyWidget.new do
	content "My first widget with custom content!"
end

puts my_widget.render

• Verify/discuss architecture of the gem
• Write meaningful tests
• Improve language of this document

1. Fork it ( https://github.com/julianschuh/statusboard/fork )
2. Read the ARCHITECTURE.md file
3. Create your feature branch (git checkout -b my-new-feature)
4. Commit your changes (git commit -am 'Add some feature')
5. Push to the branch (git push origin my-new-feature)
6. Create a new Pull Request