Skip to content

danjenkins/node-geckoboard-push

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

70 Commits
lib
lib
 
 
.gitignore
.gitignore
 
 
.travis.yml
.travis.yml
 
 
README.md
README.md
 
 
index.js
index.js
 
 
package.json
package.json
 
 

Repository files navigation

#geckoboard-push#

NodeJS implementation of the Geckoboard legacy API, this has been replaced with a a new DataSets API####

##Install##

npm install geckoboard-push

##Usage##

var Geckoboard = require('geckoboard-push');

var foo = new Geckoboard({api_key: 'geckoboard_api_key'});

###Options###

####Required####

  • api_key The key given to you in your account settings under API

####Optional#### (These options should never need to be changed)

  • params.host defaults to push.geckoboard.com
  • port defaults to 443 for https
  • method defaults to POST
  • path defaults to '/v1/send/' + current_widget_key

##Methods##

Details of types can be found at geckoboards docs:

###Map###

var bar = foo.map('map_widget_key');
bar.send(items, function(err, response){
  //callback with response from geckoboard
})

Items is an Array of Objects

[
  {
    city: {
      city_name: "london",
      country_code: "GB",
      region_code: "P5",
    },
    size: 8, /*Optional. Default = 3 */
    color: "d8f709", /*Optional. Hex color.*/
    cssclass: "mycss" /*Optional. Allows for custom CSS on the geckoboard dashboard */
  },
  {
    city: {
      city_name: "San Francisco",
      region_code: "CA",
      country_code: "US"
    }
  },
  {
    latitude: "51.526263",
    longitude: "-0.092429"
  },
  {
    latitude: "-33.94336",
    longitude: "18.896484"
  },
  {
    host: "geckoboard.com"
  },
  {
    ip: "178.125.193.227"
  }
]

###Monitoring###

var bar = foo.monitoring('number_widget_key');
bar.send(status, downTime, responseTime, function(err, response){
  //callback with response from geckoboard
});

status can have the values 'Up' and 'Down', downTime and responseTime are optional

###Number###

var bar = foo.number('number_widget_key');
bar.send(items, absolute, type, function(err, response){
  //callback with response from geckoboard
});

Items is an Array of Objects

[
  { 
    text : "Some Text",
    value : 123 
  },
  {
    text : "Some more Text",
    value : 238,
    prefix: "£"
  }
]

Absolute allows you to show numerical differences instead of Percentage based - defaults to false, can be set to true Type allows you to reverse the colours - defaults to standard, set to reverse or standard

###Text###

var bar = foo.text('text_widget_key');
bar.send(items, function(err, response){
  //callback with response from geckoboard
});

Items is an Array of Objects

[
  {text: "message c", type : 0},
  {text : "message d", type : 2},
  {text : "message e", type : 1}
]

Type has three different values:

  • 0 - None (no corner icon)
  • 1 - Alert (yellow corner icon)
  • 2 - Info (grey corner icon)

There can be up to 10 of these Objects The text can be plain or styled HTML

###Bullet###

var bar = foo.bullet('bullet_widget_key');
bar.send(items, orientation, function(err, response){
  //callback with response from geckoboard
});

Items is an Array of Objects

[
  {
    label: "Revenue 2011 YTD",
    sublabel: "(U.S. $ in thousands)",
    axis: {
      point: [
        0,
        200,
        400,
        600,
        800,
        1000
      ]
    },
    range:[
      { color: "red",
        start: 0,
        end: 400
      },
      {
        color: "amber",
        start: 401,
        end: 700
      },
      { 
        color: "green",
        start: 701,
        end: 1000
      }
    ],
    measure: {
      current: {
        start: 0,
        end: 500
      },
      projected: {
        start: 100,
        end: 900
      }
    },
    comparative: {
      point: 600
    }
  }
]

Orientation is the orientation you'd like the bullet widgets, default is horizontal, but can be changed to vertical

###Rag Column###

var bar = foo.ragColumn('rag_column_widget_key');
bar.send(items, type, function(err, response){
  //callback with response from geckoboard
})

Items is an array of Objects

[
  {
    value: 120,
    text: "Red description"
  },
  {
    value: 75,
    text: "Amber description"
  },
  {
    value: 5,
    text: "Green description"
  }
]

The type parameter accepts one value reverse. If supplied then the order of the items will be reversed.

###Rag###

var bar = foo.rag('rag_widget_key');
bar.send(items, type, function(err, response){
  //callback with response from geckoboard
})

Items is an array of Objects

[
  {
    value: 120,
    text: "Red description"
  },
  {
    value: 75,
    text: "Amber description"
  },
  {
    value: 5,
    text: "Green description"
  }
]

The type parameter accepts one value reverse. If supplied then the order of the items will be reversed.

###Funnel###

var bar = foo.funnel('funnel_widget_key');
foo.send(items, type, percentage, function(err, response){
  //callback with response from geckoboard
})

Items is an Array of Objects

[
  { 
    value: "87809", 
    label: "Step1" 
  }, 
  { 
    value: "70022", 
    label: "Step2" 
  }, 
  { 
    value: "63232", 
    label: "Step 3" 
  }, 
  { 
    value: "53232", 
    label: "Step 4" 
  }, 
  { 
    value: "32123", 
    label: "Step 5" 
  }, 
  { 
    value: "23232", 
    label: "Step 6" 
  }, 
  { 
    value: "12232", 
    label: "Step 7" 
  }, 
  { 
    value: "2323", 
    label: "Step 8" 
  } 
]

Type allows you to reverse the colours - defaults to standard, set to reverse or standard Percentage allows you to show or hide % - defaults to show, set to show or hide

###Pie###

var bar = foo.pie('pie_widget_key');
bar.send(items, function(err, response){
  //callback with response from geckoboard
})

Items is an Array of Objects

[ 
  { 
    value: "100", 
    label: "May", 
    colour: "FFFF10AA" 
  }, 
  { 
    value: "160", 
    label: "June", 
    colour: "FFAA0AAA" 
  }, 
  { 
    value: "300", 
    label: "July", 
    colour: "FF5505AA" 
  }, 
  { 
    value: "140", 
    label: "August", 
    colour: "FF0000AA" 
  } 
]

The last 2 digits in the hex colour attribute are entirely optional and represent the desired transparency.

###Gecko Meter###

var bar = foo.geckoMeter('gecko_meter_widget_key');
bar.send(value, min, max, type, function(err, response){
  //callback with response from geckoboard
})

Value is the Value of the meter Min is an Object

{
  text : "Min value",
  value : "10"
}

Max is an Object

{ 
  text: "Max value",
  value: "30"
}

Type allows you to reverse the colours - defaults to standard, set to reverse or standard

###Line###

var bar = foo.line('line_widget_key');
bar.send(items, settings, function(err, response){
  //callback with response from geckoboard
})

Items is an Array of values

[
    {
        "label": {
            "name": "Label1",
            "color": "#d4e1aa"
        },
        "title": {
            "text": "Important information 1",
            "highlight": true
        },
        "description": "A small description"
    },
    {
        "title": {
            "text": "Important information 2",
            "highlight": true
        }
    }
]

Settings is an Object which contains x and y axis detail and colour detail in hex format

{
  "axisx": [
    "Jun",
    "Jul",
    "Aug"
  ],
  "axisy": [
    "Min",
    "Max"
  ],
  "colour": "ff9900"
}

###LineV2###

var linev2 = foo.linev2('linev2_widget_key');
linev2.send(data, function(err, response){
  //callback with response from geckoboard
})

data is an object as definined by the Geckoboard API

{
  "y_axis": {
    "format": "currency",
    "unit": "USD"
  },
  "series": [
    {
      "name": "GBP -> USD",
      "data": [
        1.62529,
        1.56991,
        1.50420,
        1.52265,
        1.55356,
        1.51930,
        1.52148,
        1.51173,
        1.55170,
        1.61966,
        1.59255,
        1.63762
      ]
    }
  ]
}

###List###

var bar = foo.list('list_widget_key');
bar.send(items, function(err, response){
  //callback with response from geckoboard
})

Items is an Array of values as defined by the Geckoboard API

[
  {
    "title": {
      "text": "Chrome"
    },
    "label": {
      "name": "New!",
      "color": "#ff2015"
    },
    "description": "40327 visits"
  },
  {
    "title": {
      "text": "Safari"
    },
    "description": "11577 visits"
  },
  {
    "title": {
      "text": "Firefox"
    },
    "description": "10296 visits"
  },
  {
    "title": {
      "text": "Internet Explorer"
    },
    "description": "3587 visits"
  },
  {
    "title": {
      "text": "Opera"
    },
    "description": "499 visits"
  }
]

###Highchart###

var bar = foo.highchart('highchart_widget_key');
bar.send(highchart, function(err, response){
  //callback with response from geckoboard
})

highchart is a Highchart configuration object - see: http://www.geckoboard.com/developers/custom-widgets/widget-types/highcharts/

{
  chart: {
    renderTo: 'container'
  },
  credits: {
    enabled: false
  },
  series: {
    your_stuff
  }
}

##Examples##

var Geckoboard = require('geckoboard-push');

var gecko = new Geckoboard({api_key: 'geckoboard_api_key'});

var map = gecko.map('map_widget_key');
map.send([
  { 
    latitude: 1.00000,
    longitude: 1.0000,
    size: 10
  }
], function(err, response){
  console.log('map', response);
})

var number = gecko.number('number_widget_key');
number.send([ 
  { text : "Visitors",value : 300},
  { text : "",value : 280}
], true, 'reverse', function(err, response){
  console.log('number', response);
});

var text = gecko.text('text_widget_key');
text.send([
  {text: "message c", type : 0},
  {text : "message d", type : 2},
  {text : "message e", type : 1}
], function(err, response){
  console.log('text', response);
});

var bullet = gecko.bullet('bullet_widget_key');
bullet.send([{
  label: "Revenue 2011 YTD",
  sublabel: "(U.S. $ in thousands)",
  axis: {
    point: [
      0,
      200,
      400,
      600,
      800,
      1000
    ]
  },
  range:[
    { color: "red",
      start: 0,
      end: 400
    },
    {
      color: "amber",
      start: 401,
      end: 700
    },
    { 
      color: "green",
      start: 701,
      end: 1000
    }
  ],
  measure: {
    current: {
      start: 0,
      end: 500
    },
    projected: {
      start: 100,
      end: 900
    }
  },
  comparative: {
    point: 600
  }
}, {
  label: "Revenue 2012 YTD",
  sublabel: "(££££ in thousands)",
  axis: {
    point: [
      0,
      200,
      400,
      600,
      800,
      1000
    ]
  },
  range:[
    { color: "red",
      start: 0,
      end: 400
    },
    {
      color: "amber",
      start: 401,
      end: 700
    },
    { 
      color: "green",
      start: 701,
      end: 1000
    }
  ],
  measure: {
    current: {
      start: 0,
      end: 500
    },
    projected: {
      start: 100,
      end: 900
    }
  },
  comparative: {
    point: 600
  }
}],'vertical', function(err, response){
  console.log('bullet', response);
});

var ragColumn = gecko.ragColumn('rag_column_widget_key');
ragColumn.send([
  {
    value: 120,
    text: "Red description"
  },
  {
    value: 75,
    text: "Amber description"
  },
  {
    value: 5,
    text: "Green description"
  }
], 'reverse',function(err, response){
  console.log('rag column', response);
})

var rag = gecko.rag('rag_widget_key');
rag.send([
  {
    value: 132,
    text: "Red description"
  },
  {
    value: '80',
    text: "Amber description"
  },
  {
    value: 3,
    text: "Green description"
  }
], 'standard', function(err, response){
  console.log('RAG', response);
})

var funnel = gecko.funnel('funnel_widget_key');
funnel.send([
  { 
    value: "87809", 
    label: "Step1" 
  }, 
  { 
    value: "70022", 
    label: "Step2" 
  }, 
  { 
    value: "63232", 
    label: "Step 3" 
  }, 
  { 
    value: "53232", 
    label: "Step 4" 
  }, 
  { 
    value: "32123", 
    label: "Step 5" 
  }, 
  { 
    value: "23232", 
    label: "Step 6" 
  }, 
  { 
    value: "12232", 
    label: "Step 7" 
  }, 
  { 
    value: "2323", 
    label: "Step 8" 
  } 
], 'standard','show', function(err, response){
  console.log('Funnel', response);
})

var pie = gecko.pie('pie_widget_key');
pie.send([ 
  { 
    value: "100", 
    label: "May", 
    colour: "FFFF10AA" 
  }, 
  { 
    value: "160", 
    label: "June", 
    colour: "FFAA0AAA" 
  }, 
  { 
    value: "300", 
    label: "July", 
    colour: "FF5505AA" 
  }, 
  { 
    value: "140", 
    label: "August", 
    colour: "FF0000AA" 
  } 
], function(err, response){
  console.log('pie', response);
})

var geckometer = gecko.geckoMeter('gecko_meter_widget_key');
geckometer.send(
  23,
  {
    text : "Min value",
    value : "10"
  },
  { 
    text: "Max value",
    value: "30"
  },
  'reverse',
  function(err, response){
  console.log('geckometer', response)
})

var line = gecko.line('line_widget_key');
line.send([
  "12.3",
  "2.3",
  "10",
  "15",
  "15",
  "13",
  "12.1",
  "9.8",
  "12.3",
  "2.3",
  "10",
  "15",
  "15",
  "13",
  "12.1",
  "9.8",
  "11",
  "16",
  "15",
  "13",
  "10",
  "7"
],
{
  "axisx": [
    "Jun",
    "Jul",
    "Aug"
  ],
  "axisy": [
    "Min",
    "Max"
  ],
  "colour": "ff9900"
}, function(err, response){
  console.log('Line', response);
})

var highchart = gecko.highchart('line_widget_key');
highchart.send({
  chart: { type: 'bar' },
  title: { text: 'Unique visits by Country' },
  subtitle: { text: 'Today' },
  xAxis: {
    categories: ['USA', 'Canada', 'France', 'Australia', 'Germany'],
    title: { text: null }
  },
  yAxis: {
    min: 0,
    title: {
      text: 'Visits',
      align: 'high'
    },
    labels: { overflow: 'justify' }
  },
  tooltip: { valueSuffix: null },
  plotOptions: {
    bar: {
      dataLabels: { enabled: true }
    }
  },
  credits: { enabled: false },
  series: [{
    name: 'Visits',
    data: [107, 31, 635, 203, 2]
  }]
}, function(err, response){
  console.log('Line', response);
})

###Leaderboard###

var bar = foo.leaderboard('leaderboard_widget_key');
bar.send(items, format, unit, function(err, response){
  //callback with response from geckoboard
})

Items is an Array of values

[
    {
        "label": "Something gaining",
        "value": 100,
        "previous_rank": 3,
    },
    {
        "label": "Something staying",
        "value": 90
    },
    {
        "label": "Something losing",
        "value": 80,
        "previous_rank": 1
    }
]

###Bar###

var barChart = foo.barchart('bar_widget_key');
bar.send(data, function(err, response){
  //callback with response from geckoboard
})

data is an object as definined by the Geckoboard API

{
  "x_axis": {
    "labels": [
      "2000",
      "2001",
      "2002",
      "2003",
      "2004",
      "2005"
    ]
  },
  "y_axis": {
    "format": "currency",
    "unit": "USD"
  },
  "series": [
    {
      "data": [
        1000,
        1500,
        30600,
        28800,
        22300,
        36900
      ]
    }
  ]
}

Format allows you to optionally change the number format. Defaults to decimal.

Unit is a ISO 4217 currency code. Required when format is currency.

##NPM Maintainers##

The npm module for this library is maintained by:

##License##

geckoboard-push is licensed under the MIT license.

About

Interface into Geckoboard's push API

Resources

Readme
Activity

Stars

34 stars

Watchers

6 watching

Forks

14 forks
Report repository

Releases

13 tags

Packages

No packages published

Contributors 11

Languages