Blessed

Build terminal dashboards using ascii/ansi art and javascript

CLIDashboard
yaronn/blessed-contribblessed-contrib

README

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)
Liran Tal (@lirantal)

Demo (full size):

termterm

(source code)

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:

  1. ````` js
  2.    var blessed = require('blessed')
  3.      , contrib = require('blessed-contrib')
  4.      , screen = blessed.screen()
  5.      , line = contrib.line(
  6.          { style:
  7.            { line: "yellow"
  8.            , text: "green"
  9.            , baseline: "black"}
  10.          , xLabelPadding: 3
  11.          , xPadding: 5
  12.          , label: 'Title'})
  13.      , data = {
  14.          x: ['t1', 't2', 't3', 't4'],
  15.          y: [5, 1, 7, 5]
  16.       }
  17.    screen.append(line) //must append before setting data
  18.    line.setData([data])

  20.    screen.key(['escape', 'q', 'C-c'], function(ch, key) {
  21.      return process.exit(0);
  22.    });

  24.    screen.render()
  25. `````

See below for a complete list of widgets.


Widgets


Line Chart

Bar Chart

Stacked Bar Chart

Map

Gauge

Stacked Gauge

Donut

LCD Display

Rolling Log

Picture

Sparkline

Table

Tree

Markdown

Line Chart


line

  1. ````` js
  2.    var line = contrib.line(
  3.          { style:
  4.            { line: "yellow"
  5.            , text: "green"
  6.            , baseline: "black"}
  7.          , xLabelPadding: 3
  8.          , xPadding: 5
  9.          , showLegend: true
  10.          , wholeNumbersOnly: false //true=do not show fraction in y axis
  11.          , label: 'Title'})
  12.    var series1 = {
  13.          title: 'apples',
  14.          x: ['t1', 't2', 't3', 't4'],
  15.          y: [5, 1, 7, 5]
  16.       }
  17.    var series2 = {
  18.          title: 'oranges',
  19.          x: ['t1', 't2', 't3', 't4'],
  20.          y: [2, 1, 4, 8]
  21.       }
  22.    screen.append(line) //must append before setting data
  23.    line.setData([series1, series2])
  24. `````
Examples: simple line chart, multiple lines, 256 colors

Bar Chart


bar

  1. ````` js
  2.     var bar = contrib.bar(
  3.        { label: 'Server Utilization (%)'
  4.        , barWidth: 4
  5.        , barSpacing: 6
  6.        , xOffset: 0
  7.        , maxHeight: 9})
  8.     screen.append(bar) //must append before setting data
  9.     bar.setData(
  10.        { titles: ['bar1', 'bar2']
  11.        , data: [5, 10]})
  12. `````

Stacked Bar Chart


stacked-bar

  1. ````` js
  2.     bar = contrib.stackedBar(
  3.        { label: 'Server Utilization (%)'
  4.        , barWidth: 4
  5.        , barSpacing: 6
  6.        , xOffset: 0
  7.        //, maxValue: 15
  8.        , height: "40%"
  9.        , width: "50%"
  10.        , barBgColor: [ 'red', 'blue', 'green' ]})
  11.     screen.append(bar)
  12.     bar.setData(
  13.        { barCategory: ['Q1', 'Q2', 'Q3', 'Q4']
  14.        , stackedCategory: ['US', 'EU', 'AP']
  15.        , data:
  16.           [ [ 7, 7, 5]
  17.           , [8, 2, 0]
  18.           , [0, 0, 0]
  19.           , [2, 3, 2] ]
  20.        })
  21. `````

Map


map

  1. ````` js
  2.    var map = contrib.map({label: 'World Map'})
  3.    map.addMarker({"lon" : "-79.0000", "lat" : "37.5000", color: "red", char: "X" })
  4. `````


Gauge


gauge

  1. ````` js
  2.    var gauge = contrib.gauge({label: 'Progress', stroke: 'green', fill: 'white'})
  3.    gauge.setPercent(25)
  4. `````

Stacked Gauge


stackedgauge

Either specify each stacked portion with a percent and stroke...

  1. ````` js
  2.    var gauge = contrib.gauge({label: 'Stacked '})
  3.    gauge.setStack([{percent: 30, stroke: 'green'}, {percent: 30, stroke: 'magenta'}, {percent: 40, stroke: 'cyan'}])
  4. `````

Or, you can just supply an array of numbers and random colors will be chosen.

  1. ````` js
  2.    var gauge = contrib.gauge({label: 'Stacked Progress'})
  3.    gauge.setStack([30,30,40])
  4. `````

Donut


donut


  1. ````` js
  2.    var donut = contrib.donut({
  3. label: 'Test',
  4. radius: 8,
  5. arcWidth: 3,
  6. remainColor: 'black',
  7. yPadding: 2,
  8. data: [
  9.    {percent: 80, label: 'web1', color: 'green'}
  10. ]
  11.   });
  12. `````

Data passed in uses percent and label to draw the donut graph. Color is optional and defaults to green.

  1. ````` js
  2.    donut.setData([
  3.     {percent: 87, label: 'rcp','color': 'green'},
  4. {percent: 43, label: 'rcp','color': 'cyan'},
  5.    ]);
  6. `````

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.

You can also hardcode a specific numeric into the donut's core display instead of the percentage by passing an percentAltNumber property to the data, such as:

  1. ````` js
  2.    var donut = contrib.donut({
  3. label: 'Test',
  4. radius: 8,
  5. arcWidth: 3,
  6. remainColor: 'black',
  7. yPadding: 2,
  8. data: [
  9.    {percentAltNumber: 50, percent: 80, label: 'web1', color: 'green'}
  10. ]
  11.   });
  12. `````

See an example of this in one of the donuts settings on ./examples/donut.js.

LCD Display


lcd

  1. ````` js
  2.    var lcd = contrib.lcd(
  3.      { segmentWidth: 0.06 // how wide are the segments in % so 50% = 0.5
  4.      , segmentInterval: 0.11 // spacing between the segments in % so 50% = 0.550% = 0.5
  5.      , strokeWidth: 0.11 // spacing between the segments in % so 50% = 0.5
  6.      , elements: 4 // how many elements in the display. or how many characters can be displayed.
  7.      , display: 321 // what should be displayed before first call to setDisplay
  8.      , elementSpacing: 4 // spacing between each element
  9.      , elementPadding: 2 // how far away from the edges to put the elements
  10.      , color: 'white' // color for the segments
  11.      , label: 'Storage Remaining'})
  12. `````

  1. ````` js

  3. lcd.setDisplay(23 + 'G'); // will display "23G"
  4. lcd.setOptions({}) // adjust options at runtime

  6. `````

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


log

  1. ````` js
  2.    var log = contrib.log(
  3.       { fg: "green"
  4.       , selectedFg: "green"
  5.       , label: 'Server Log'})
  6.    log.log("new log line")
  7. `````


Picture


(Also check the new blessed image implementation which has several benefits over this one.)

log

  1. ````` js
  2.     var pic = contrib.picture(
  3.        { file: './flower.png'
  4.        , cols: 25
  5.        , onReady: ready})
  6.     function ready() {screen.render()}
  7. `````

note: only png images are supported


Sparkline


spark

  1. ````` js
  2.    var spark = contrib.sparkline(
  3.      { label: 'Throughput (bits/sec)'
  4.      , tags: true
  5.      , style: { fg: 'blue' }})

  7.    sparkline.setData(
  8.    [ 'Sparkline1', 'Sparkline2'],
  9.    [ [10, 20, 30, 20]
  10.    , [40, 10, 40, 50]])
  11. `````

Table


table

  1. ````` js
  2.    var table = contrib.table(
  3.      { keys: true
  4.      , fg: 'white'
  5.      , selectedFg: 'white'
  6.      , selectedBg: 'blue'
  7.      , interactive: true
  8.      , label: 'Active Processes'
  9.      , width: '30%'
  10.      , height: '30%'
  11.      , border: {type: "line", fg: "cyan"}
  12.      , columnSpacing: 10 //in chars
  13.      , columnWidth: [16, 12, 12] /*in chars*/ })

  15.    //allow control the table with the keyboard
  16.    table.focus()

  18.    table.setData(
  19.    { headers: ['col1', 'col2', 'col3']
  20.    , data:
  21.       [ [1, 2, 3]
  22.       , [4, 5, 6] ]})
  23. `````

Tree


table

  1. ````` js
  2.    var tree = contrib.tree({fg: 'green'})

  4.    //allow control the table with the keyboard
  5.    tree.focus()

  7.    tree.on('select',function(node){
  8.      if (node.myCustomProperty){
  9.        console.log(node.myCustomProperty);
  10.      }
  11.      console.log(node.name);
  12.    }

  14.    // you can specify a name property at root level to display root
  15.    tree.setData(
  16.    { extended: true
  17.    , children:
  18.      {
  19.        'Fruit':
  20.        { children:
  21.          { 'Banana': {}
  22.          , 'Apple': {}
  23.          , 'Cherry': {}
  24.          , 'Exotics': {
  25.              children:
  26.              { 'Mango': {}
  27.              , 'Papaya': {}
  28.              , 'Kiwi': { name: 'Kiwi (not the bird!)', myCustomProperty: "hairy fruit" }
  29.              }}
  30.          , 'Pear': {}}}
  31.      , 'Vegetables':
  32.        { children:
  33.          { 'Peas': {}
  34.          , 'Lettuce': {}
  35.          , 'Pepper': {}}}}})
  36. `````

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'}
children
  Type : hash or function(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 and children
  Example :
* Hash : {'Fruit':{ name: 'Fruit', children:{ 'Banana': {}, 'Cherry': {}}}}
    Function : see examples/explorer.js
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 the node.children() result
  You can read this property, but you should never write it.
  Usually this will be used to check if(node.childrenContent) in your node.children function to generate children only once
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 node extended option is not set
* *Example* : {'Fruit':{ name: 'Fruit', extended: true, children:{ 'Banana': {}, 'Cherry': {}}}}

Markdown


table

  1. ````` js
  2.    var markdown = contrib.markdown()
  3.    markdown.setMarkdown('# Hello \n blessed-contrib renders markdown using `marked-terminal`')
  4. `````

Colors

You can use 256 colors (source):

  1. ````` js
  2.   function randomColor() {
  3.     return [Math.random() * 255,Math.random()*255, Math.random()*255]
  4.   }

  6.   line = contrib.line(
  7.   {
  8.     ...
  9.     , style: { line: randomColor(), text: randomColor(), baseline: randomColor() }
  10.   })
  11. `````
  

Layouts


Grid

Carousel

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.

  1. ````` js
  2.    var screen = blessed.screen()

  4.    var grid = new contrib.grid({rows: 12, cols: 12, screen: screen})

  6.    //grid.set(row, col, rowSpan, colSpan, obj, opts)
  7.    var map = grid.set(0, 0, 4, 4, contrib.map, {label: 'World Map'})
  8.    var box = grid.set(4, 4, 4, 4, blessed.box, {content: 'My Box'})

  10.    screen.render()
  11. `````

Carousel

A carousel layout switches between different views based on time or keyboard activity.
One use case is an office dashboard with rotating views:

  1. ````` js
  2.     var blessed = require('blessed')
  3.       , contrib = require('./')
  4.       , screen = blessed.screen()

  6.     function page1(screen) {
  7.        var map = contrib.map()
  8.        screen.append(map)
  9.     }

  11.     function page2(screen) {
  12.       var line = contrib.line(
  13.        { width: 80
  14.        , height: 30
  15.        , left: 15
  16.        , top: 12
  17.        , xPadding: 5
  18.        , label: 'Title'
  19.        })

  21.       var data = [ { title: 'us-east',
  22.                  x: ['t1', 't2', 't3', 't4'],
  23.                  y: [0, 0.0695652173913043, 0.11304347826087, 2],
  24.                  style: {
  25.                   line: 'red'
  26.                  }
  27.                }
  28.             ]

  30.       screen.append(line)
  31.       line.setData(data)
  32.     }

  34.     screen.key(['escape', 'q', 'C-c'], function(ch, key) {
  35.       return process.exit(0);
  36.     });

  38.     var carousel = new contrib.carousel( [page1, page2]
  39.                                        , { screen: screen
  40.                                          , interval: 3000 //how often to switch views (set 0 to never swicth automatically)
  41.                                          , controlKeys: true  //should right and left keyboard arrows control view rotation
  42.                                          })
  43.     carousel.start()

  45. `````

Samples



Terminal Dashboard


term

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

  1. ````` js
  2.    var blessed = require('blessed')
  3.      , contrib = require('blessed-contrib')
  4.      , screen = blessed.screen()
  5.      , grid = new contrib.grid({rows: 1, cols: 2, screen: screen})

  7.    var line = grid.set(0, 0, 1, 1, contrib.line,
  8.      { style:
  9.        { line: "yellow"
  10.        , text: "green"
  11.        , baseline: "black"}
  12.      , xLabelPadding: 3
  13.      , xPadding: 5
  14.      , label: 'Stocks'})

  16.    var map = grid.set(0, 1, 1, 1, contrib.map, {label: 'Servers Location'})

  18.    var lineData = {
  19.       x: ['t1', 't2', 't3', 't4'],
  20.       y: [5, 1, 7, 5]
  21.    }

  23.    line.setData([lineData])

  25.    screen.key(['escape', 'q', 'C-c'], function(ch, key) {
  26.      return process.exit(0);
  27.    });

  29.    screen.render()
  30. `````

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:
  1. `````
  2.     $> LANG=en_US.utf8 TERM=xterm-256color node your-code.js
  3. `````

License

This library is under the MIT License

More Information

Created by Yaron Naveh (twitter, blog)