django-geckoboard 1.2.8

Geckoboard custom widgets for Django projects

Geckoboard is a hosted, real-time status board serving up indicators from web analytics, CRM, support, infrastructure, project management, sales, etc. It can be connected to virtually any source of quantitative data. This Django application provides view decorators to help create custom widgets.

Installation

To install django-geckoboard, simply place the django_geckoboard package somewhere on the Python path. You do not need to add it to the INSTALLED_APPS list, unless you want to run the tests.

Limiting access

If you want to protect the data you send to Geckoboard from access by others, you can use an API key shared by Geckoboard and your widget views. Set GECKOBOARD_API_KEY in the project settings.py file:

GECKOBOARD_API_KEY = 'XXXXXXXXX'

If you do not set an API key, anyone will be able to view the data by visiting the widget URL.

Encryption

Geckoboard encryption allows encrypting data before it is sent to Geckoboard's servers. After entering the password used to encrypt the data when the Geckoboard is loaded, the data will be decrypted in the browser.

To use encryption, first set a password in the project settings.py file:

GECKOBOARD_PASSWORD = 'XXXXXXXXX'

Next, enable encryption for each widget using the decorator arguments:

@number_widget(encrypted=True)
    def user_count(request):
        return User.objects.count()

Creating custom widgets

The available custom widgets are described in the Geckoboard support section, under Geckoboard API. From the perspective of a Django project, a custom widget is just a view. The django-geckoboard application provides view decorators that render the correct response for the different widgets.

Let's say you want to add a widget to your dashboard that shows the number of number of comments posted today. First create a view, using a django-geckoboard decorator:

from datetime import date, time, datetime
from django.contrib.comments.models import Comment
from django_geckoboard.decorators import number_widget

@number_widget
def comment_count(request):
    midnight = datetime.combine(date.today(), time.min)
    return Comment.objects.filter(submit_date__gte=midnight).count()

You can also specify the output format of the widget as either JSON or XML:

@number_widget(format='json')
def comment_count(request):
     midnight = datatime.combine(date.today(), time.min)
     return Comment.objects.filter(submit_data__get=midnight).count()

If your widget has optional settings, you can pass them in the decorator definition:

@number_widget(absolute='true')
def comment_count(request):
    midnight = datetime.combine(date.today(), time.min)
    return Comment.objects.filter(submit_date__gte=midnight).count()

Then use a URLconf module to map a URL to the view:

from django.conf.urls.defaults import *

urlpatterns = patterns('YOUR_VIEW_MODULE',
    ...
    (r'^geckoboard/comment_count/$', 'comment_count'),
)

This is all the Django code you need to display the comment count on your dashboard. When you create a custom widget in Geckoboard, enter the following information:

Encryption
Enable if the field is encrypted (see instructions above).
URL data feed
The view URL. In the example above this would be something like http://HOSTNAME/geckoboard/comment_count/.
API key
The content of the GECKOBOARD_API_KEY setting, if you have set it.
Widget type
Custom
Feed format
Either XML or JSON. If you don't specify a format the decorators will automatically detect and output the correct format or default to XML if this is not enabled (by default the format isn't appended by Geckoboard as a parameter any more)
Request type
Either GET or POST. The view decorators accept both.

The following decorators are available from the django_geckoboard.decorators module:

number_widget

Render a Number & Secondary Stat widget.

The decorated view must return a tuple (current, [previous], [prefix]) where the current parameter is the current value, optional previous parameter is the previous value of the measured quantity and the optional parameter prefix is the prefix used in Geckoboard widget. If there is only one parameter you do not need to return it in a tuple. For example, to render a widget that shows the number of users and the difference from last week:

from django_geckoboard.decorators import number_widget
from datetime import datetime, timedelta
from django.contrib.auth.models import User

@number_widget
def user_count(request):
    last_week = datetime.now() - timedelta(weeks=1)
    users = User.objects
    last_week_users = users.filter(date_joined__lt=last_week)
    return (users.count(), last_week_users.count())

@number_widget
def users_count_with_prefix(request):
    last_week = datetime.now() - timedelta(weeks=1)
    users = User.objects
    last_week_users = users.filter(date_joined__lt=last_week)
    return (users.count(), last_week_users.count(), '$')

rag_widget

Render a RAG Column & Numbers or RAG Numbers widget.

The decorated view must return a tuple with three tuples (value, [text]). The value parameters are the numbers shown in red, amber and green (in that order). The optional text parameters will be displayed next to the respective values in the dashboard.

For example, to render a widget that shows the number of comments that were approved or deleted by moderators in the last 24 hours:

from django_geckoboard.decorators import rag_widget
from datetime import datetime, timedelta
from django.contrib.comments.models import Comment, CommentFlag

@rag_widget
def comments(request):
    start_time = datetime.now() - timedelta(hours=24)
    comments = Comment.objects.filter(submit_date__gt=start_time)
    total_count = comments.count()
    approved_count = comments.filter(
            flags__flag=CommentFlag.MODERATOR_APPROVAL).count()
    deleted_count = Comment.objects.filter(
            flags__flag=CommentFlag.MODERATOR_DELETION).count()
    pending_count = total_count - approved_count - deleted_count
    return (
        (deleted_count, "Deleted comments"),
        (pending_count, "Pending comments"),
        (approved_count, "Approved comments"),
    )

text_widget

Render a Text widget.

The decorated view must return a list of tuples (message, [type]). The message parameters are strings that will be shown in the widget. The type parameters are optional and tell Geckoboard how to annotate the messages. Use TEXT_INFO for informational messages, TEXT_WARN for for warnings and TEXT_NONE for plain text (the default). If there is only one plain message, you can just return it without enclosing it in a list and tuple.

For example, to render a widget showing the latest Geckoboard twitter updates, using Mike Verdone's Twitter library:

from django_geckoboard.decorators import text_widget, TEXT_NONE
import twitter

@text_widget
def twitter_status(request):
    twitter = twitter.Api()
    updates = twitter.GetUserTimeline('geckoboard')
    return [(u.text, TEXT_NONE) for u in updates]

pie_chart

Render a Pie chart widget.

The decorated view must return an iterable over tuples (value, label, [color]). The optional color parameter is a string 'RRGGBB[TT]' representing red, green, blue and optionally transparency.

For example, to render a widget showing the number of normal, staff and superusers:

from django_geckoboard.decorators import pie_chart
from django.contrib.auth.models import User

@pie_chart
def user_types(request):
    users = User.objects.filter(is_active=True)
    total_count = users.count()
    superuser_count = users.filter(is_superuser=True).count()
    staff_count = users.filter(is_staff=True,
                               is_superuser=False).count()
    normal_count = total_count = superuser_count - staff_count
    return [
        (normal_count,    "Normal users", "ff8800"),
        (staff_count,     "Staff",        "00ff88"),
        (superuser_count, "Superusers",   "8800ff"),
    ]

line_chart

Render a Line chart widget.

The decorated view must return a tuple (values, x_axis, y_axis, [color]). The values parameter is a list of data points. The x-axis parameter is a label string or a list of strings, that will be placed on the X-axis. The y-axis parameter works similarly for the Y-axis. If there are more than one axis label, they are placed evenly along the axis. The optional color parameter is a string 'RRGGBB[TT]' representing red, green, blue and optionally transparency.

For example, to render a widget showing the number of comments per day over the last four weeks (including today):

from django_geckoboard.decorators import line_chart
from datetime import date, timedelta
from django.contrib.comments.models import Comment

@line_chart
def comment_trend(request):
    since = date.today() - timedelta(days=29)
    days = dict((since + timedelta(days=d), 0)
            for d in range(0, 29))
    comments = Comment.objects.filter(submit_date__gte=since)
    for comment in comments:
        days[comment.submit_date.date()] += 1
    return (
        days.values(),
        [days[i] for i in range(0, 29, 7)],
        "Comments",
    )

geck_o_meter

Render a Geck-O-Meter widget.

The decorated view must return a tuple (value, min, max). The value parameter represents the current value. The min and max parameters represent the minimum and maximum value respectively. They are either a value, or a tuple (value, text). If used, the text parameter will be displayed next to the minimum or maximum value.

For example, to render a widget showing the number of users that have logged in in the last 24 hours:

from django_geckoboard.decorators import geck_o_meter
from datetime import datetime, timedelta
from django.contrib.auth.models import User

@geck_o_meter
def login_count(request):
    since = datetime.now() - timedelta(hours=24)
    users = User.objects.filter(is_active=True)
    total_count = users.count()
    logged_in_count = users.filter(last_login__gt=since).count()
    return (logged_in_count, 0, total_count)

funnel

Render a Funnel widget.

The decorated view must return a dictionary with at least an items key. To render a funnel showing the breakdown of authenticated users vs. anonymous users:

from django_geckoboard.decorators import funnel
from django.contrib.auth.models import User

@funnel
def user_breakdown(request):
    all_users = User.objects
    active_users =all_users.filter(is_active=True)
    staff_users = all_users.filter(is_staff=True)
    super_users = all_users.filter(is_superuser=True)
    return {
        "items": [
            (all_users.count(), 'All users'),
            (active_users.count(), 'Active users'),
            (staff_users.count(), 'Staff users'),
            (super_users.count(), 'Super users'),
        ],
        "type": "standard",   # default, 'reverse' changes direction
                              # of the colors.
        "percentage": "show", # default, 'hide' hides the percentage
                              # values.
        "sort": False,        # default, `True` orders the values
                              # descending.
    }

bullet

Render a Bullet widget.

The decorated view must return a dictionary with at least keys label, axis_points, current and comparative. To render Geckoboard's own example at http://support.geckoboard.com/entries/274940-custom-chart-widget-type-definitions:

from django_geckoboard.decorators import bullet

@bullet
def geckoboard_bullet_example(request):
    return = {
        'label': 'Revenue 2011 YTD',
        'axis_points': [0, 200, 400, 600, 800, 1000],
        'current': 500,
        'comparative': 600,
        'sublabel': 'U.S. $ in thousands',
        'red': [0, 400],
        'amber': [401, 700],
        'green': [701, 1000],
        'projected': [100, 900],
        'auto_scale': False,
    }

Changelog

Version 1.2.8

  • Use json package directly (Max Lynch)

Version 1.2.7

  • Add support for encryption (Jeremy A. Johnson)
  • Allow setting output format in widget decorator (Rob Hudson)

Version 1.2.6

  • Allow number widget to return list of dicts (Arthur Furlan)

Version 1.2.5

  • Add support for the "prefix" parameter (Arthur Furlan)

Version 1.2.4

  • Add "Content-Type" header (Arthur Furlan)

Version 1.2.3

  • Fix KeyError bug in auto-scaling code (Ben Belchak)

Version 1.2.2

  • Fix comparative bar on bullet graphs (Rod Begbie)

Version 1.2.1

  • Fix unicode handling (Éric St-Jean)

Version 1.2.0

  • Add bullet widget decorator (Hedley Roos)

Version 1.1.0

  • Add funnel widget decorator (Simon de Haan)

Version 1.0.0

  • No changes from 0.2.1

Version 0.2.1

  • Fix API key detection

Version 0.2.0

  • Rename widget decorators

Version 0.1.0

MIT License

Author

Joost Cassee

Pip

django-geckoboard==1.2.8

Classifiers

  • Environment :: Web Environment
  • Framework :: Django
  • Intended Audience :: Developers
  • License :: OSI Approved :: MIT License
  • Operating System :: OS Independent
  • Programming Language :: Python
  • Development Status :: 4 - Beta
  • Topic :: Software Development :: Libraries :: Python Modules
  • Topic :: Internet :: WWW/HTTP
File Type Python Version Uploaded On Downloads
django-geckoboard-1.2.8.tar.gz Source March 9, 2015 4,283
Version Release Date
1.2.8 March 9, 2015
1.2.7 Oct. 10, 2013
1.2.6 Aug. 12, 2013
1.2.5 Aug. 7, 2013
1.2.4 July 25, 2013
1.2.3 Jan. 29, 2013
1.2.2 April 13, 2012
1.2.1 Nov. 5, 2011
1.2.0 July 12, 2011
1.1.0 March 23, 2011
1.0.0 Feb. 24, 2011
0.2.1 Feb. 15, 2011
0.2.0 Feb. 15, 2011
0.1.0 Feb. 14, 2011
Date Package Version Action
Aug. 24, 2015, 11:03 p.m. django-geckoboard 1.2.8 Release Created
Aug. 24, 2015, 11:03 p.m. django-geckoboard 0.1.0 Release Created
Aug. 24, 2015, 11:03 p.m. django-geckoboard 1.2.1 Release Created
Aug. 24, 2015, 11:03 p.m. django-geckoboard 1.2.0 Release Created
Aug. 24, 2015, 11:03 p.m. django-geckoboard 1.2.3 Release Created
Aug. 24, 2015, 11:03 p.m. django-geckoboard 1.2.2 Release Created
Aug. 24, 2015, 11:03 p.m. django-geckoboard 1.2.5 Release Created
Aug. 24, 2015, 11:03 p.m. django-geckoboard 1.2.4 Release Created
Aug. 24, 2015, 11:03 p.m. django-geckoboard 1.2.7 Release Created
Aug. 24, 2015, 11:03 p.m. django-geckoboard 1.2.6 Release Created
Aug. 24, 2015, 11:03 p.m. django-geckoboard 0.2.0 Release Created
Aug. 24, 2015, 11:03 p.m. django-geckoboard 0.2.1 Release Created
Aug. 24, 2015, 11:03 p.m. django-geckoboard 1.0.0 Release Created
Aug. 24, 2015, 11:03 p.m. django-geckoboard 1.1.0 Release Created
Aug. 24, 2015, 11:03 p.m. django-geckoboard Package Created