Gramps 3.3 Wiki Manual - Plugin Manager
|Special copyright notice: All edits to this page need to be under two different copyright licenses:
These licenses allow the Gramps project to maximally use this wiki manual as free content in future Gramps versions. If you do not agree with this dual license, then do not edit this page. You may only link to other pages within the wiki which fall only under the GFDL license via external links (using the syntax: [http://www.gramps-project.org/...]), not via internal links.
The Plugin Manager is available from the menu Help ->Plugin Manager. Many of the features of the Plugin Manager are intended for developers, and the dialogues described below are those seen by developers. The features for normal users are noted below where they are different.
Gramps detects whether it is being run in User mode or Developer mode by the 'optimise' flag:
python -O gramps.py
See Debugging GRAMPS.
Gramps consists of a core plus many plugins. When Gramps starts, the core is loaded and only a limited number of plugins are loaded. This decreases the startup time and memory requirements of Gramps. Subsequently, many plugins are automatically loaded by Gramps as they are needed, so that many users will not need to be aware of the existence of plugins, or their delayed loading.
The Plugin Manager allows you to control how Gramps manages plugins.
There are two main categories of plugins in Gramps: "user plugins" and "system plugins". User plugins are those that you use and control to provide different functionality for you. The system plugins are used by Gramps.
The following types of User Plugins are present in Gramps:
- doc creators: Backends for which Gramps can write reports (pdf, odf, ascii text, ...)
- exporters: export formats you can export your data too via menu Family Trees ->Export...
- gramplets: small programs you can embed in the GrampletView, or detach and use as a normal window
- gramps views: the views visible in the main window of Gramps
- importers: import formats from which Gramps can import data via menu Family Trees ->Import...
- map service: targets that can be used on the place view to go to an internet map service (Go toolbar button)
- quickreport: small reports that are available in the context menu on the listviews, or via the Quickreport gramplet
- reports: Textual or graphical reports Gramps can produce
- tools: Tools you can start via the menu Tools
The following types of System Plugins are present in Gramps:
- plugin libs: libraries that are present giving extra functionality.
- relationships: relationship calculators for different languages
There are many plugins that come with Gramps. However, anyone can also write a plugin and share it. These third-party plugins are called "addons". We highly encourage users and developers to share their creations with other Gramps users.
Registration and loading
Plugins are either held locally on the computer and are known about by Gramps, when they are said to be Registered, or they are held on a remote computer and Gramps only knows their name, type and description, when they are said to be Addons.
When Gramps starts, information is automatically read about the local plugins, so that they become registered. The Plugin Manager can be used to download remote Addons so that they too become registered.
Registered (i.e. local) plugins are loaded by Gramps in the following situations:
- they are automatically loaded at startup. Some plugin types are loaded at startup (e.g., non hidden views), some plugins can have a flag that forces load on startup,
- they are automatically loaded by virtue of the user clicking on a view or requesting a report,
- they are loaded by the user explicitly requesting load in the plugin manager,
- remote plugins are loaded at the same time as they are registered by using Install Addons described below.
The plugin Manager can be used to hide or unhide plugins. Some menus will not display hidden addons, so that the addon cannot be selected. For example, if a Gramplet is hidden, then it will not appear in the "Add a gramplet" context menu which appear when right clicking the background of the Gramplets main tab. However, hiding some addons (such as Relationships or Gramps Views) has no effect and may not even be allowed.
There are three tabs of the Plugin Manager: Registered Plugins, Loaded Plugins, and Install Addons.
Here you see a list of all plugins that Gramps has found. These are the plugins which are part of Gramps, as well as the plugins found in the gramps33/plugins directory within the GRAMPS User Directory. The type of plugin is shown in the first column.
A plugin can be made hidden or unhidden. This is only useful for the User Plugins.
Here you see a list of all plugins that have been attempted to be loaded. Normally, all views (such as the Relationship View) will be loaded, and all gramplets/reports/tools you have used will be loaded automatically.
If there was an error during the loading of a plugin, then the staus will be shown in this tab. Double clicking a row showing a failure opens a dialog showing the error in detail. You can use this to contact the plugin author or the Gramps bug list.
Here you will initially see an empty list. By clicking the "Refresh Addon List" button, Gramps will fetch the listed third-party plugins (known as Addons) listed at 3.3 Addons. You may wish to refresh this list every once in a while to see the latest Addons.
Also, you can enter an Addon's URL or path to a filename in the "Path to addon" to load the Addon.
An addon is a packaged set of files made to run in this version of Gramps. The addon package may end in "addon.tgz" or ".zip". You cannot install a .py file directly, but will need to install the .gpr.py and .py files by having access them in a package. For details on creating an Addon, see Addons Development.
After refreshing the addon list you may also click on a specific Addon listed. This will place the URL of the add in the "Path to addon". Then you can select "Install Addon" to download and install the selected Addon.
You may also select "Install All Addons". This will go through the list and download (or update) all of the listed Addons.
Later if you decide that you do not like an Addon, you can mark it "hidden" and it will no longer show.