Difference between revisions of "Addons development"

From Gramps
Jump to: navigation, search
(Create a Gramps Plugin Registration file)
(Addon Development)
Line 3: Line 3:
 
= Addon Development =
 
= Addon Development =
  
Addon's for GRAMPS can extend the program in many different ways. 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 it are:
+
Addon's for GRAMPS can extend the program in many different ways. You can add any of the following types of addons:
 +
 
 +
# Doc creator
 +
# Exporter
 +
# Gramplet
 +
# Importer
 +
# Map service
 +
# Plugin lib
 +
# Quickreport
 +
# Relationships
 +
# Report
 +
# Tool
 +
# View
 +
 
 +
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:
  
 
# Develop your addon
 
# Develop your addon
Line 29: Line 43:
 
## ./make.py init NewProjectName
 
## ./make.py init NewProjectName
  
Follow the development API for your tool, report, view, or [[Gramplets]]. Place all of your associated .py, .glade, etc. files in this directory.  
+
Follow the development API for your tool, [[Report-writing_tutorial|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.
  
 
To test your addon as you develop it it is suggested that you add a link to your addon development directory from your GRAMPS user plugin directory, like so:
 
To test your addon as you develop it it is suggested that you add a link to your addon development directory from your GRAMPS user plugin directory, like so:

Revision as of 12:59, 2 November 2009

This page documents the API, methods, and best practices for developing an 3rd-party addon for GRAMPS 3.2, due March 2010.

Addon Development

Addon's for GRAMPS can extend the program in many different ways. You can add any of the following types of addons:

  1. Doc creator
  2. Exporter
  3. Gramplet
  4. Importer
  5. Map service
  6. Plugin lib
  7. Quickreport
  8. Relationships
  9. Report
  10. Tool
  11. View

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:

  1. Develop your addon
  2. Create a Gramps Plugin Registration file (.gpr.py)
  3. Get translators to translate your addon into multiple languages
  4. Package your addon
  5. List and document your addon
  6. Support it through issue tracker
  7. Maintain the code as GRAMPS continues to evolve

We'll now look at each of these steps in detail.

Develop your addon

These steps show how to download and work with the addon development tools.

  1. Checkout the gramps-addons files from the gramps-addons project:
    1. cd to the same director that gramps trunk is in
    2. svn co https://gramps-addons.svn.sourceforge.net/svnroot/gramps-addons gramps-addons
    3. cd gramps-addons
  2. Make a new project directory in gramps-addon/contrib:
    1. cd contrib
    2. mkdir NewProjectName
  3. Initialize the addon:
    1. ./make.py init NewProjectName

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.

To test your addon as you develop it it is suggested that you add a link to your addon development directory from your GRAMPS user plugin directory, like so:

cd ~/.gramps/plugins/
link -s /home/username/gramps/gramps-addons/contrib development

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

FIXME: how do you share files between addons?

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

  1. Get an http://sourceforge.net account if you don't already have one.
  2. Request SVN write access for the gramps-addon project from https://sourceforge.net/project/memberlist.php?group_id=285429
  3. Remove the files that should not be added to SVN:
    1. ./make.py clean NewProjectName
  4. Add the project to the repository:
    1. svn add NewProjectName
    2. svn commit -m "A message describing what this addon is"

Before making additional edits to your addon, you should:

  1. svn update
  2. svn status
  3. svn commit -m "A message describing the changes"

Create a Gramps Plugin Registration file

Create the NewProjectName.gpr.py file as follows.

For any addon which you have the translations for, you will need to add a way to retrieve the translation. You need to add this to the top of the .gpr.py file:

from TransUtils import get_addon_translator
_ = get_addon_translator(__file__).gettext

Following that, you then to describe the addon. Here is a sample Gramplet GPR file:

register(TOOL, 
         id    = 'AttachSource',
         name  = _("Attach Source"),
         description =  _("Attaches a shared source to multiple objects."),
         version = '0.0.0',
         status = UNSTABLE,
         fname = 'AttachSourceTool.py',
         authors = ["Douglas S. Blank"],
         authors_email = ["[email protected]"],
         category = TOOL_DBPROC,
         toolclass = 'AttachSourceWindow',
         optionclass = 'AttachSourceOptions',
         tool_modes = [TOOL_MODE_GUI]
         )

You can see examples of the kinds of addons here.

Get translators to translate your addon into multiple languages

  1. Initialize and update the template.pot for your addon:
    1. ./make.py init NewProjectName
  2. Initialize a language for your addon (say French, fr):
    1. ./make.py init NewProjectName fr
  3. Update it from gramps and other addons:
    1. ./make.py update NewProjectName fr
  4. Edit contrib/NewProjectName/po/fr-local.po
  5. Compile the language:
    1. ./make.py compile NewProjectName fr
  6. Add or update your local language file, and commit changes:
    1. svn add NewProjectName/po/fr-local.po
    2. svn commit NewProjectName/po/fr-local.po -m "Added fr po file"

Package your addon

./make.py build NewProjectName 

List and document your addon

Edit 3.2 Third-party Plugins and describe your addon.

Support it through issue tracker

Maintain the code as GRAMPS continues to evolve

Resources