Printed Reports

Overview

Printed report generation is arguably the most important thing that ChildCount+ does. To simplify the process, we have created a report generation “framework” of sorts that makes creating reports faster and easier (once you know how it all works).

One key principle of the framework to reduce the duplication of code by abstracting a lot of the common elements of report generation out of the individual report code. The framework treats each report as a function that takes as arguments:

  1. A time period (e.g., “12 Months (divided by Quarter)”)
  2. A file format (e.g., “pdf”)
  3. [Optional] A variant (e.g., “Bugongi Health Center”)

In the definition of the report, the report author only has to write a function that takes these three parameters and spits out a report with the desired properties. The report framework handles the user interface for generating reports and manages the storage as well. Look at the existing reports to see how this all is done.

How to Add Reports

  1. Create a report definition file and place it in apps/reportgen/definitions. Your best bet is to copy an existing report file and adjust it according to your needs.
  2. If your report is called NewReport.py, then add NewReport to the __all__ list in apps/reportgen/definitions/__init__.py.
  3. Open the Django admin interface (at http://your_server_ip/admin), and add an entry to the Reportgen.Report model. The entry should contain the name of your report class (e.g., NewReport) and a human-readable title for the report.
  4. Restart celeryd, rapidsms and celerybeat.

How to Debug Reports

Debugging reports can be annoying. The one way to simplify the process is this:

# Open shell
cd sms
./rapidsms shell

# Load a time period
from reportgen.timeperiods import Month
t = Month.periods()[2]

# Load your new report definition file
from reportgen.definitions.MyNewReport import ReportDefinition

# Test the report using the first variant
ReportDefinition.test(t, 'pdf')

# The generated report will end up in /tmp/test_my_new_report
# (or whatever the name of your report is)

# To re-run your report, you need to quit the shell
exit

Save this script in a file to speed up the process.

ccdoc - ChildCount+ Document-Generation Library

The ccdoc library adds another layer of abstraction to reports. Using ccdoc, you can generate an instance of a report as a ccdoc ccdoc.document.Document object and ccdoc will handle generation of the report output in HTML, PDF, and XLS file formats. Many of the reports in apps/reportgen/definitions use ccdoc to simplify the report generation process and those are good places to look for real-world examples of ccdoc in action.

The file lib/ccdoc/example.py contains an example of how to create and render a Document into HTML. Run the example from your rapidsms shell (when you’re in your site directory) like this:

cd ~/your-site
./rapidsms shell < lib/ccdoc/example.py > test.html
# Ignore the >>> prompts that the python shell adds

How It Works

The user creates a ccdoc.document.Document object, which is pretty much a collection of ccdoc.section.Section, ccdoc.paragraph.Paragraph, and ccdoc.table.Table objects. The user then passes the Document to an object that inherits from ccdoc.generator.Generator (for example, ccdoc.html.HTMLGenerator). The Generator object prints the formatted report to a file – you can either ask for the name of the file where the report has been printed or you can get the contents of the file back as a string.

You can create new Generator objects that inherit from Generator. If you do, make sure to look in lib/ccdoc/generator.py at the bottom and to implement _*_document() and the _render_*() methods in your subclass.

See the ccdoc page for API information.