Open main menu

Gramps β

Changes

Addons development

2,511 bytes added, 10 March
Get a local copy of Gramps and its addons
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:
#Report<!-- sync with https://gramps-project.org/wiki/index.php?title=Addon_list_legend&action=edit&section=2 --> * '''Importer''' (IMPORT) - adds additional file format import options to Gramps#Quickreport* '''Exporter''' (EXPORT) - adds additional file format export options to Gramps* '''[[Gramps_Glossary#Toolgramplet|Gramplet]]''' (GRAMPLET) - adds a new interactive interface section to a Gramps view mode, which can be activated by right-clicking on the dashboard View or from the menu of the Sidebar/Bottombar in the other view categories. * '''Gramps [[Gramps_Glossary#Importerviewmode|View ''(mode)'']]''' (VIEW) - adds a new view mode to the list of views available within a [[Gramps_Glossary#Exporterview|View Category]]#Doc creator* '''[[Map_Services|Map Service]]''' (MAPSERVICE) - adds new mapping options to Gramps#* '''Plugin lib''' (GENERAL) - libraries that are present giving extra functionality. Can add, replace and or modifies built-in Gramps options.* '''[[Gramps_{{man version}}_Wiki_Manual_-_Reports_-_part_8#Map serviceQuick_Views|Quickreport'''/'''Quickview]]''' (QUICKREPORT) - a view that you can run by right-clicking on object, or if a person quickview, then through the Quick View Gramplet#* '''[[Gramps_{{man version}}_Wiki_Manual_-_Reports_-_part_1|Report]]''' (REPORT) - adds a new output report / includes '''Website''' - output a static genealogy website based on your Gramps ViewFamily Tree data.* '''[[Gramps_{{man version}}_Wiki_Manual_-_Filters#Add_Rule_dialog|Rule]]''' (RULE) - adds new [[Gramps_Glossary#filter|filter]] rules. {{new|5.1}}* '''[[Gramps_{{man version}}_Wiki_Manual_-_Tools|Tool]]''' (TOOL) - adds a utility that helps process data from your family tree.* '''Doc creator''' (DOCGEN)* '''Relationships''' (RECALC)#Gramplet#* '''Sidebar''' (SIDEBAR)#* '''[[Database_Backends|Database ]]''' (Introduced Gramps DATABASE) - add support for another database backend. {{new|5.x and greater0}}* '''Thumbnailer''' (THUMBNAILER){{new|5.2}}#Rule * '''Citation formatter''' (Introduced Gramps CITE) {{new|5.1.x and greater)2}}
==Writing an addon==
# [[#List_and_document_your_addon_on_the_wiki|Document your addon]] and publish it to the addon list
# [[#List_your_addon_in_the_Gramps_Plugin_Manager|Register your addon with the Plugin Manager]]
# [[#Announce_it_on_the_Gramps_mailing_listAnnounce_the_addon|Announce it on the Gramps mailing listForum]] - 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
== Develop your addon ==
The [http://github.com/gramps-project/addons-source addons-source] repository 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 current Gramps {{man version}} public release, be sure to use the maintenance/gramps51 gramps52 git branch, as the default is master branch for the developmental pre-release. (Currently gramps 5.23, which is not the typical target for addons.)
Example commands are shown below referring to the public release rather than the master branch.
* /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
 
=== Get a local copy of Gramps and its addons ===
git clone https://github.com/gramps-project/gramps.git gramps
To switch to a local copy of the gramps51 gramps52 maintenance branch:
cd addons-source
git checkout -b gramps51 gramps52 origin/maintenance/gramps51gramps52
or to work in the master branch:
cd addons-source
git checkout -b gramps52 gramps53 origin/master
=== Other prerequisites ===
* Remove the files using the ''clean'' command that should not be added to GitHub (eg files(template.pot/ locale etc)):
: <code>./make.py gramps51 gramps52 clean NewProjectName</code>
* Add the project to the repository:
: <code>git add NewProjectName</code>
* to make sure that outside changes do not affect your commit
: <code>git pull --rebase</code>
: <code>git push origin gramps51gramps52</code>
Also you may want to [[Addons_development#Package_your_addon |Package your addon]] so it can be downloaded via the plugin manager.
To build and compile translations for all projects to their download/Addon.addon.tgz files:
: <code>python3 make.py gramps51 gramps52 build all</code>
To compile translations for all projects :
: <code>python3 make.py gramps51 gramps52 compile all</code>
== Create a Gramps Plugin Registration file ==
<pre>
register(PTYPE,
gramps_target_version = "5.12",
version = "1.0.0",
ATTR = value,
description = _("Attaches a shared source to multiple objects."),
version = '1.0.0',
gramps_target_version = '5.12',
status = STABLE,
fname = 'AttachSourceTool.py',
</pre>
You can see examples of the kinds of addons [https://github.com/gramps-project/gramps/plugins here] (for example, see [https://github.com/gramps-project/gramps/plugins/drawreport/drawplugins.gpr.py gramps/plugins/drawreport/drawplugins.gpr.py]) and see the full documentation in the [https://github.com/gramps-project/gramps/blob/3f0db9303f29811b43325c30149c8844c7ce24b6/gramps/gen/plug/_pluginreg.py#L23 master/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>
description = _("Provides a library for doing something."),
version = '1.0',
gramps_target_version = '5.12',
status = STABLE,
fname = 'library.py',
category = "WEBSTUFF",
version = '1.0',
gramps_target_version = '5.12',
data = ["a", "b", "c"],
)
description = _("Provides a collection of stylesheets for the web"),
version = '1.0',
gramps_target_version = '5.12',
fname = "stylesheet.py",
load_on_reg = True,
* Initialize and update the <code>template.pot</code> for your addon:
: <code>cd ~/addons-source</code>
: <code>./make.py gramps51 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 gramps51 gramps52 init NewProjectName fr</code>
* Update it from gramps and other addons:
: <code>./make.py gramps51 gramps52 update NewProjectName fr</code>
* Edit the translations file manually:
: <code>/NewProjectName/po/fr-local.po</code>
* Compile the language:
: <code>./make.py gramps51 gramps52 compile NewProjectName</code>
* Add or update your local language file, and commit changes:
: <code>git add NewProjectName/po/fr-local.po</code>
: <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 gramps51gramps52</code>
== Package your addon ==
To create a downloadable package:
: <code>./make.py gramps51 gramps52 build NewProjectName</code> or: <code>./make.py gramps52 gramps53 build NewProjectName</code> for the master branch.
This will automatically include the following files in your build:
<pre> cd '~/addons'
git add gramps51gramps52/download/NewProjectName.addon.tgz
git commit -m "Added new plugin: NewProjectName"</pre>
or (for the master branch);
<pre> cd '~/addons'
git add gramps52gramps53/download/NewProjectName.addon.tgz
git commit -m " Added 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 gramps51 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:
: <code>cd '~/gramps-addons'</code> or wherever you have built your addon
: <code>GRAMPSPATH=path/to/your/gramps/install ./make.py gramps51 gramps52 listing NewProjectName</code>
or (for the master branch);
: <code>cd '~/gramps-addons'</code> or wherever you have built your addon
: <code>GRAMPSPATH=path/to/your/gramps/install ./make.py gramps52 gramps53 listing NewProjectName</code>
That will create a series of files in the <tt>../listings/</tt> directory.
<pre> cd '~/addons'
git add gramps51gramps52/listings/*
git commit -m "Added new plugin to listings: NewProjectName"</pre>
or (for the master branch);
<pre> cd '~/addons'
git add gramps52gramps53/listings/*
git commit -m " Added new plugin to listings: NewProjectName"</pre>
===List your addon===
Add a short description of your addon to the Addons list by editing the current release listing eg: [[5.1_Addons2_Addons]] or if the addon is meant for a future release [[5.2_Addons3_Addons]] when available.
==== Example addon template ====
== Announce the addon ==
Join the [[Contact#Mailing_listsForum|Gramps Mailing lists]] or [[Contact#Forum|Forum]] and announce it to the users with general information on why you created and how to use it.
== Support it through issue tracker ==
;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]]