Django项目的Geckoboard自定义小部件
项目描述
Geckoboard 是一个托管实时状态板，提供来自网络分析、CRM、支持、基础设施、项目管理、销售等的指标。它可以连接到几乎任何定量数据源。此 Django 应用程序提供了视图装饰器，以帮助创建自定义小部件。
安装
要安装 django-geckoboard，只需将 django_geckoboard 包放置在Python路径上的某个位置。除非您想运行测试，否则不需要将其添加到 INSTALLED_APPS 列表。
限制访问
如果您想保护您发送到Geckoboard的数据免受他人访问，您可以使用Geckoboard和您的部件视图共享的API密钥。在项目的 settings.py 文件中设置 GECKOBOARD_API_KEY
GECKOBOARD_API_KEY = 'XXXXXXXXX'
如果您没有设置API密钥，任何人都可以通过访问部件URL来查看数据。
加密
Geckoboard加密允许在将数据发送到Geckoboard服务器之前对其进行加密。在加载Geckoboard时输入用于加密数据的密码后，数据将在浏览器中解密。
要使用加密，首先在项目的 settings.py 文件中设置密码
GECKOBOARD_PASSWORD = 'XXXXXXXXX'
然后，使用装饰器参数为每个小部件启用加密
@number_widget(encrypted=True)
def user_count(request):
return User.objects.count()
创建自定义小部件
可用的自定义小部件在Geckoboard支持部分有描述，在Geckoboard API下。从Django项目的角度来看，自定义小部件只是一个视图。django-geckoboard应用程序提供了用于渲染不同小部件正确响应的视图装饰器。
假设您想在仪表板上添加一个显示今天发布的评论数量的小部件。首先创建一个视图，使用django-geckoboard装饰器
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()
您还可以指定小部件的输出格式为JSON或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()
如果您的部件有可选设置，您可以在装饰器定义中传递它们
@number_widget(absolute='true')
def comment_count(request):
midnight = datetime.combine(date.today(), time.min)
return Comment.objects.filter(submit_date__gte=midnight).count()
然后使用URLconf模块将URL映射到视图
from django.conf.urls.defaults import *
urlpatterns = patterns('YOUR_VIEW_MODULE',
...
(r'^geckoboard/comment_count/$', 'comment_count'),
)
这是在仪表板上显示评论计数所需的全部Django代码。当您在Geckoboard中创建自定义小部件时，输入以下信息
- 加密
如果该字段已加密（参见上面说明），请启用。
- URL数据源
视图URL。在上面的示例中，这将是类似于http://HOSTNAME/geckoboard/comment_count/的内容。
- API密钥
如果设置了，请输入GECKOBOARD_API_KEY设置的内容。
- 小部件类型
自定义
- 数据源格式
可以是XML或JSON。如果没有指定格式，装饰器将自动检测并输出正确的格式，或者默认为XML（默认情况下，Geckoboard不再将格式作为参数附加）
- 请求类型
可以是GET或POST。视图装饰器接受两者。
以下装饰器来自django_geckoboard.decorators模块
number_widget
渲染数字 & 次级统计小部件。
装饰的视图必须返回一个元组(当前值, [前一个值], [前缀])，其中当前值参数是当前值，可选的前一个值参数是所测量的数量的前一个值，可选的前缀参数是在Geckoboard小部件中使用的。如果只有一个参数，您不需要将其放在元组中返回。例如，要渲染一个显示用户数量和与上周相比的差异的小部件
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
渲染RAG Column & Numbers或RAG Numbers小部件。
装饰的视图必须返回一个包含三个元组的元组(值, [文本])。值参数按顺序显示为红色、琥珀色和绿色。可选的文本参数将在仪表板中显示在相应值旁边。
例如，要渲染一个显示在过去24小时内由版主批准或删除的评论数量的小部件
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
渲染文本小部件。
装饰的视图必须返回一个包含元组的列表(消息, [类型])。消息参数是将在小部件中显示的字符串。可选的类型参数将告诉Geckoboard如何注释消息。使用TEXT_INFO用于信息性消息，TEXT_WARN用于警告，TEXT_NONE用于纯文本（默认）。如果只有一个纯文本消息，您可以不将其放在列表和元组中返回
例如，要渲染一个显示最新的Geckoboard Twitter更新的小部件，使用Mike Verdone的Twitter库
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
渲染饼图小部件。
装饰的视图必须返回一个元组序列(值, 标签, [颜色])。可选的颜色参数是一个表示红色、绿色、蓝色和可选透明度的字符串'RRGGBB[TT]'。
例如，要渲染一个显示普通用户、工作人员和超级用户的数量的小部件
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
渲染折线图小部件。
装饰过的视图必须返回一个元组(values, x_axis, y_axis, [color])。其中values参数是一个数据点列表。x轴参数是一个标签字符串或字符串列表，将放置在X轴上。y轴参数与Y轴的工作方式类似。如果有多个轴标签，它们将均匀地放置在轴上。可选的color参数是一个表示红色、绿色、蓝色和可选透明度的字符串'RRGGBB[TT]'。
例如，要渲染一个显示过去四周（包括今天）每天评论数量的小部件
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
渲染一个Geck-O-Meter小部件。
装饰过的视图必须返回一个元组(value, min, max)。其中value参数表示当前值。min和max参数分别表示最小值和最大值。它们可以是值，也可以是元组(value, text)。如果使用，则text参数将在最小值或最大值旁边显示。
例如，要渲染一个显示过去24小时内登录的用户数量的小部件
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
渲染一个Funnel小部件。
装饰过的视图必须返回一个至少包含items键的字典。要渲染一个显示认证用户与匿名用户分解的漏斗
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
渲染一个Bullet小部件。
装饰过的视图必须返回一个至少包含键label、axis_points、current和comparative的字典。要渲染Geckoboard的示例，请访问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,
}
变更日志
版本 2.0.0
添加对Python 3.4和4.5的支持，并放弃对Python < 2.7的支持；添加对Django 1.9的支持，并放弃对Django < 1.8的支持（Matt Terry）
版本 1.2.8
直接使用json包（Max Lynch）
版本 1.2.7
添加加密支持（Jeremy A. Johnson）
允许在控件装饰器中设置输出格式（Rob Hudson）
版本 1.2.6
允许数字控件返回字典列表（Arthur Furlan）
版本 1.2.5
添加对“prefix”参数的支持（Arthur Furlan）
版本 1.2.4
添加“Content-Type”头（Arthur Furlan）
版本 1.2.3
修复自动缩放代码中的KeyError错误（Ben Belchak）
版本 1.2.2
修复子弹图表上的比较条形图（Rod Begbie）
版本 1.2.1
修复Unicode处理（Éric St-Jean）
版本 1.2.0
添加bullet控件装饰器（Hedley Roos）
版本 1.1.0
添加funnel控件装饰器（Simon de Haan）
版本 1.0.0
从0.2.1版本没有变化
版本 0.2.1
修复API密钥检测
版本 0.2.0
重命名控件装饰器
版本 0.1.0
首次发布，从django-analytical中分离出来。
