4,216
edits
Changes
→Get a local copy of Gramps and its addons
{{man tip|Information on developing Gramps addons|If you are looking for addons to install, visit: [[Third-party Addons]]}}{{man warn|WarningNote that this article anticipates that most addons will be developed under Linux.|([[Getting started with Gramps development|Linux is the principal development platform.]]) While it is possible to do so under Windows or MacOS, some of the steps will differ and the documented processes have not been as thoroughly reviewed. So developer beware.<br>See [[Portal:Developers]]}}If you are developing a [[Third-party Addons|This Third-party Addon]]; this page documents the API, methods, and best practices for developing a 3rd-party addon for GRAMPS 3Gramps 4.2 / 3.3 / 3and later.4.}}
==What can addons extend?==Addons for GRAMPS 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 Gramps continues to evolve
We'll now look at expand upon each of these steps in detailindividually.
== Develop your addon ==
The [http://github.com/gramps-project/addons subversion -source addons-source] repository has holds the source code for the addons with branches holding the version for different gramps. If you are working on an addon for gramps for the following structure:current Gramps {{man version}} public release, be sure to use the maintenance/gramps52 git branch, as the default is master branch for the developmental pre-release. (Currently gramps 5.3, which is not the typical target for addons.)
*** /download
** * /listings** [https://github.com/gramps-project/addons/branchestree/master/gramps50 /gramps50]*** /download*** /listings** [https://github.com/gramps{{stable_branch}}-project/addons/tree/master/gramps51 /gramps51]*** /gramps32download*** /listings** [https://github.com/gramps-project/contribaddons/tree/master/gramps52 /gramps52]*** /download*** /listings === Get a local copy of Gramps and its addons === These steps show how to downloadthe addon sources. # 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]] for instructions on installing git and getting basic settings configured. Also [https://help.github.com/articles/generating-an-ssh-key/ Connecting to GitHub with SSH] will help with setting up credentials for GitHub.To fully build and advertise a new addon will require local copies of the three repositories, the 'addons-source', 'addons' and the main Gramps source 'gramps'. This wiki assumes that all three git repositories local locations are put into the same base directory and named with the repository names in order for the make.py script commands to work as shown. From the base directory, run the following commands to create a copy of each repository. If you want to use SSH; git clone [email protected]:gramps-project/addons-source.git addons-source git clone [email protected]:gramps-project/addons.git addons git clone [email protected]:gramps-project/gramps.git gramps or if you want to use a web url: git clone https://github.com/gramps-project/addons-source.git addons-source git clone https://github.com/gramps-project/addons.git addons git clone https://github.com/gramps-project/gramps.git gramps
For example if your home directory is '/home/name' and you use the default ("suggested path names, use: <code>GRAMPSPATH=/home/name/gramps LANGUAGE='en_US.UTF-8' python3 make.py ./..</code>to replace the <code>./make.") is not correctpy</code> in the examples below.
To commit test your changes so addon as you develop it is suggested that others can use you copy your NewProjectName plugin into your Gramps user plugin directory from your addondevelopment directory, prior to testing. Or just edit in the Gramps user plugin directory until it is ready to publish, follow these steps:then copy back to your addon development directory.
=== Config ===
Some addons may want to have persistent data (data settings that remain between sessions). You can handle this yourself, or you can use Gramps' built-in configure system.
from config import configas configman cm config = configconfigman.register_manager("view_placetreeview_0grampletname") cm# register the values to save: config.register("section.variable1option-name1", value1) cmconfig.register("section.variable2option-name2", value2)
...
This will create the file "view_placetreeview_0grampletname.ini" and put in the same directory as the addon. In If the addonconfig file already exists, you can then:it remains intact.
In the addon, you can then: x = cmconfig.get("section.variable1option-name1") cmconfig.set("section.variable1option-name1", 3)
and when this code is exiting, you might want to save the config. In a Gramplet that would be:
def on_save(self):
If your code is a system-level file, then you might want to save the config in the Gramps system folder:
This, however, would be rare; most .ini files would go into the plugins directory.
In other code that might use this config file, you would do this:
from config import configas configman cm config = configconfigman.get_manager("view_placetreeview_0grampletname") x = cmconfig.get("section.variable1option-name1")
=== 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.
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:
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
# ngettext# ugettext# ungettextsgettext
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'''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 ==
<pre>
register(PTYPE,
gramps_target_version = "35.42",
version = "1.0.0",
ATTR = value,
</pre>
[https://github.com/gramps-project/gramps/blob/master/gramps/gen/plug/_pluginreg.py#L76 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.
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://svngithub.code.sf.net/pcom/gramps/code/trunk-project/gramps/plugins/ here] (for example, see [httphttps://grampsgithub.svn.sourceforge.netcom/viewvcgramps-project/gramps/trunk/src/plugins/drawreport/drawplugins.gpr.py?view=markup trunk/srcgramps/plugins/drawreport/drawreportdrawplugins.gpr.py]) and see the full documentation in the [httphttps://github.com/gramps.svn.sourceforge.net-project/gramps/blob/viewvc3f0db9303f29811b43325c30149c8844c7ce24b6/gramps/trunkgen/plug/src_pluginreg.py#L23 master/gramps/gen/plug/_pluginreg.py?view=markup 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 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>: <code>./make.py gramps52 init NewProjectName</code># * 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):## : <code>./make.py gramps52 init NewProjectName fr</code># * Update it from gramps and other addons:## : <code>./make.py gramps52 update NewProjectName fr</code># * Edit contribthe translations file manually:: <code>/NewProjectName/po/fr-local.po</code># * Compile the language:## : <code>./make.py gramps52 compile NewProjectName</code># * Add or update your local language file, and commit changes:## svn : <code>git add NewProjectName/po/fr-local.po</code>## svn : <code>git commit NewProjectName/po/fr-local.po -m "Added fr po file"</code>* If you have been given 'push' rights to GitHub 'gramps-project/addons-source', then;: <code>git push origin gramps52</code>
== 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.
{{man warn|Gramps needs to have been built|Make sure you have already built gramps52 or master. python makeChange to the appropriate git branch in your gramps directory, and run <code>python3 setup.py build all</code> See [[Linux:Build_from_source]]}}
To compile all projects to their download/Addon.addon.tgz filescreate a listing:
== Support it through issue tracker ==
== Maintain the Example code as GRAMPS continues to evolve 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* httphttps://github.com/gramps-project/addons-source - Source code (Git)* https://github.svn.sourceforge.net/viewvccom/gramps-project/addons/ - SVN browsedownloadable .tgz files;Gramps Addons site for Gramps 4.1 and older* For 4.1.x and earlier, see [[Addons development old]]. = Addon Development Tutorials and Samples =* [[Report-writing_tutorial|Report-writing Tutorial]]* [[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-in_Report|Adapt a built-in Report]]
[[Category:Developers/General]]
[[Category:Reports]]
[[Category:Gramplets]]
[[Category:Addons]]