28
edits
Changes
From Gramps
Synced from repo@41d611f via publish.py
<!--
Index page over the addon kinds. Each kind gets:
- the registration constant
- where the kind shows up in the UI
- the base class (if any) and entry-point shape
- the minimum-viable shape of the implementation module
- a pointer onward (tutorial, similar live addon, the kind's wiki page)
Source of truth for the constants:
../gramps/gramps/gen/plug/_pluginreg.py (PTYPE_STR block, ~L82-L98).
The numeric values aren't author-facing; cite by name.
-->
== Overview ==
Gramps doesn't have one "addon" shape — it has 14 of them, each registered with a different <code>register(KIND, …)</code> constant and each plugged in at a different extension point. This page is the index over all of them, with the registration constant, the UI location, the base class to subclass, and a pointer onward. Use it to answer the first question every prospective addon author asks: '''which kind of thing am I writing?'''
Source of truth for the constants: [https://github.com/gramps-project/gramps/blob/maintenance/gramps60/gramps/gen/plug/_pluginreg.py <code>gramps/gen/plug/_pluginreg.py</code>].
[[File:addon-kinds-ui-map.svg|Fig. 1 — Where each addon kind plugs into the Gramps UI. Menu-anchored kinds (REPORT, TOOL, IMPORT/EXPORT) appear inline with the menu item that hosts them; panel-anchored kinds (SIDEBAR, VIEW, GRAMPLET, QUICKVIEW, MAPSERVICE, RULE) carry callouts to their surface. The six kinds with no direct UI surface — DOCGEN, DATABASE, RELCALC, THUMBNAILER, CITE, GENERAL — are listed separately. Schematic; relative positions match Gramps 6.0's default layout but are not pixel-accurate.]]
== Kinds at a glance ==
{|
! Constant
! Where it shows up
! Typical use
|-
| <code>GRAMPLET</code>
| Dashboard, sidebar, bottombar
| Lightweight widget over the current selection
|-
| <code>VIEW</code>
| Main view area
| A full alternative way to browse the tree
|-
| <code>REPORT</code>
| Reports menu
| Text / graphical output (PDF, HTML, ODF, …) using the docgen interface
|-
| <code>TOOL</code>
| Tools menu
| Operates on the database, optionally writing inside a transaction
|-
| <code>IMPORT</code>
| File → Import
| Reads an external format into the tree
|-
| <code>EXPORT</code>
| File → Export
| Writes the tree to an external format
|-
| <code>DOCGEN</code>
| Report output backends
| Adds a new output format / paper backend used by reports
|-
| <code>QUICKVIEW</code>
| Right-click context menus
| Single-call short report on a selected object (formerly <code>QUICKREPORT</code>)
|-
| <code>SIDEBAR</code>
| Sidebar navigator
| Adds a new sidebar category
|-
| <code>MAPSERVICE</code>
| Geography view
| Adds a new map tile provider
|-
| <code>RELCALC</code>
| Relationships view
| Per-locale relationship calculator
|-
| <code>RULE</code>
| Filter editor
| Adds a new filter rule for an object type
|-
| <code>DATABASE</code>
| New tree backend selection
| Adds support for another database backend
|-
| <code>THUMBNAILER</code>
| Media handling
| Adds a thumbnail generator for an additional media format
|-
| <code>CITE</code>
| Source citations
| Adds a citation formatter style
|-
| <code>GENERAL</code>
| (varies)
| Catch-all for libraries / pluggable categories (<code>WEBSTUFF</code>, <code>Filters</code>, …)
|}
<code>QUICKREPORT</code> is the legacy name for <code>QUICKVIEW</code>; the integer constant is identical (<code>gramps/gen/plug/_pluginreg.py</code> line 83). New addons use <code>QUICKVIEW</code>; existing ones continue to work.
== Per-kind notes ==
The notes below cover the kinds an addon author is likely to write. Kinds with deeper conventions get their own section; the rest are summarised in one paragraph each. For full attribute lists per kind, the authoritative reference is the <code>expand_*</code> functions in <code>_pluginreg.py</code>.
=== <code>GRAMPLET</code> ===
'''Where it shows up:''' docked in the Dashboard, sidebar, or bottombar of any view; can be detached into a floating window.
'''Base class:''' subclass <code>gramps.gen.plug.Gramplet</code>. Override <code>init()</code> (constructor hook, runs once), <code>main()</code> (re-run on update), <code>db_changed()</code> (called when the active database changes), and <code>active_changed()</code> (called when the active person / family / etc. changes).
'''Minimum-viable shape:'''
<syntaxhighlight lang="python">from gramps.gen.plug import Gramplet
class MyGramplet(Gramplet):
def init(self):
self.set_text(_("Hello"))</syntaxhighlight>
'''Registration:''' see [[User:Eduralph/Sandbox/Gramps_6.0_Wiki_Manual_-_Addon_Development_-_Getting_Started#2-add-the-registration-file|02-get-started]] for the full call. Required Gramplet-specific fields are <code>gramplet</code> (the class name) and <code>gramplet_title</code> (the user-visible tab title).
'''Tutorial:''' [[User:Eduralph/Sandbox/Gramps_6.0_Wiki_Manual_-_Addon_Development_-_Tutorials#a-live-gramplet|03-tutorials → A live Gramplet]].
=== <code>REPORT</code> ===
'''Where it shows up:''' Reports menu, organised by category.
'''Base class:''' subclass <code>gramps.gen.plug.report.Report</code>. Override <code>write_report()</code> to emit content. Pair with an options class that subclasses <code>gramps.gen.plug.report.MenuReportOptions</code> and overrides <code>add_menu_options()</code> (to define user-adjustable options) and <code>make_default_style()</code> (to define paragraph and font styles).
'''Categories''' (<code>_pluginreg.py</code> L141–L149): <code>CATEGORY_TEXT</code>, <code>CATEGORY_DRAW</code>, <code>CATEGORY_CODE</code>, <code>CATEGORY_WEB</code>, <code>CATEGORY_BOOK</code>, <code>CATEGORY_GRAPHVIZ</code>, <code>CATEGORY_TREE</code>. Text and Draw reports go through the docgen abstraction, so the same report can emit PDF / HTML / ODF without per-format code.
'''Report modes''' (<code>report_modes</code> field): <code>REPORT_MODE_GUI</code> (dialog-driven), <code>REPORT_MODE_BKI</code> (book item), <code>REPORT_MODE_CLI</code> (command line). Most addons combine GUI + CLI.
'''Tutorial:''' [[User:Eduralph/Sandbox/Gramps_6.0_Wiki_Manual_-_Addon_Development_-_Tutorials#a-text-report|03-tutorials → A text Report]].
=== <code>TOOL</code> ===
'''Where it shows up:''' Tools menu, optionally categorised.
'''Base class:''' subclass a class from <code>gramps.gui.plug.tool</code> (typically <code>Tool</code> or <code>BatchTool</code>). Override the constructor — Gramps passes <code>(dbstate, user, options_class, name, callback=None)</code>. Tools that mutate the database '''must''' do so inside a <code>DbTxn</code>.
'''Categories''' (<code>_pluginreg.py</code> L154–L159): <code>TOOL_DEBUG</code>, <code>TOOL_ANAL</code>, <code>TOOL_DBPROC</code>, <code>TOOL_DBFIX</code>, <code>TOOL_REVCTL</code>, <code>TOOL_UTILS</code>. Choose the one that matches what the tool actually does — <code>TOOL_DBFIX</code> for repairs, <code>TOOL_ANAL</code> for read-only analysis, <code>TOOL_UTILS</code> for generic utilities.
'''Tool modes''' (<code>tool_modes</code> field, <code>_pluginreg.py</code> L183–L184): <code>TOOL_MODE_GUI</code> and <code>TOOL_MODE_CLI</code>. A pure-data tool should support both so a power user can scriptit.
'''Tutorial:''' [[User:Eduralph/Sandbox/Gramps_6.0_Wiki_Manual_-_Addon_Development_-_Tutorials#a-simple-tool|03-tutorials → A simple Tool]].
=== <code>QUICKVIEW</code> ===
'''Where it shows up:''' right-click context menus on the selected object in views and editors.
'''Entry point:''' a <code>run(database, document, person_or_family_or_…)</code> function declared in the implementation module and pointed to by the <code>runfunc</code> field. No class subclassing required.
'''Categories''' (<code>_pluginreg.py</code> L163–L174): <code>CATEGORY_QR_PERSON</code>, <code>CATEGORY_QR_FAMILY</code>, <code>CATEGORY_QR_EVENT</code>, <code>CATEGORY_QR_SOURCE</code>, <code>CATEGORY_QR_PLACE</code>, <code>CATEGORY_QR_REPOSITORY</code>, <code>CATEGORY_QR_NOTE</code>, <code>CATEGORY_QR_DATE</code>, <code>CATEGORY_QR_MEDIA</code>, <code>CATEGORY_QR_CITATION</code>, <code>CATEGORY_QR_SOURCE_OR_CITATION</code>, <code>CATEGORY_QR_MISC</code>. The category determines which context menu the entry appears in.
Quick Views are deliberately the shortest path to a usable report — written against the <code>gramps.gen.simple</code> API (<code>SimpleAccess</code>, <code>SimpleDoc</code>), they hide most of the docgen complexity. Reach for a full <code>REPORT</code> only when you need styles, paragraph layout, or multiple output formats.
'''Tutorial:''' [[User:Eduralph/Sandbox/Gramps_6.0_Wiki_Manual_-_Addon_Development_-_Tutorials#a-quick-view|03-tutorials → A Quick View]].
=== <code>RULE</code> ===
'''Where it shows up:''' the Add Rule dialog when the user composes a custom filter from the Filter Editor; available wherever filters are.
'''Base class:''' subclass the right rule base from <code>gramps.gen.filters.rules</code> — pick the namespace-specific base (<code>gramps.gen.filters.rules.person.Rule</code>, <code>…family.Rule</code>, etc.) that matches the object type your rule applies to. Set the class attributes <code>name</code>, <code>description</code>, <code>category</code>, and <code>labels</code> (the user-prompted arguments); implement <code>apply(db, obj)</code> to return <code>True</code> / <code>False</code>.
'''Tutorial:''' [[User:Eduralph/Sandbox/Gramps_6.0_Wiki_Manual_-_Addon_Development_-_Tutorials#a-custom-filter-rule|03-tutorials → A custom filter Rule]].
=== <code>VIEW</code> ===
'''Where it shows up:''' the main view area; available from the navigator once registered.
'''Base class:''' subclass an appropriate view from <code>gramps.gui.views</code> (<code>NavigationView</code>, <code>ListView</code>, <code>PageView</code>). Views are the heaviest addon kind — they own the entire display surface and the keyboard / mouse interaction. Most addons should reach for <code>GRAMPLET</code> instead and only graduate to <code>VIEW</code> when the gramplet outgrows its container.
'''Live examples:''' <code>CombinedView</code>, <code>LifeLineChartView</code>, <code>QuiltView</code> — read one before writing your own.
=== <code>IMPORT</code> / <code>EXPORT</code> ===
'''Where they show up:''' File → Import / Export, with the new format appearing in the format dropdown.
'''Entry point:''' a module-level function. Importers receive <code>(database, filename, user)</code>; exporters receive <code>(database, filename, error_dialog, option_box, callback)</code> (signatures vary slightly by Gramps minor; the safest move is to read a live importer/exporter and copy the shape).
'''Live examples:''' the GEDCOM (<code>gramps/plugins/importer/importgedcom.py</code>, <code>…/exporter/exportgedcom.py</code>) and JSON importers/exporters in core are the canonical references.
=== <code>DOCGEN</code> ===
'''Where it shows up:''' as a new output format in any Report's options dialog; not user-launched on its own.
'''Base class:''' subclass <code>gramps.gen.plug.docgen.BaseDoc</code> (or the text/draw subclasses depending on what kind of output you generate). A DocGen implements the ''primitives'' — paragraphs, tables, drawing commands — that the abstract Report classes call into. Authors usually only write a new DocGen to add a new output format (e.g. a new word-processor file type); it's a relatively rare addon kind.
=== <code>SIDEBAR</code> ===
'''Where it shows up:''' the navigator on the left of the main window; each <code>SIDEBAR</code> plugin adds one category.
'''Base class:''' subclass <code>gramps.gui.sidebar.Sidebar</code>. Core categories (People, Families, Events, …) are themselves implemented this way, so the canonical examples ship in core under <code>gramps/gui/sidebar/</code>.
=== <code>MAPSERVICE</code> ===
'''Where it shows up:''' the Geography views' map-source dropdown.
'''Base class:''' subclass <code>gramps.plugins.lib.maps.osmgps.MapService</code> and implement the URL / tile-fetch protocol for your provider. Pure tile adapters — no UI changes — so most are very small.
=== <code>RELCALC</code> ===
'''Where it shows up:''' wherever Gramps computes a relationship string (Relationships view, person editor, reports). One <code>RELCALC</code> plugin per locale.
'''Base class:''' subclass <code>gramps.gen.relationship.RelationshipCalculator</code>. The base class supplies all the English-language logic; subclasses override the localised strings and any kinship rules specific to the culture being modelled.
=== <code>DATABASE</code> ===
'''Where it shows up:''' the database-backend dropdown in tree creation.
Adds a fully alternative storage backend implementing the <code>DbReadBase</code> / <code>DbWriteBase</code> interfaces. By far the heaviest kind — the only current in-tree examples are the BSDDB and SQLite backends themselves. Treat the existence of this kind as "yes, it is possible," not "you should consider writing one."
=== <code>THUMBNAILER</code> ===
'''Where it shows up:''' wherever Gramps generates a media thumbnail.
Adds a generator for one additional media format. Pure-function shape: input file → thumbnail image. Use this when a media type Gramps recognises doesn't have a working thumbnailer in your environment.
=== <code>CITE</code> ===
'''Where it shows up:''' the citation style chooser in source / citation editors and reports.
Adds an alternative citation formatter (Chicago, MLA, Evidence Explained, …). Implements the formatting protocol expected by the source / citation code; cite an existing core formatter (<code>gramps/plugins/cite/</code>) for the exact shape on the branch you're targeting.
=== <code>GENERAL</code> ===
'''Where it shows up:''' nowhere directly — <code>GENERAL</code> is the escape hatch for plugin code that doesn't fit any other kind. Two main uses:
* '''Shared libraries''' — code reused across multiple addons. Set <code>load_on_reg=True</code> and the file gets imported at startup; everything in it becomes importable to other plugins as <code>import <addon-id></code>. The <code>libwebconnect</code> addon, depended on by every Web Connect Pack, is the archetype.
* '''Pluggable categories''' — <code>GENERAL</code> plugins can declare a <code>category</code> string; other code can then ask the plugin manager for all <code>GENERAL</code> plugins of category <code>WEBSTUFF</code> (CSS stylesheets for the narrative website report) or <code>Filters</code> (filter-rule providers). New categories are rare; the published ones are documented in [[Addons_development#Registered_GENERAL_Categories|addons-development]].
The category <code>WEBSTUFF</code> is the one most addon authors meet: addons that ship a stylesheet for the narrative website register as <code>GENERAL, category="WEBSTUFF"</code> and the website report picks them up automatically.
== Multiple kinds in one addon ==
A single <code>.gpr.py</code> can call <code>register(...)</code> more than once. The classic case is a report that also registers a Quick View entry for the same underlying logic (<code>gramps/plugins/quickview/all_events.py</code> does this for events). Each <code>register()</code> call is independent; only the addon folder / <code>id</code> and the implementation file(s) are shared.
== See also ==
* [[User:Eduralph/Sandbox/Gramps_6.0_Wiki_Manual_-_Addon_Development|01-overview]] — what an addon is, file roles.
* [[User:Eduralph/Sandbox/Gramps_6.0_Wiki_Manual_-_Addon_Development_-_Getting_Started|02-get-started]] — first Gramplet end-to-end.
* [[User:Eduralph/Sandbox/Gramps_6.0_Wiki_Manual_-_Addon_Development_-_Tutorials|03-tutorials]] — per-kind walkthroughs.
* [[User:Eduralph/Sandbox/Gramps_6.0_Wiki_Manual_-_Addon_Development_-_Fundamentals|05-fundamentals]] — the cross-cutting concepts every kind relies on.
* [https://github.com/gramps-project/gramps/blob/maintenance/gramps60/gramps/gen/plug/_pluginreg.py <code>gramps/gen/plug/_pluginreg.py</code>] — the authoritative definition of all the constants and <code>expand_*</code> attribute lists per kind.
* [[6.0_Addons|6.0 Addons]] — the canonical catalogue of what already exists per kind; reading a similar addon's source is your fastest second tutorial.
{{stub}}
Index page over the addon kinds. Each kind gets:
- the registration constant
- where the kind shows up in the UI
- the base class (if any) and entry-point shape
- the minimum-viable shape of the implementation module
- a pointer onward (tutorial, similar live addon, the kind's wiki page)
Source of truth for the constants:
../gramps/gramps/gen/plug/_pluginreg.py (PTYPE_STR block, ~L82-L98).
The numeric values aren't author-facing; cite by name.
-->
== Overview ==
Gramps doesn't have one "addon" shape — it has 14 of them, each registered with a different <code>register(KIND, …)</code> constant and each plugged in at a different extension point. This page is the index over all of them, with the registration constant, the UI location, the base class to subclass, and a pointer onward. Use it to answer the first question every prospective addon author asks: '''which kind of thing am I writing?'''
Source of truth for the constants: [https://github.com/gramps-project/gramps/blob/maintenance/gramps60/gramps/gen/plug/_pluginreg.py <code>gramps/gen/plug/_pluginreg.py</code>].
[[File:addon-kinds-ui-map.svg|Fig. 1 — Where each addon kind plugs into the Gramps UI. Menu-anchored kinds (REPORT, TOOL, IMPORT/EXPORT) appear inline with the menu item that hosts them; panel-anchored kinds (SIDEBAR, VIEW, GRAMPLET, QUICKVIEW, MAPSERVICE, RULE) carry callouts to their surface. The six kinds with no direct UI surface — DOCGEN, DATABASE, RELCALC, THUMBNAILER, CITE, GENERAL — are listed separately. Schematic; relative positions match Gramps 6.0's default layout but are not pixel-accurate.]]
== Kinds at a glance ==
{|
! Constant
! Where it shows up
! Typical use
|-
| <code>GRAMPLET</code>
| Dashboard, sidebar, bottombar
| Lightweight widget over the current selection
|-
| <code>VIEW</code>
| Main view area
| A full alternative way to browse the tree
|-
| <code>REPORT</code>
| Reports menu
| Text / graphical output (PDF, HTML, ODF, …) using the docgen interface
|-
| <code>TOOL</code>
| Tools menu
| Operates on the database, optionally writing inside a transaction
|-
| <code>IMPORT</code>
| File → Import
| Reads an external format into the tree
|-
| <code>EXPORT</code>
| File → Export
| Writes the tree to an external format
|-
| <code>DOCGEN</code>
| Report output backends
| Adds a new output format / paper backend used by reports
|-
| <code>QUICKVIEW</code>
| Right-click context menus
| Single-call short report on a selected object (formerly <code>QUICKREPORT</code>)
|-
| <code>SIDEBAR</code>
| Sidebar navigator
| Adds a new sidebar category
|-
| <code>MAPSERVICE</code>
| Geography view
| Adds a new map tile provider
|-
| <code>RELCALC</code>
| Relationships view
| Per-locale relationship calculator
|-
| <code>RULE</code>
| Filter editor
| Adds a new filter rule for an object type
|-
| <code>DATABASE</code>
| New tree backend selection
| Adds support for another database backend
|-
| <code>THUMBNAILER</code>
| Media handling
| Adds a thumbnail generator for an additional media format
|-
| <code>CITE</code>
| Source citations
| Adds a citation formatter style
|-
| <code>GENERAL</code>
| (varies)
| Catch-all for libraries / pluggable categories (<code>WEBSTUFF</code>, <code>Filters</code>, …)
|}
<code>QUICKREPORT</code> is the legacy name for <code>QUICKVIEW</code>; the integer constant is identical (<code>gramps/gen/plug/_pluginreg.py</code> line 83). New addons use <code>QUICKVIEW</code>; existing ones continue to work.
== Per-kind notes ==
The notes below cover the kinds an addon author is likely to write. Kinds with deeper conventions get their own section; the rest are summarised in one paragraph each. For full attribute lists per kind, the authoritative reference is the <code>expand_*</code> functions in <code>_pluginreg.py</code>.
=== <code>GRAMPLET</code> ===
'''Where it shows up:''' docked in the Dashboard, sidebar, or bottombar of any view; can be detached into a floating window.
'''Base class:''' subclass <code>gramps.gen.plug.Gramplet</code>. Override <code>init()</code> (constructor hook, runs once), <code>main()</code> (re-run on update), <code>db_changed()</code> (called when the active database changes), and <code>active_changed()</code> (called when the active person / family / etc. changes).
'''Minimum-viable shape:'''
<syntaxhighlight lang="python">from gramps.gen.plug import Gramplet
class MyGramplet(Gramplet):
def init(self):
self.set_text(_("Hello"))</syntaxhighlight>
'''Registration:''' see [[User:Eduralph/Sandbox/Gramps_6.0_Wiki_Manual_-_Addon_Development_-_Getting_Started#2-add-the-registration-file|02-get-started]] for the full call. Required Gramplet-specific fields are <code>gramplet</code> (the class name) and <code>gramplet_title</code> (the user-visible tab title).
'''Tutorial:''' [[User:Eduralph/Sandbox/Gramps_6.0_Wiki_Manual_-_Addon_Development_-_Tutorials#a-live-gramplet|03-tutorials → A live Gramplet]].
=== <code>REPORT</code> ===
'''Where it shows up:''' Reports menu, organised by category.
'''Base class:''' subclass <code>gramps.gen.plug.report.Report</code>. Override <code>write_report()</code> to emit content. Pair with an options class that subclasses <code>gramps.gen.plug.report.MenuReportOptions</code> and overrides <code>add_menu_options()</code> (to define user-adjustable options) and <code>make_default_style()</code> (to define paragraph and font styles).
'''Categories''' (<code>_pluginreg.py</code> L141–L149): <code>CATEGORY_TEXT</code>, <code>CATEGORY_DRAW</code>, <code>CATEGORY_CODE</code>, <code>CATEGORY_WEB</code>, <code>CATEGORY_BOOK</code>, <code>CATEGORY_GRAPHVIZ</code>, <code>CATEGORY_TREE</code>. Text and Draw reports go through the docgen abstraction, so the same report can emit PDF / HTML / ODF without per-format code.
'''Report modes''' (<code>report_modes</code> field): <code>REPORT_MODE_GUI</code> (dialog-driven), <code>REPORT_MODE_BKI</code> (book item), <code>REPORT_MODE_CLI</code> (command line). Most addons combine GUI + CLI.
'''Tutorial:''' [[User:Eduralph/Sandbox/Gramps_6.0_Wiki_Manual_-_Addon_Development_-_Tutorials#a-text-report|03-tutorials → A text Report]].
=== <code>TOOL</code> ===
'''Where it shows up:''' Tools menu, optionally categorised.
'''Base class:''' subclass a class from <code>gramps.gui.plug.tool</code> (typically <code>Tool</code> or <code>BatchTool</code>). Override the constructor — Gramps passes <code>(dbstate, user, options_class, name, callback=None)</code>. Tools that mutate the database '''must''' do so inside a <code>DbTxn</code>.
'''Categories''' (<code>_pluginreg.py</code> L154–L159): <code>TOOL_DEBUG</code>, <code>TOOL_ANAL</code>, <code>TOOL_DBPROC</code>, <code>TOOL_DBFIX</code>, <code>TOOL_REVCTL</code>, <code>TOOL_UTILS</code>. Choose the one that matches what the tool actually does — <code>TOOL_DBFIX</code> for repairs, <code>TOOL_ANAL</code> for read-only analysis, <code>TOOL_UTILS</code> for generic utilities.
'''Tool modes''' (<code>tool_modes</code> field, <code>_pluginreg.py</code> L183–L184): <code>TOOL_MODE_GUI</code> and <code>TOOL_MODE_CLI</code>. A pure-data tool should support both so a power user can scriptit.
'''Tutorial:''' [[User:Eduralph/Sandbox/Gramps_6.0_Wiki_Manual_-_Addon_Development_-_Tutorials#a-simple-tool|03-tutorials → A simple Tool]].
=== <code>QUICKVIEW</code> ===
'''Where it shows up:''' right-click context menus on the selected object in views and editors.
'''Entry point:''' a <code>run(database, document, person_or_family_or_…)</code> function declared in the implementation module and pointed to by the <code>runfunc</code> field. No class subclassing required.
'''Categories''' (<code>_pluginreg.py</code> L163–L174): <code>CATEGORY_QR_PERSON</code>, <code>CATEGORY_QR_FAMILY</code>, <code>CATEGORY_QR_EVENT</code>, <code>CATEGORY_QR_SOURCE</code>, <code>CATEGORY_QR_PLACE</code>, <code>CATEGORY_QR_REPOSITORY</code>, <code>CATEGORY_QR_NOTE</code>, <code>CATEGORY_QR_DATE</code>, <code>CATEGORY_QR_MEDIA</code>, <code>CATEGORY_QR_CITATION</code>, <code>CATEGORY_QR_SOURCE_OR_CITATION</code>, <code>CATEGORY_QR_MISC</code>. The category determines which context menu the entry appears in.
Quick Views are deliberately the shortest path to a usable report — written against the <code>gramps.gen.simple</code> API (<code>SimpleAccess</code>, <code>SimpleDoc</code>), they hide most of the docgen complexity. Reach for a full <code>REPORT</code> only when you need styles, paragraph layout, or multiple output formats.
'''Tutorial:''' [[User:Eduralph/Sandbox/Gramps_6.0_Wiki_Manual_-_Addon_Development_-_Tutorials#a-quick-view|03-tutorials → A Quick View]].
=== <code>RULE</code> ===
'''Where it shows up:''' the Add Rule dialog when the user composes a custom filter from the Filter Editor; available wherever filters are.
'''Base class:''' subclass the right rule base from <code>gramps.gen.filters.rules</code> — pick the namespace-specific base (<code>gramps.gen.filters.rules.person.Rule</code>, <code>…family.Rule</code>, etc.) that matches the object type your rule applies to. Set the class attributes <code>name</code>, <code>description</code>, <code>category</code>, and <code>labels</code> (the user-prompted arguments); implement <code>apply(db, obj)</code> to return <code>True</code> / <code>False</code>.
'''Tutorial:''' [[User:Eduralph/Sandbox/Gramps_6.0_Wiki_Manual_-_Addon_Development_-_Tutorials#a-custom-filter-rule|03-tutorials → A custom filter Rule]].
=== <code>VIEW</code> ===
'''Where it shows up:''' the main view area; available from the navigator once registered.
'''Base class:''' subclass an appropriate view from <code>gramps.gui.views</code> (<code>NavigationView</code>, <code>ListView</code>, <code>PageView</code>). Views are the heaviest addon kind — they own the entire display surface and the keyboard / mouse interaction. Most addons should reach for <code>GRAMPLET</code> instead and only graduate to <code>VIEW</code> when the gramplet outgrows its container.
'''Live examples:''' <code>CombinedView</code>, <code>LifeLineChartView</code>, <code>QuiltView</code> — read one before writing your own.
=== <code>IMPORT</code> / <code>EXPORT</code> ===
'''Where they show up:''' File → Import / Export, with the new format appearing in the format dropdown.
'''Entry point:''' a module-level function. Importers receive <code>(database, filename, user)</code>; exporters receive <code>(database, filename, error_dialog, option_box, callback)</code> (signatures vary slightly by Gramps minor; the safest move is to read a live importer/exporter and copy the shape).
'''Live examples:''' the GEDCOM (<code>gramps/plugins/importer/importgedcom.py</code>, <code>…/exporter/exportgedcom.py</code>) and JSON importers/exporters in core are the canonical references.
=== <code>DOCGEN</code> ===
'''Where it shows up:''' as a new output format in any Report's options dialog; not user-launched on its own.
'''Base class:''' subclass <code>gramps.gen.plug.docgen.BaseDoc</code> (or the text/draw subclasses depending on what kind of output you generate). A DocGen implements the ''primitives'' — paragraphs, tables, drawing commands — that the abstract Report classes call into. Authors usually only write a new DocGen to add a new output format (e.g. a new word-processor file type); it's a relatively rare addon kind.
=== <code>SIDEBAR</code> ===
'''Where it shows up:''' the navigator on the left of the main window; each <code>SIDEBAR</code> plugin adds one category.
'''Base class:''' subclass <code>gramps.gui.sidebar.Sidebar</code>. Core categories (People, Families, Events, …) are themselves implemented this way, so the canonical examples ship in core under <code>gramps/gui/sidebar/</code>.
=== <code>MAPSERVICE</code> ===
'''Where it shows up:''' the Geography views' map-source dropdown.
'''Base class:''' subclass <code>gramps.plugins.lib.maps.osmgps.MapService</code> and implement the URL / tile-fetch protocol for your provider. Pure tile adapters — no UI changes — so most are very small.
=== <code>RELCALC</code> ===
'''Where it shows up:''' wherever Gramps computes a relationship string (Relationships view, person editor, reports). One <code>RELCALC</code> plugin per locale.
'''Base class:''' subclass <code>gramps.gen.relationship.RelationshipCalculator</code>. The base class supplies all the English-language logic; subclasses override the localised strings and any kinship rules specific to the culture being modelled.
=== <code>DATABASE</code> ===
'''Where it shows up:''' the database-backend dropdown in tree creation.
Adds a fully alternative storage backend implementing the <code>DbReadBase</code> / <code>DbWriteBase</code> interfaces. By far the heaviest kind — the only current in-tree examples are the BSDDB and SQLite backends themselves. Treat the existence of this kind as "yes, it is possible," not "you should consider writing one."
=== <code>THUMBNAILER</code> ===
'''Where it shows up:''' wherever Gramps generates a media thumbnail.
Adds a generator for one additional media format. Pure-function shape: input file → thumbnail image. Use this when a media type Gramps recognises doesn't have a working thumbnailer in your environment.
=== <code>CITE</code> ===
'''Where it shows up:''' the citation style chooser in source / citation editors and reports.
Adds an alternative citation formatter (Chicago, MLA, Evidence Explained, …). Implements the formatting protocol expected by the source / citation code; cite an existing core formatter (<code>gramps/plugins/cite/</code>) for the exact shape on the branch you're targeting.
=== <code>GENERAL</code> ===
'''Where it shows up:''' nowhere directly — <code>GENERAL</code> is the escape hatch for plugin code that doesn't fit any other kind. Two main uses:
* '''Shared libraries''' — code reused across multiple addons. Set <code>load_on_reg=True</code> and the file gets imported at startup; everything in it becomes importable to other plugins as <code>import <addon-id></code>. The <code>libwebconnect</code> addon, depended on by every Web Connect Pack, is the archetype.
* '''Pluggable categories''' — <code>GENERAL</code> plugins can declare a <code>category</code> string; other code can then ask the plugin manager for all <code>GENERAL</code> plugins of category <code>WEBSTUFF</code> (CSS stylesheets for the narrative website report) or <code>Filters</code> (filter-rule providers). New categories are rare; the published ones are documented in [[Addons_development#Registered_GENERAL_Categories|addons-development]].
The category <code>WEBSTUFF</code> is the one most addon authors meet: addons that ship a stylesheet for the narrative website register as <code>GENERAL, category="WEBSTUFF"</code> and the website report picks them up automatically.
== Multiple kinds in one addon ==
A single <code>.gpr.py</code> can call <code>register(...)</code> more than once. The classic case is a report that also registers a Quick View entry for the same underlying logic (<code>gramps/plugins/quickview/all_events.py</code> does this for events). Each <code>register()</code> call is independent; only the addon folder / <code>id</code> and the implementation file(s) are shared.
== See also ==
* [[User:Eduralph/Sandbox/Gramps_6.0_Wiki_Manual_-_Addon_Development|01-overview]] — what an addon is, file roles.
* [[User:Eduralph/Sandbox/Gramps_6.0_Wiki_Manual_-_Addon_Development_-_Getting_Started|02-get-started]] — first Gramplet end-to-end.
* [[User:Eduralph/Sandbox/Gramps_6.0_Wiki_Manual_-_Addon_Development_-_Tutorials|03-tutorials]] — per-kind walkthroughs.
* [[User:Eduralph/Sandbox/Gramps_6.0_Wiki_Manual_-_Addon_Development_-_Fundamentals|05-fundamentals]] — the cross-cutting concepts every kind relies on.
* [https://github.com/gramps-project/gramps/blob/maintenance/gramps60/gramps/gen/plug/_pluginreg.py <code>gramps/gen/plug/_pluginreg.py</code>] — the authoritative definition of all the constants and <code>expand_*</code> attribute lists per kind.
* [[6.0_Addons|6.0 Addons]] — the canonical catalogue of what already exists per kind; reading a similar addon's source is your fastest second tutorial.
{{stub}}
