Getting Started

Overview

This library deals with the following concepts:

Report

A class that maintains a collection of charts

Chart

A class that, given a set of options and a set of data, generates HTML to display that data in a nice format. Charts can include graphs, tables, and other arbitrary visualization types.

ChartData

A class that allows the collection of data in a structured format, which can then be passed into a Chart.

ChartRenderer

A class that implements the rendering of Chart objects. Changing the ChartRenderer class for a Report or Chart allows for easy changing of rendering technologies - i.e. google charts, FusionCharts, HighCharts etc.

ReportView

A class-based view to assist with the creation of a report API. More information in the API documentation.

Report objects

Consider the following, very simple report - this would usually be located in a reports.py file in your app directory:

# myapp/reports.py

from report_tools.reports import Report
from report_tools.chart_data import ChartData
from report_tools.renderers.googlecharts import GoogleChartsRenderer
from report_tools import charts


class MyReport(Report):
    renderer = GoogleChartsRenderer

    pie_chart = charts.PieChart(
        title="A nice, simple pie chart",
        width=400,
        height=300
    )

    def get_data_for_pie_chart(self):
        data = ChartData()

        data.add_column("Pony Type")
        data.add_column("Population")

        data.add_row(["Blue", 20])
        data.add_row(["Pink", 20])
        data.add_row(["Magical", 1])

        return data

A Report is composed of Chart objects. In this case, the report has a single chart pie_chart. This chart has been given a title, width and height, but other than that it will use the default rendering options.

For information on the available Chart classes, see the Chart documentation.

Rendering for this report will be performed by the GoogleChartsRenderer class, which uses Google’s visualization framework. For more information on the available rendering classes, see the renderer documentation.

All charts on a report require a get_data_for_xxx method, where xxx is the attribute name given to the chart. In this case, you can see the get_data_for_pie_chart field has been created. Pie charts require a ChartData object as input, so the get_data_for_pie_chart method creates one, fills it with data and returns it. For detailed information on how to enter data into a ChartData object or other data storage formats, see the ChartData documentation.

Using a report in your views

Using a report in your view is simple:

# myapp/views.py

from django.shortcuts import render
from myapp.reports import MyReport


def my_report(request):
    # Initialise the report
    template = "myapp/my_report.html"
    report = MyReport()
    context = {'report': report}

    return render(request, template, context)

You can also use the included class based view, which will help if you wish to use API features down the track:

# myapp/views.py

from django.shortcuts import render
from myapp.reports import MyReport
from report_tools.views import ReportView


class MyReportView(ReportView):
    def get_report(self, request):
        return MyReport()
        
    def get(self, request):
        template = 'myapp/my_report.html'
        context = {
            'report': self.get_report(request),
        }
        
        return render(request, template, context)

Note the use of the get_report method. This provides the hook required for the API to grab the report. For more information, check the API documentation.

Using a report in your templates

Using a report in your template is also straightforward

<!-- templates/myapp/my_report.html -->

<h1 class="chart-header">{{ report.pie_chart.title }}</h1>

<div class="chart-container">
	{{ report.pie_chart }}
</div>