# Writing Extentions for gramps

Copyright © 2001 by Donald N. Allingham

# Introduction

`gramps` was intended from the start to allow the user to extend it through a plugin system. Five types of plugins are supported - filters, reports, tools, import filters, and export filters. In a way, an export filter can be viewed as a special type of report, and an import filter can be viewed as a special type of tool.

All plugins are written in the `python` language.

## Filters

A filter is a plugin that be used to temporarily display or hide individuals in the People View. The filter is the simplest form of plugin, which only needs to determine if a person meets or fails to meet its criteria. It operates on a single person at a time.

Filters should never alter a database.

## Reports

A report is a plugin that generates output. The output may be in either a interactive, graphical form, or as an output file. Report plugins are passed a reference to the internal database and a reference to the active person, which allows the plugn to operate on a single person, the entire database, or anything in between.

Plugins that conform to the reportplugin interface appear in the + + + + + + + + + +Reports+ + + + + + + + + menu and in the Report Selection dialog box.

A report should never alter the database.

## Tools

A tool is a plugin that alters the database. It may perform something as small changing the case of some text to something as complex as merging redundant individuals. Tools plugins are passed a reference to the internal database, the active person, and a callback function. The callback function is used to notify the main program if it needs to update the display with any modified information.

Plugins that conform to the tool plugin interface appear in the + + + + + + + + + +Tools+ + + + + + + + + menu and in the Tool Selection dialog box.

A tool is allowed (and usually expected) to alter the database.

## Import Filters

An import filter is a plugin that adds information from another source to the database. It is similar to a tool, but is called differently to allow gramps to distinguish it from a tool.

Plugins that conform to the import filter calling syntax appear in the + + + + + + + + + +File+ + + + + + + + + + + ->Import+ + + + + + + + + menu.

An import filter is allowed to modify the database.

## Export Filters

An export filter is a plugin that translates the gramps database into the format expected by another program. Since it generates an output file, it is similar to a report generator. However, its calling syntax is different, so that gramps knows how to distiguish it from a report generator.

Plugins that conform to the export filter calling syntax appear in the + + + + + + + + + +File+ + + + + + + + + + + ->Export+ + + + + + + + + menu.

An export filter should not alter the database.

|  | Next >>>
|  | Writing Filters