4,216
edits
Changes
→Get a local copy of Gramps and its addons
{{out of dateman tip|Information on developing Gramps addons|If you are looking for addons to install, visit: [[Third-party Addons]]}}{{man warn|Warning:Note that this article anticipates that most addons will be developed under Linux.|([[Getting started with Gramps development|This page documents Linux is the API, methodsprincipal development platform.]]) While it is possible to do so under Windows or MacOS, some of the steps will differ and best practices for the documented processes have not been as thoroughly reviewed. So developer beware.<br>See [[Portal:Developers]]}}If you are developing a [[Third-party Addons|Third-party Addon]] ; this page documents the API, methods, and best practices for Gramps 34.2 and later }}.
==What can addons extend?==
Addons for Gramps can extend the program in many different ways. You can add any of the following [https://github.com/gramps-project/gramps/blob/master/gramps/gen/plug/_pluginreg.py types] of addons:
==Writing an addon==
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]]# [[#Create_a_Gramps_Plugin_Registration_file|Create a Gramps Plugin Registration file (.gpr.py)]]# Get translators to translate [[#internationalization|Invite translation of your addon ]] into multiple natural languages# [[#Package_your_addon|Package your addon]]# List [[#List_and_document_your_addon_on_the_wiki|Document your addon]] and document publish it to the addon list# [[#List_your_addon_in_the_Gramps_Plugin_Manager|Register your addonwith the Plugin Manager]]# [[#Announce_the_addon|Announce it on the Gramps Forum]] - Let users know it exist and how to use it.# [[#Support_it_through_issue_tracker|Support it through the issue tracker]]# [[#Maintain_the_code_as_Gramps_continues_to_evolve|Maintain the code ]] as Gramps continues to evolve
We'll now look at expand upon each of these steps in detailindividually.
== Develop your addon ==
Example commands are shown below referring to the public release rather than the master branch. The developers are currently merging changes to the most recent maintenance branch into master as necessary, so you don't have to do anything for that unless you are in a hurry. The [http://github.com/gramps-project/addons-source addons-source] git repository has the following structure, with the code for each addon in its own folder:
* /addons-source
** ...
The [http://github.com/gramps-project/addons addons] git repository holds built versions of the addons for each release of Gramps, and has the following structure:
* /addons
** [https://github.com/gramps-project/addons/tree/master/gramps42 /gramps42]
*** /download
*** /listings
** [https://github.com/gramps-project/addons/tree/master/gramps50 /gramps50]*** /download*** /listings** [https://github.com/gramps-project/addons/tree/master/gramps51 /gramps51]*** /download*** /listings** [https://github.com/gramps-project/addons/tree/master/gramps52 /gramps52]
*** /download
*** /listings
=== Test your addon as you develop Other prerequisites ===To test {{man warn|These instructions, the make.py script etc.|are designed to operate in a Linux environment. {{man menu|They won't work on Windows without modifications.}}}}* Gramps uses Python version 3.2 or higher. You must have at least that version installed. If you have installed Gramps 4.2 or higher on your addon as Linux system already, then a sufficient version of Python will be present. If you have more than one version of Python installed, then you develop it it must use the correct version for these scripts. On some systems, both Python 2.x and 3.x are installed. It is suggested possible that you the normal invocation of <code>python</code> starts up Python 2.x, and that to start up Python 3.x requires invoking with <code>python3</code> or <code>python3.4</code> etc. You can test the version by <code>python –version</code> or <code>python3 –version</code>. If this is so, replace your Gramps user plugin directory any usage of 'python' in the examples below with a link the appropriate invocation.* The make.py used in construction of the addons requires that the LANGUAGE environment variable be set to 'en_US.UTF-8'. * The make.py used in construction of the addons requires that the GRAMPSPATH environment variable be set to your addon development directory, like sopath to the Gramps source tree.* intltool must be installed;:<code>sudo apt-get install intltool</code>
====Gramps 4.2 and later=Test your addon as you develop ===For Gramps 4.2 and later follow these steps:# Get an https://github.com/join account if you don't already have one.# Request GIT write access for the https://github.com/gramps-project/addons-source project by emailing the [[Contact#Mailing_lists|gramps-devel mailing list]]See also [[Brief_introduction_to_Git|git introduction]].
Also you may want to [[Addons_development#Package_your_addon |Package your addon]] so it can be downloaded via the plugin manager.
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.
Note that these instructions will only work for Python strings, if you have a glade file, it will not get translated.
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:
from gramps.gen.const import GRAMPS_LOCALE as glocale
# lngettext
# sgettext
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.
_("Remaining names | rest")
Where "rest" is the English string that we want to present and "Remaining names" is a hint for translators.
==== Commands to compile translations ====
To build and compile translations for all projects to their download/Addon.addon.tgz files:
: <code>python3 make.py gramps52 build all</code>
To compile translations for all projects :
: <code>python3 make.py gramps52 compile all</code>
== Create a Gramps Plugin Registration file ==
<pre>
register(PTYPE,
gramps_target_version = "35.42",
version = "1.0.0",
ATTR = value,
</pre>
[httphttps://sourceforgegithub.netcom/pgramps-project/gramps/source/ciblob/master/tree/gramps/gen/plug/_pluginreg.py#l78 L76 PTYPE] is TOOL, GRAMPLET, REPORT, QUICKVIEW, 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.
Here is a sample Tool GPR file:
description = _("Attaches a shared source to multiple objects."),
version = '1.0.0',
gramps_target_version = '35.42',
status = STABLE,
fname = 'AttachSourceTool.py',
</pre>
You can see examples of the kinds of addons [httphttps://sourceforgegithub.net/pcom/gramps/source/ci/master/tree-project/gramps/plugins/ here] (for example, see [httphttps://sourceforgegithub.net/pcom/gramps/source/ci/master/tree-project/gramps/plugins/drawreport/drawplugins.gpr.py gramps/source/ci/master/tree/gramps/plugins/drawreport/drawplugins.gpr.py]) and see the full documentation in the [httphttps://sourceforgegithub.netcom/gramps-project/gramps/blob/p3f0db9303f29811b43325c30149c8844c7ce24b6/gramps/sourcegen/ciplug/_pluginreg.py#L23 master/tree/gramps/gen/plug/_pluginreg.py here] in the comments and docstrings.
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.
=== Report plugins ===
The possible report categories are ([https://github.com/gramps-project/gramps/blob/892fc270592095192947097d22a72834d5c70447/gramps/gen/plug/_pluginreg.py#L141-L149 gen/plug/_pluginreg.py]):
<pre>
#possible report categories
CATEGORY_BOOK = 4
CATEGORY_GRAPHVIZ = 5
CATEGORY_TREE = 6
REPORT_CAT = [ CATEGORY_TEXT, CATEGORY_DRAW, CATEGORY_CODE,
CATEGORY_WEB, CATEGORY_BOOK, CATEGORY_GRAPHVIZ, CATEGORY_TREE]
</pre>
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|Writing a Plugin]] specifically.
=== General plugins ===
description = _("Provides a library for doing something."),
version = '1.0',
gramps_target_version = '35.42',
status = STABLE,
fname = 'library.py',
Runs when plugin is registered.
"""
print ("Hello World!")
</pre>
category = "WEBSTUFF",
version = '1.0',
gramps_target_version = '35.42',
data = ["a", "b", "c"],
)
description = _("Provides a collection of stylesheets for the web"),
version = '1.0',
gramps_target_version = '35.42',
fname = "stylesheet.py",
load_on_reg = True,
def filters(namespace):
print ("Ok...", plugin.category, namespace, uistate)
# return a Filter object here
return filters
</pre>
<span id=internationalization>
== List the Prerequistes your addon depends on ==
''In your gpr file, you can have a line like:
<code>depends_on = ["libwebconnect"]</code>
which is a list of id's from other gpr files. This example will ensure that [[Addon:Web_Connect_Pack#Prerequisites|libwebconnect]] is loaded before your addon. If it can't be found, or you have a cycle, then your addons won't be loaded.
example code used in the Addon:Web_Connect_Pack that references libwebconnect Prerequistes [https://github.com/gramps-project/addons-source/blob/1304b65a7d758bfe17339c26260473ac3e9c4061/RUWebConnectPack/RUWebPack.gpr.py#L17 RUWebPack.gpr.py#L17 ]
This means that common Prerequistes can be shared between addons and that code sits in its own gpr/addon file.
<!--
[] for addon prerequistes have a look at converting them to use "depends_on = " like in the following addons
https://github.com/gramps-project/addons-source/search?utf8=%E2%9C%93&q=depends_on&type=
https://github.com/gramps-project/gramps/search?utf8=%E2%9C%93&q=depends_on&type=
which can be a comma separated list for multiple dependencies/prerequisites (so that addons that share prerequisites import the same library?) (maybe move spell check into an addon etc? tip of the day... possibilities...)
depends_on = ["libwebconnect"]
mentioned in the following
https://sourceforge.net/p/gramps/mailman/message/27070037/
''In your gpr file, you can have a line like:
depends_on = ["libwebconnect"]
which is a list of id's from other gpr files. This example will ensure
that libwebconnect is loaded before your plugin. If it can't be found,
or you have a cycle, then your plugin won't be loaded.
If it is a common function, perhaps libhtml is the right place to put
it, and you can put a depends_on on that.
-Doug''
example output is on terminal only:
Cannot resolve the following plugin dependencies:
Plugin 'UK Web Connect Pack' requires: ['libwebconnect']
[](feature) For plugins/addons if prerequisites not available display a page stating why/what is missing that includes the addon description and a url to the support page.
[] Gramps CLI info "gramps -v" needs a section that list third-party addons with version numbers and if prerequisites have been met.
[]update the Addon:Prerequisites Checker Gramplet to test for your Prerequisites.
-->
== Get translators to translate your addon into multiple languages ==
</span>If you [[#Localization|designed for localization]], the addon will begin supporting a single language. Make your addon inviting for volunteers to translate it into their native language.* Initialize and update the <code>template.pot </code> for your addon:** : <code>cd ~/addons-source</code>: <precode>./make.py gramps52 init NewProjectName</precode>* You should edit the header of <code>template.pot</code>with your information, so it gets copied to individual language files.
* Initialize a language for your addon (say French, fr):
* Update it from gramps and other addons:
* Compile the language:
* Add or update your local language file, and commit changes:
== Package your addon ==
To create a downloadable package:
: <code>./make.py gramps52 build NewProjectName</code> python or: <code>./make.py gramps53 build NewProjectName</code> for the master branch.
This will automatically include the following files in your build:
</pre>
{{man note|Note:|Running the command '''<code>make.py xxx build''' </code> will increment the third number in your dotted version number of all addons in the <code>*.gpr.py </code> file. Consider this number to be a "build number".}}
Then add the package to GitHub: <pre> cd '~/addons' svn git add ..gramps52/download/NewProjectName.addon.tgz git commit -m "Added new plugin: NewProjectName"</pre>or (for the master branch);<pre> cd '~/addons' git add gramps53/download/NewProjectName.addon.tgz svn git commit -m "Message describing changesAdded new plugin: NewProjectName"</pre>
== List your addon in the Gramps Plugin Manager==
{{man warn|Gramps needs to have been built|Make sure you have already built gramps34 or gramps41 gramps52 or master. Change to the appropriate git branch in your gramps directory, and run <code>python3 setup.py build</code> See [[Linux:Build_from_source]]}}
To create a listing:
That will create a series of files in the <tt>../listings/</tt> directory.
Then add the updated listing to SVNGitHub:
<pre> cd '~/addons' svn git add ..gramps52/listings/* git commit -m "Added new plugin to listings: NewProjectName"</pre>or (for the master branch);<pre> cd ..'~/addons' svn git add gramps53/listings/* git commit -m "Message describing changesAdded new plugin to listings: NewProjectName"</pre>
== List and document your addon on the wiki==
===List your addon===Add a short description of your addon to the Addons list by editing the current release listing eg: [[5.2_Addons]] or if the addon is meant for a future release [[5.3_Addons]] when available. ==== Example addon template ====Examine the listing for other addons and refer to the [[Addon list legend]] for details of on the meaning of each columns.<pre>|- <!-- Copy this section and list your Addon -->|<!-- Plugin / Documentation -->|<!-- Type -->|<!-- Image -->|<!-- Description -->|<!-- Use -->|<!-- Rating (out of 4) -->|<!-- Contact -->|<!-- Download -->|-</pre> ===Document your addon===Document the addon in the wiki using the page name format of {{man menu|Addon:NewProjectName}} examine the other addon support pages for the general format to use.{{man tip|Hint on creating a new wiki page.|To create a new wiki page use the search box to search for the name of your page that doesn't exist then on the search results page you will be provided with a link to create the new page, by selecting and you can add your content}} ====Example addon article====Consider including the following information: <pre><!-- Copy this section to your Addon support page-->{{Third-party plugin}}<!-- This is a mediawiki template that expands out to display the standard addon message you see at the top of each addon page-->
== Miscellaneous commands Features==
== Support it through issue tracker ==
== Maintain the code as Gramps continues to evolve ==
{{man tip|When submitting an update the patch part of the version number MAJOR.MINOR.PATCH is updated during the addon build process e.g. 1.1.3 to 1.1.4|You can find this step in [https://github.com/gramps-project/addons-source/blob/master/make.py#L125 addons-source/make.py].[https://gramps.discourse.group/t/should-addons-pr-include-version-number-update/2591]}} Remember that Gramps addons exist for many reasons and there are manyGramps developers that do support addons in various ways (translations,triage, keeping in sync with master, download infrastructure, etc).
Some reasons why the addons exist; they provide:
* A place for controversial plugins that will never be accepted into core, but are loved by many users (eg, Data Entry Gramplet).
* A place for experimental components to live.
== Example code adding common enhancements ==
* Copy all the Gramplet's output to a system clipboard via context pop-up menu : Enhancement request {{bug|11573}}, [https://github.com/gramps-project/gramps/pull/1014/commits/72012e13b4ca15caca4b7f36fdb9702c1fd470fd example pull]
* add a custom [[Gramps_Glossary#viewmode|View Mode]] toolbar icon via the <code>.gpr.py</code> : [https://github.com/gramps-project/gramps/pull/1017 Pull 1017 Discussion], [https://github.com/gramps-project/gramps/pull/1017/commits/76e41d546d6ec519dd78fbe07f663135b5c79351 example Pull]
= Resources =
* [[Brief_introduction_to_Git|Git introduction]]
* [[Getting started with Gramps development]]
* [[Portal:Developers]]
* [https://gramps-project.org/docs/gen/gen_plug.html?highlight=include_in_listing#module-gramps.gen.plug._pluginreg Registration Module]
;Gramps Addons site for Gramps 4.2 and newer
* https://github.com/gramps-project/addons-source - Source code (Git)
* https://github.com/gramps-project/addons - downloadable .tgz files
;Gramps Addons site for Gramps 34.2 to Gramps 1 and older* For 4.1.x and earlier, see [[Addons development old]]. = Addon Development Tutorials and Samples =* [[Report-writing_tutorial|Report-writing Tutorial]]* https://sourceforge.net/p/gramps[[Quick_Views|Quick Views]]* [[Gramplets|Gramplets]]* [[Develop_an_Add-on_Rule|Develop an Add-on Rule]]* [[Develop_an_Add-on_Tool|Develop an Add-on Tool]]* [[Adapt_a_built-addons/ in_Report|Adapt a built- Source code (SVN) and downloadable .tgz filesin Report]]
[[Category:Developers/General]]