blessed-contrib

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.

Contributors:

Yaron Naveh (@YaronNaveh)

Demo (full size):

(source code)

Running the demo

git clone https://github.com/yaronn/blessed-contrib.git
cd blessed-contrib
npm install
node ./examples/dashboard.js

Tested on Linux and OS X. In order to use on windows need to install Braille fonts (not tested).

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 bellow). A layout is optional but usefull for dashboards. The widgets in blessed-contrib follow the same usage pattern:

   var blessed = require('blessed')
     , contrib = require('blessed-contrib')
     , screen = blessed.screen()
     , line = contrib.line(
         { style: 
           { line: "yellow"
           , text: "green"
           , baseline: "black"}
         , xLabelPadding: 3
         , xPadding: 5
         , label: 'Title'})
     , data = {
         x: ['t1', 't2', 't3', 't4'],
         y: [5, 1, 7, 5]
      }
   screen.append(line) //must append before setting data
   line.setData([data])
   
   screen.key(['escape', 'q', 'C-c'], function(ch, key) {
     return process.exit(0);
   });

   screen.render()

See bellow for a complete list of widgets.

Widgets

Line Chart

Bar Chart

Map

Gauge

Rolling Log

Picture

Sparkline

Table

Tree

Line Chart

   var line = contrib.line(
         { style: 
           { line: "yellow"
           , text: "green"
           , baseline: "black"}
         , xLabelPadding: 3
         , xPadding: 5
         , showLegend: true
         , wholeNumbersOnly: false //true=do not show fraction in y axis
         , label: 'Title'})
   var series1 = {
         title: 'apples',
         x: ['t1', 't2', 't3', 't4'],
         y: [5, 1, 7, 5]
      }
   var series2 = {
         title: 'oranges',
         x: ['t1', 't2', 't3', 't4'],
         y: [5, 1, 7, 5]
      }
   screen.append(line) //must append before setting data
   line.setData([series1, series2])

Examples: simple line chart, multiple lines

Bar Chart

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

Map

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

Gauge

   var gauge = contrib.gauge({label: 'Progress'})
   gauge.setPercent(25)

Rolling Log

   var log = contrib.log(
      { fg: "green"
      , selectedFg: "green"
      , label: 'Server Log'})
   log.log("new log line")

Picture

    var pic = contrib.picture(
       { file: './flower.png'
       , cols: 25
       , onReady: ready})
    function ready() {screen.render()}

note: only png images are supported

Sparkline

   var spark = contrib.sparkline(
     { label: 'Throughput (bits/sec)'
     , tags: true
     , style: { fg: 'blue' }})

   sparkline.setData(
   [ 'Sparkline1', 'Sparkline2'], 
   [ [10, 20, 30, 20]
   , [40, 10, 40, 50]])

Table

   var table = contrib.table(
     { keys: true
     , fg: 'green'
     , label: 'Active Processes'
     , columnSpacing: 10 //in chars
     , columnWidth: [16, 12, 12] /*in chars*/ })

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

   table.setData(
   { headers: ['col1', 'col2', 'col3']
   , data: 
      [ [1, 2, 3] 
      , [4, 5, 6] ]})

Tree

   var tree = contrib.tree({fg: 'green'})

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

   tree.on('select',function(node){
     if (node.myCustomProperty){
       console.log(node.myCustomProperty);
     }
     console.log(node.name);
   }

   // you can specify a name property at root level to display root
   tree.setData(
   { extended: true
   , children:
     {
       'Fruit':
       { children:
         { 'Banana': {}
         , 'Apple': {}
         , 'Cherry': {}
         , 'Exotics': {
             children: 
             { 'Mango': {}
             , 'Papaya': {}
             , 'Kiwi': { name: 'Kiwi (not the bird!)', myCustomProperty: "hairy fruit" }
             }}
         , 'Pear': {}}}
     , 'Vegetables':
       { children:
         { 'Peas': {}
         , 'Lettuce': {}
         , 'Pepper': {}}}}})

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 is sevral 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': {}}}}

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.

   var screen = blessed.screen()

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

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

   screen.render()

Carousel

A carousel layout switchs between differen views based on time or keyboard activity. One use case is office dashboard with rotating views

    var blessed = require('blessed')
      , contrib = require('./')
      , screen = blessed.screen()

    function page1(screen) {     
       var map = contrib.map()   
       screen.append(map) 
    }

    function page2(screen) {  
      var line = contrib.line(
       { width: 80
       , height: 30
       , left: 15
       , top: 12  
       , xPadding: 5
       , label: 'Title'
       })

      var data = [ { title: 'us-east',
                 x: ['t1', 't2', 't3', 't4'],
                 y: [0, 0.0695652173913043, 0.11304347826087, 2],
                 style: {
                  line: 'red'
                 }
               }
            ]

      screen.append(line)
      line.setData(data)  
    }

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

    var carousel = new contrib.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
                                         })
    carousel.start()

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 dashbaord)

npm install blessed
npm install blessed-contrib

A simple dashboard

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

   var line = grid.set(0, 0, 1, 1, contrib.line, 
     { style: 
       { line: "yellow"
       , text: "green"
       , baseline: "black"}
     , xLabelPadding: 3
     , xPadding: 5
     , label: 'Stocks'})

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

   var lineData = {
      x: ['t1', 't2', 't3', 't4'],
      y: [5, 1, 7, 5]
   }

   line.setData([lineData])

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

   screen.render()

Rich dashboard

See source code

License

This library is under the MIT License

More Information

Created by Yaron Naveh (twitter, blog)