Jump to: navigation, search

Report-writing tutorial

No change in size, 04:43, 1 February 2013
This tutorial covers the basics of writing a simple report using the GRAMPS Gramps report infrastructure. It covers the process of handling options, building a document and creating the report.
The goals of this report are to create a database summary report. It will include the following information in the report:
;Report class : This is the code that takes data from the GRAMPS Gramps database and organizes it into the document structure. This structure can later be printed, viewed, or written into a file in a variety of formats. This class uses the [ docgen] interface to abstract away the output format details.
;Options class : This is the code that provides means to obtain options necessary for the report using a variety of available mechanisms.
;Registration statement : This initializes the report by a single call to the <tt>register()</tt> function. It is trivial, but without it your report will not become available to GRAMPSGramps, even if it is otherwise perfectly written.
A report can potentially be generated as a standalone report, as a GRAMPS Gramps Book item, and as a command line report. The registration determines which modes are enabled for a given report. The report class does not have to know anything about the mode. The options class is there to provide options interface for all available modes.
==Document interface==
GRAMPS Gramps attempts to abstract the output document format away from the report. By coding to the [ docgen] class, the report can generate its output in the format desired by the end user. The document passed to the report (<tt>self.doc</tt>) could represent an HTML, OpenDocument, PDF or any of the other formats supported by the user. The report does not have to concern itself with the output format details, since all details are handled by the document object.
A document is composed of paragraphs, tables, and graphics objects. Tables and graphics objects will not be covered in this tutorial.
===Report class===
The user's report class should inherit from the Report class contained within the Report module. The constructor should take three arguments (besides class instance itself, usually denoted by 'self' name):
* GRAMPS Gramps database instance
* options class instance
* user class instance
* It should also enable the "semi-common" options that are used in this report, by overriding the <tt>enable_options</tt> method which defines <tt>enable_dict</tt> dictionary. The semi-commons are the options which GRAMPS Gramps knows about, but which are not necessarily present in all reports:
def enable_options(self):
All the common options are already taken care of by the core of GRAMPSGramps.
* For any new options set up in the options class, there must be defined UI widgets to provide means of changing these options through the dialogs. Also, there must be defined methods to extract values of these options from the widgets and to set them into the class-variable dictionary:
There are arguments for the report class and options class. The <tt>report_modes</tt> argument is set to a list of zero or more of the following modes:
* REPORT_MODE_GUI (available for GRAMPS Gramps running in a window, graphical user interface)
* REPORT_MODE_BKI (available as a book report item)
* REPORT_MODE_CLI (available for the command line interface)

Navigation menu