blessed-contrib
Build dashboards (or any other application) using ascii/ansi art and javascript.
Friendly to terminals, ssh and developers. Extends blessed with custom drawille and other widgets.
You should also check WOPR: a markup for creating terminal reports, presentations and infographics.
Contributors:
Yaron Naveh (@YaronNaveh) Chris (@xcezzz) Miguel Valadas (@mvaladas)
Demo (full size):
Running the demo
git clone https://github.com/yaronn/blessed-contrib.git
cd blessed-contrib
npm install
node ./examples/dashboard.js
Works on Linux, OS X and Windows. For Windows follow the pre requisites.
Installation (to build custom projects)
npm install blessed blessed-contrib
Usage
You can use any of the default widgets of blessed (texts, lists and etc) or the widgets added in blessed-contrib (described below). A layout is optional but useful for dashboards. The widgets in blessed-contrib follow the same usage pattern:
var blessed = contrib = screen = blessed line = contrib data = x: 't1' 't2' 't3' 't4' y: 5 1 7 5 screen //must append before setting data line screen; screen
See below for a complete list of widgets.
Widgets
Line Chart
var line = contrib var series1 = title: 'apples' x: 't1' 't2' 't3' 't4' y: 5 1 7 5 var series2 = title: 'oranges' x: 't1' 't2' 't3' 't4' y: 2 1 4 8 screen //must append before setting data line
Examples: simple line chart, multiple lines, 256 colors
Bar Chart
var bar = contrib screen //must append before setting data bar
Stacked Bar Chart
bar = contrib screen bar
Map
var map = contrib map
Gauge
var gauge = contrib gauge
Stacked Gauge
Either specify each stacked portion with a percent
and stroke
...
var gauge = contrib gauge
Or, you can just supply an array of numbers and random colors will be chosen.
var gauge = contrib gauge
Donut
var donut = contrib;
Data passed in uses percent
and label
to draw the donut graph. Color is optional and defaults to green.
donut;
Updating the donut is as easy as passing in an array to setData
using the same array format as in the constructor. Pass in as many objects to the array of data as you want, they will automatically resize and try to fit. However, please note that you will still be restricted to actual screen space.
LCD Display
var lcd = contrib
lcd; // will display "23G" lcd // adjust options at runtime
Please see the examples/lcd.js for an example. The example provides keybindings to adjust the segmentWidth
and segmentInterval
and strokeWidth
in real-time so that you can see how they manipulate the look and feel.
Rolling Log
var log = contrib log
Picture
(Also check the new blessed image implementation which has several benefits over this one.)
var pic = contrib {screen}
note: only png images are supported
Sparkline
var spark = contrib sparkline
Table
var table = contrib //allow control the table with the keyboard table table
Tree
var tree = contrib //allow control the table with the keyboard tree tree
Options
- keys : Key to expand nodes. Default : ['enter','default']
- extended : Should nodes be extended/generated by default? Be careful with this setting when using a callback function. Default : false
- template :
- extend : Suffix "icon" for closed node. Default : '[+]'
- retract : Suffix "icon" for opened node. Default : '[-]'
- lines : Show lines in tree. Default : true
Nodes
Every node is a hash and it can have custom properties that can be used in "select" event callback. However, there are several special keys :
- name
- Type :
string
- Desc : Node name
- If the node isn't the root and you don't specify the name, will be set to hash key
- Example :
{ name: 'Fruit'}
- Type :
- children
- Type :
hash
orfunction(node){ return children }
- Desc : Node children.
- The function must return a hash that could have been used as children property
- If you use a function, the result will be stored in
node.childrenContent
andchildren
- Example :
- Hash :
{'Fruit':{ name: 'Fruit', children:{ 'Banana': {}, 'Cherry': {}}}}
- Function : see
examples/explorer.js
- Hash :
- Type :
- childrenContent
- Type :
hash
- Desc : Children content for internal usage DO NOT MODIFY
- If
node.children
is a hash,node.children===node.childrenContent
- If
node.children
is a function, it's used to store thenode.children()
result - You can read this property, but you should never write it.
- Usually this will be used to check
if(node.childrenContent)
in yournode.children
function to generate children only once
- Type :
- extended
- Type :
boolean
- Desc : Determine if this node is extended
- No effect when the node have no child
- Default value for each node will be
treeInstance.options.extended
if the nodeextended
option is not set - Example :
{'Fruit':{ name: 'Fruit', extended: true, children:{ 'Banana': {}, 'Cherry': {}}}}
- Type :
Markdown
var markdown = contrib markdown
Colors
You can use 256 colors (source):
{ return Math * 255Math*255 Math*255 } line = contrib
Layouts
Grid
A grid layout can auto position your elements in a grid layout. When using a grid, you should not create the widgets, rather specify to the grid which widget to create and with which params. Each widget can span multiple rows and columns.
var screen = blessed var grid = rows: 12 cols: 12 screen: screen //grid.set(row, col, rowSpan, colSpan, obj, opts) var map = grid var box = grid screen
Carousel
A carousel layout switches between different views based on time or keyboard activity. One use case is an office dashboard with rotating views:
var blessed = contrib = screen = blessed { var map = contrib screen } { var line = contrib var data = title: 'us-east' x: 't1' 't2' 't3' 't4' y: 0 00695652173913043 011304347826087 2 style: line: 'red' screen line } screen; var carousel = page1 page2 screen: screen interval: 3000 //how often to switch views (set 0 to never swicth automatically) controlKeys: true //should right and left keyboard arrows control view rotation carouselstart
Samples
Terminal Dashboard
Running the sample
git clone https://github.com/yaronn/blessed-contrib.git
cd blessed-contrib
npm install
node ./examples/dashboard.js
Installation (for a custom dashboard)
npm install blessed
npm install blessed-contrib
A simple dashboard
var blessed = contrib = screen = blessed grid = rows: 1 cols: 2 screen: screen var line = grid var map = grid var lineData = x: 't1' 't2' 't3' 't4' y: 5 1 7 5 line screen; screen
Rich dashboard
See source code
Troubleshooting
If you see questions marks or some (or all) missign characters try running with these env vars to fix encoding / terminal:
$> LANG=en_US.utf8 TERM=xterm-256color node your-code.js
License
This library is under the MIT License