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:
- A time period (e.g., “12 Months (divided by Quarter)”)
- A file format (e.g., “pdf”)
- [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¶
- 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.
- If your report is called
NewReport.py, then add
- 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
NewReport) and a human-readable title for the report.
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() # 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
Many of the reports in
use ccdoc to simplify the report generation process and those
are good places to look for real-world examples of ccdoc in
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
which is pretty much a
ccdoc.table.Table objects. The
user then passes the
Document to an object that inherits from
ccdoc.generator.Generator (for example,
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
the bottom and to implement
_*_document() and the
methods in your subclass.
See the ccdoc page for API information.