4,216
edits
Changes
→Get a local copy of Gramps and its addons
* '''[[Gramps_{{man version}}_Wiki_Manual_-_Reports_-_part_8#Quick_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 Family Tree data.
* '''[[Gramps_{{man version}}_Wiki_Manual_-_Filters#Add_Rule_dialog|Rule]]''' (RULE) - adds new [[Gramps_Glossary#filter|filter]] rules. <small>{{new for version |5.1</small>}}
* '''[[Gramps_{{man version}}_Wiki_Manual_-_Tools|Tool]]''' (TOOL) - adds a utility that helps process data from your family tree.
* '''Doc creator''' (DOCGEN)
* '''Relationships''' (RECALC)
* '''Sidebar''' (SIDEBAR)
* '''[[Database_Backends|Database]]''' (DATABASE) - add support for another database backend. <small>{{new for version |5.0</small>}}* '''Thumbnailer''' (THUMBNAILER) - ⚡<small>''{{new for version |5.2.0''</small>}}* '''Citation formatter''' (CITE) - ⚡<small>''{{new for version |5.2.0''</small>}}
==Writing an addon==
== 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.
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',
=== 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 ====
;Gramps Addons site for Gramps 4.1 and older
* For 4.1.x and earlier, see [[Addons development old]].
= See also 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:Developers/Tutorials]]