Writing Reports

Users can create their own report generators and add them to gramps. By adding the report generator to the user's private plugin directory (~/.gramps/plugins), the report generator will be automatically recognized the next time that the program is started.

Creating a report generator

Fewer restrictions are made on report generators than on filters. The report generator is passed the current gramps database and the active person. The generator needs to take special care to make sure that it does not alter the database in anyway.

A report generator is a function that takes two arguments — a database (of type RelDataBase) and the currently selected person (of type Person). When called, this task should generate the desired report.

This function's implementation can be as simple as generating output without the user's intervention, or it could display a graphical interface to allow the user to select options and customize a report.

As with filters, the report generator must be registered before gramps will understand it. The report generator is registered using the Plugins.register_report. This function takes five arguments.

While only the task and report name are required, it is recommended to provide all five parameters.


import Plugins

def report(database,person):
   ... actual code ...

Plugins.register_report(
    task=report,
    category="Category",
    name="Report Name",
    description="A text descripition of the report generator",
    xpm="%s/myfile.xpm" % os.path.dirname(__file__)
)
        

Figure 2. Sample report implementation

A little help - Format Interfaces

gramps provides some help with writing reports. Several generic python classes exist that aid in the writing of report generators. These classes provide an abstract interface for a type of document, such as a drawing, word processor document, or a spreadsheet. From these core classes, gramps derives interfaces to various document formats. This means that by coding to the generic word processing class (TextDoc), a report generator can instant access to multiple file formats (such as HTML, OpenOffice, and AbiWord).

This scheme of deriving a output format from a generic base class also makes it easier to add new formats. Creating a new derivied class targeting a different format (such as KWord or LaTeX) makes it easy for existing report generators to use the new formats.