Plugins

Importante

Plugins is an experimental feature! The API may change.

We welcome you to try and provide your feedback.

Plugins allow you to extend the functionality of Gaphor beyond the features provided in the standard distributions. In particular, plugins can be helpful if you install the binary distributions available on the download page.

Gaphor can be extended via entry points in several ways:

  1. Application (global) services (gaphor.appservices)

  2. Session specific services (gaphor.services)

  3. Modeling languages (gaphor.modelinglanguages)

  4. (Sub)command line parsers (gaphor.argparsers)

  5. Indirectly loaded modules (gaphor.modules), mainly for UI components

The default location for plugins is $HOME/.local/gaphor/plugins-2 ($USER/.local/gaphor/plugins-2 on Windows). This location can be changed by setting the environment variable GAPHOR_PLUGIN_PATH and point to a directory.

Install a plugin

At this moment Gaphor does not have functionality bundled to install and maintain plugins. To install a plugin, use pip from a Python installation on your computer. On macOS and Linux, that should be easy, on Windows you may need to install Python separately from python.org or the Windows Store.

Importante

  1. Since plugins are installed with your system Python version, it’s important that plugins are pure Python and do not contain compiled C code.

  2. If you use Gaphor installed as Flatpak, you need to grant Gaphor access to user files (filesystem=home), so Gaphor can find files in your .local folder. You can use FlatSeal to change permissions of Flatpaks.

For example: to install the Hello World plugin on Linux and macOS, enter:

pip install --target $HOME/.local/gaphor/plugins-2 git+https://github.com/gaphor/gaphor_plugin_helloworld.git

Then start Gaphor as you normally would. A new Hello World entry has been added to the tools menu (Menu icon → Tools → Hello World).

Create your own plugin

If you want to write a plugin yourself, you can familiarize yourself with Gaphor’s design principles, service oriented architecture, and event driven framework.

Ejemplo de plugin

You can have a look at the Hello World plugin available on GitHub for an example of how to create your own plugin.

The pyproject.toml file contains a plugin:

[tool.poetry.plugins."gaphor.services"]
"helloworld" = "gaphor_helloworld_plugin:HelloWorldPlugin"

This refers to the class HelloWorldPlugin in package/module gaphor_plugins_helloworld.

Aquí tiene una versión reducida del plugin hello world:

from gaphor.abc import Service, ActionProvider
from gaphor.core import _, action

class HelloWorldPlugin(Service, ActionProvider):     # 1.

    def __init__(self, tools_menu):                  # 2.
        self.tools_menu = tools_menu
        tools_menu.add_actions(self)                 # 3.

    def shutdown(self):                              # 4.
        self.tools_menu.remove_actions(self)

    @action(                                         # 5.
        name="helloworld",
        label=_("Hello world"),
        tooltip=_("Every application…"),
    )
    def helloworld_action(self):
        main_window = self.main_window
        ...  # gtk code left out

  1. Como se ha dicho antes, un plugin debe implementar la interfaz Service. También implementa ActionProvider, diciendo que tiene algunas acciones a realizar por el usuario.

  2. La entrada de menú formará parte del menú de extensión «Herramientas». Este punto de extensión se crea como un servicio. También se pueden pasar otros servicios como dependencias. Los servicios pueden obtener referencias a otros servicios definiéndolos como argumentos del constructor.

  3. Se registran todas las acciones definidas en este servicio.

  4. Cada servicio tiene un método shutdown(). Esto permite al servicio realizar alguna limpieza cuando se apaga.

  5. La acción que puede ser invocada. La acción está definida y será recogida por el método add_actions() (ver 3.)

Plugin Development FAQ

How do I acceess gaphor services in my plugin?

Gaphor’s services can be made accessible by listing the service names in the init function of your plugin class. This also requires including Service as a base class. In the HelloWorldPlugin example, the tools_menu service is included.

A more complete description of this approach can be found in the Service Oriented Architecture documentation page.

Community Developed Plugins

Gaphor_Tools

What does it do?

Import and export of SysML requirements and notes to Excel and Confluence. It’s currently at the proof-of-concept stage of development, but does allow a requirements table to be exported, then edited and imported bringing in all the changes to the model, similarly for element notes.

Where can I get it?

From this BitBucket Repo