16,602
edits
Changes
m
NOTE: to use make.py as shown throughout this document, you may have to use: GRAMPSPATH=/path/to/gramps python make.py ... if ==Follow the default ("../../..") is not correct.development API for your tool===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 Gramps development see [[Portal:Developers]] and [[Writing a Plugin]] specifically.
GRAMPS 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.
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 === Commit your addons with a name appropriate for Python imports.changes ===
<pre>
from TransUtils import get_addon_translator
_ = get_addon_translator().gettext
</pre>
NOTE: Currently we don't These have a method of using a context become obsolete in any of these functions. The translation functions that are supported are defined as followsGramps 4; gettext, ngettext, and sgettext always return translated strings in unicode for consistent portability between Python 2 and Python3. '''gettext(message)'''
If a fallback has been set, forward See the [http://docs.python.org/3/library/gettext() to .html#the fallback-gnutranslations-class python documentation] for documentation of gettext and ngettext. Otherwise, The "l" versions return the translated messagestring encoded according to the [http://docs.python.org/3/library/locale.html#locale. Overridden setlocale currently set locale]; the "u" versions return unicode strings in Python2 and are not available in derived classesPython 3.
== List and document your addon ==
Edit [[Plugins3.4]] 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".
→Miscellaneous commands
{{man warn|Warning:|This page documents the API, methods, and best practices for developing a 3rd-party addon for GRAMPS Gramps 3.2 / 3.3 / 3.4.and later }}
Addons for GRAMPS 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:
# List and document your addon
# Support it through issue tracker
# Maintain the code as GRAMPS Gramps continues to evolve
We'll now look at each of these steps in detail.
== Develop your addon ==
The [http://svn.code.sf.net/p/gramps-addons /code/ gramps-addons] subversion repository has the following structure:
* /gramps-addons
The contrib subdirectories hold the source code for the addons for a particular version. If you are working on a addon for gramps{{stable_branch}} then you should be working in gramps-addons/branches/gramps{{stable_branch}}/contrib. If you are working in gramps/trunk then you should use gramps-addons/trunk/contrib.
==== Setup the addon development tools====
These steps show how to download and work with the addon development tools.
{{man tip| 1=Tip |2=To use make.py as shown throughout this document, you may have to use:<br />
<pre>GRAMPSPATH=/path/to/gramps python make.py ...</pre> <br /> if the default ("../../..") is not correct.}}
# Checkout the gramps-addons files from the [https://sourceforge.net/projects/gramps-addons/ gramps-addons] project:
### cd ~/gramps/trunk
## Checkout gramps-addons:
### svn co httphttps://svn.code.sf.net/p/gramps-addons/code/trunk/ gramps-addons
## Change to trunk or branches/gramps{{stable_branch}} directory:
### cd gramps-addons/branches/gramps{{stable_branch}}/contrib
## ./make.py init NewProjectName
=== Test your addon as you develop ===To test your addon as you develop it it is suggested that you replace your GRAMPS Gramps user plugin directory with a link to your addon development directory, like so:
cd ~/.gramps/gramps{{stable_branch}}/
ln -s /wherever/trunk/gramps-addons/branches/gramps{{stable_branch}}/contrib plugins
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 by emailing one of the admins of the project (listed under the gramps-addon title next to the group icon) from httpshttp://sourceforge.net/projectprojects/gramps-addons/memberlist.php?group_id=285429
# 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
'''lgettext(message)sgettext''' If is a fallback has been setGramps extension that filters out clarifying comments for translators, 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 the fallback. Otherwise, return Where "rest" is 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 ===
NOTE: Running the '''make.py build''' will increment the third number in your dotted version number of all addons in the gpr.py file. Consider this number to be a "build number".
== List your addon in the Gramps Plugin Manager==''New for Gramps 3.4'': You need to then make your addon available in listings of various languages. '''Make sure you have already built gramps34 or trunk''' To do thatcreate a listing:
python make.py listing
cd ..
svn commit -m "Message describing changes"
== List and document your addon on the wiki==
Document the addon in the wiki using the name '''"Addon:NewProjectName"'''.
Edit [[Plugins3.4]] or [[Plugins4.0]] and describe your addon. You can point to the addon.tgz in SVN as the downloadable file.
== Miscellaneous commands ==
To build and compile translations for all projectsto their download/Addon.addon.tgz files:
python make.py build all
To compile translations for all projects to their download/Addon.addon.tgz files:
python make.py compile all
== 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]]
