Writing Extentions for gramps
<<< Previous |  | Next >>>

# 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.

- `The report generation task` This task that generates the report.

- `The report category` The category in which the report is grouped in the Reports menu and in the Report Selection dialog.

- `The report name` The name of the report.

- `A text description of the report` The description appears in the report selection tool to provide the user with a description of what the tools does.

- `A graphic logo in XPM format` This may be either a path to a filename, or a list of strings containting the XPM data. If a filename is specified, care must be taken to make sure the file location is relocatable and can be determined at runtime.

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.

<<< Previous | Home | Next >>>
Writing Filters |  | Writing Tools