1,583
edits
Changes
→Resources
{{man warn|Warning:|This page documents the API, methods, and best practices for developing a 3rd-party addon for Gramps 3.2 / 3.3 / 3.4.and later }}
Addons for Gramps can extend the program in many different ways. You can add any of the following [http://svn.code.sf.net/p/gramps/code/trunk/gramps/gen/plug/_pluginreg.py types ] of addons:
# Doc creatorReport# ExporterQuickreport# GrampletTool# Importer# Map serviceExporter#Doc creator# Plugin lib# QuickreportMap service# RelationshipsGramps View# ReportRelationships# ToolGramplet# ViewSidebar
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 ==
The [http://svn.code.sf.net/p/gramps-addons /code/ gramps-addons] subversion repository has the following structure:
* /gramps-addons
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:
# Get an http://sourceforge.net account if you don't already have one.
# Request SVN write access for the gramps-addon project from https://sourceforge.net/project/memberlist.php?group_id=285429[http://sourceforge.net/p/allura/tickets/5481/]
# Remove the files that should not be added to SVN:
## ./make.py clean NewProjectName
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 3: ====
from TransUtils import get_addon_translator
_ = get_addon_translator(__file__).gettext
==== For Gramps 4: ====
from gramps.gen.const import GRAMPS_LOCALE as glocale
_ = glocale.get_addon_translator(__file__).gettext
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
# ngettextsgettext Gramps 3 also provides:
# ugettext
# ungettext
See the [http://docs.python.org/3/library/gettext.html#the-gnutranslations-class python documentation] for documentation of gettext and ngettext. The translation functions that "l" versions return the string encoded according to the [http://docs.python.org/3/library/locale.html#locale.setlocale currently set locale]; the "u" versions return unicode strings in Python2 and are supported are defined as followsnot available in Python 3.
'''gettext(message)sgettext''' If is a fallback has been setGramps extension that filters out clarifying comments for translators, forward gettext() to the fallback. Otherwise, return the translated message. Overridden in derived classes. '''lgettext(message)''' If a fallback has been set, forward lgettext() to the fallback. Otherwise, return the translated message. Overridden in derived classes.such as'''ugettext _(message"Remaining names | rest")''' If a fallback has been set, forward ugettext() to Where "rest" is the fallback. Otherwise, return the translated message as a Unicode English string. Overridden in derived classes. '''ngettext(singular, plural, n)''' If a fallback has been set, forward ngettext() that we want to the fallback. Otherwise, return the translated message. Overridden in derived classes. '''lngettext(singular, plural, n)''' If present and "Remaining names" is a fallback has been set, forward ngettext() to the fallback. Otherwise, return the translated message. Overridden in derived classes. '''ungettext(singular, plural, n)''' If a fallback has been set, forward ungettext() to the fallback. Otherwise, return the translated message as a Unicode string. Overridden in derived classeshint for translators.
== Create a Gramps Plugin Registration file ==
</pre>
PTYPE is TOOL, GRAMPLET, REPORT, QUICKREPORTQUICKVIEW, IMPORT, EXPORT, DOCGEN, GENERAL, MAPSERVICE, VIEW, or RELCALC.
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.
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 Gramps development see [[Portal:Developers]] and [[Writing a plugin]] specifically.
=== General plugins ===
== List and document your addon ==
Edit [[Plugins3.4]] or [[Plugins4.0]] and describe your addon. You can point to the addon.tgz in SVN as the downloadable file. Document the addon in the wiki using the name '''"Addon:NewProjectName"'''.
== Support it through issue tracker ==
Visit http://www.gramps-project.org/bugs/view_all_bug_page.php and become a user. Suggest to check it regularly.
== Maintain the code as GRAMPS Gramps continues to evolve ==
= Resources =
* httphttps://gramps-addons.svn.sourceforge.net/viewvcp/gramps-addons/ - SVN browseGramps Addons site
[[Category:Developers/General]]
