# Request SVN write access for the gramps-addon project by emailing one of the admins of the project (listed under the gramps-addon title next to the group icon) from http://sourceforge.net/projects/gramps-addons/

# Remove the files that should not be added to SVN:

# Remove the files that should not be added to SVN:

## ./make.py clean NewProjectName

## ./make.py clean NewProjectName

Revision as of 15:26, 3 February 2013

Warning:

This page documents the API, methods, and best practices for developing a 3rd-party addon for Gramps 3.2 and later

Addons for Gramps can extend the program in many different ways. You can add any of the following types of addons:

Report

Quickreport

Tool

Importer

Exporter

Doc creator

Plugin lib

Map service

Gramps View

Relationships

Gramplet

Sidebar

Writing an addon is fairly straightforward if you have just a little bit of Python experience. And sharing your addon is the right thing to do. The general steps to writing an addon and sharing your own addons are:

Follow the development API for your tool

Follow the development API for your tool, report, view, or Gramplets. Place all of your associated .py, .glade, etc. files in this directory. For general information on Gramps development see Portal:Developers and Writing a Plugin specifically.

Test your addon as you develop

To test your addon as you develop it it is suggested that you replace your Gramps user plugin directory with a link to your addon development directory, like so:

cd ~/.gramps/gramps4.1

/

mv plugins/* /wherever/trunk/gramps-addons/branches/gramps4.1

/contrib/

rm -rf plugins
ln -s /wherever/trunk/gramps-addons/branches/gramps4.1

/contrib plugins

Gramps will search this folder (and subdirectories) for .grp.py files, and add them to the plugin list.

If you have code that you want to share between addons, you don't need to do anything special. Currently, Gramps adds each directory in which a .gpr.py is found onto the PYTHONPATH which is searched when you perform an import. Thus "import NewProjectName" will work from another addon. You should always make sure you name your addons with a name appropriate for Python imports.

Commit your changes

To commit your changes so that others can use your addon, follow these steps:

Localization

For general help on translations in Gramps, see Coding for translation. However, that will only use translations that come with Gramps, or allows you to contribute translations to the Gramps core. To have your own managed translations that will be packaged with your addon, read the rest of this page.

For any addon which you have translations into other languages, you will need to add a way to retrieve the translation. You need to add this to the top of your NewProjectName.py file:

For Gramps 4:

Then you can use the standard "_()" function to translate phrases in your addon.

You can use one of a few different types of translation functions:

gettext

lgettext

ngettext

lngettext

sgettext

Gramps 3 also provides:

ugettext

ungettext

These have become obsolete in Gramps 4; gettext, ngettext, and sgettext always return translated strings in unicode for consistent portability between Python 2 and Python3.

See the python documentation for documentation of gettext and ngettext. The "l" versions return the string encoded according to the currently set locale; the "u" versions return unicode strings in Python2 and are not available in Python 3.

sgettext is a Gramps extension that filters out clarifying comments for translators, such as

_("Remaining names | rest")

Where "rest" is the English string that we want to present and "Remaining names" is a hint for translators.

Create a Gramps Plugin Registration file

First, create the NewProjectName.gpr.py file. The registration takes this general form:

ATTR depends on the PTYPE. But you must have gramps_target_version and version. gramps_target_version should be a string of the form "X.Y" version number matching Gramps X major, Y minor integer. version is a string of the form "X.Y.Z" representing the version of your addon. X, Y, and Z should all be integers.

Note that this .gpr.py will automatically use translations if you have them (see below). That is, the function "_" is predefined to use your locale translations; you only need to mark the text with _("TEXT") and include a translation of "TEXT" in your translation file. For example, in the above example, _("Attach Source") is marked for translation. If you have developed and packaged your addon with translation support, then that phrase will be converted into the user's language.

Each report category has a set of standards and interface. The categories CATEGORY_TEXT and CATEGORY_DRAW use the Document interface of Gramps. See also Report API for a draft view on this.
The application programming interface or API for reports is treated at Report-writing_tutorial. For general information on Gramps development see Portal:Developers and Writing a plugin specifically.

General plugins

The plugin framework also allows you to create generic plugins for use. This includes the ability to create libraries of functions, and plugins of your own design.

Example: A library of functions

In this example, a file name library.py will be imported at time of registration (when Gramps starts):

The code in the file library.py will be imported when Gramps begins. You can access the loaded module in other code by issuing an "import library" as Python keeps track of files already imported. However, the amount of useful code that you can run when the program is imported is limited. You might like to have the code do something that requires a dbstate or uistate object, and neither of these is available when just importing a file.

If "load_on_reg" was not True, then this code would be unavailable until manually loaded. There is no automatic mechanism in Gramps to load GENERAL plugins automatically.

In addition to importing a file at startup, one can also run a single function inside a GENERAL plugin, and it will be passed the dbstate, the uistate, and the plugin data. The function must be called "load_on_reg", and take those three parameters, like this:

GENERAL plugins can have a function (called "process") which will process the data

If you (or someone else) create additional general plugins of this category, and they follow your load_on_reg data format API, then they could be used just like your original data. For example, here is an additional general plugin in the 'WEBSTUFF' category: