plugin_development.md 3.03 KB
Newer Older
inso's avatar
inso committed
1 2 3 4
# Developing a plugin for sakia

## Prepare dev environment

inso's avatar
inso committed
5
Follow the doc file [Install for developers](https://github.com/duniter/sakia/blob/dev/doc/install_for_developers.md).
inso's avatar
inso committed
6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43
You can use the same pyenv environment to develop your plugin.

## Plugin structure

The plugin source code should follow the structure below :

```
/
   [plugin_pkg_name]/
      images/                # The directory containing images used in the widget
         images.qrc          # The qt resources .qrc file describing available images
         [image1.png]        # The list of images
         [image2.png]
      __init__.py            # The __init__ file of the plugin
      [script_1.py]          # Some scripts imported in the __init__ file
      [script_2.py]
      [ui_file.ui]           # ui files designed using QtDesigner
```

The `__init__.py` file must set the following global constants :

```python
PLUGIN_NAME = "Title of the plugin"
PLUGIN_DESCRIPTION = "Description of the plugin"
PLUGIN_VERSION = "0.1"
```

The function below must be present in the `__init__.py` file to initialize the plugin on Sakia startup :

```python

def plugin_exec(app, main_window):
    """
    :param sakia.app.Application app:
    :param sakia.gui.main_window.controller.MainWindowController main_window:
    """
    # Place your init code here
    pass
inso's avatar
inso committed
44
```
inso's avatar
inso committed
45 46 47 48 49 50 51 52

## Building your plugin

To build the plugin, you need :

### To generate resources (images, qrc, ...)

Generating resources uses [pyrcc5](http://pyqt.sourceforge.net/Docs/PyQt5/resources.html).
inso's avatar
inso committed
53 54
Generating designer ui files uses [pyuic5](http://pyqt.sourceforge.net/Docs/PyQt5/designer.html).

inso's avatar
inso committed
55 56 57 58 59
To help you generate your resources, you should copy the `gen_resources.py` file from sakia sources and configure the
 variable `gen_resources`. Replace `'src'` by the name of your plugin package.

### To import your resources in your code

inso's avatar
inso committed
60
The generation of the resources builds the following python files :
inso's avatar
inso committed
61 62 63 64 65 66 67 68

 - `filename.ui` -> `filename_uic.py`
 - `filename.qrc` -> `filename_rc.py`

The `filename_uic.py` file should be imported in the file using the designed widget. See the
[dialog of the example plugin](https://github.com/Insoleet/sakia-plugin-example/blob/master/plugin_example/main_dialog.py)

The `filename_rc.py` file should be imported in the `__init__.py` file, on the last line. See the
inso's avatar
inso committed
69
[\__init__.py of the example plugin](https://github.com/Insoleet/sakia-plugin-example/blob/master/plugin_example/__init__.py#L28)
inso's avatar
inso committed
70 71 72 73 74 75 76 77 78 79 80 81 82 83 84

### To generate your plugin

To generate your plugin, you must zip everything (generated resources) in a zip file respecting the structure below :

```
[plugin_name].zip\
    [plugin_name]\
        __init__.py
        [generated files...]
```

The [setup.py](https://github.com/Insoleet/sakia-plugin-example/blob/master/setup.py) file from the
example plugin is available to help you generate correctly the plugin.

inso's avatar
inso committed
85 86 87 88
### To test your plugin

To test your plugin, you need to run sakia with the parameter `--withplugin [path to zip file]`. The plugin will
be loaded automatically on startup but won't be installed to user profile directory.