django-geckoboard 2.0.0

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,
    }

Version 2.0.0

• Add support for Python 3.4 and 4.5 and drop support for Python < 2.7; add support for Django 1.9 and drop support for Django < 1.8 (Matt Terry)

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

• First release, split off from django-analytical.