codevis/doc/plugins.md

0001 Plugins
0002 ===
0003
0004 Codevis application supports plugins. It is possible to create plugins in C++, Python or mix the two languages.
0005
0006 The plugin system works as follows: There's a set of places in the application code that call user-definable functions.
0007  Those functions are called "Hooks". Each hook receives a pointer to a "handler" that'll be provided by the application.
0008  So a "hook" is a "place" _where_ the function will be called and the handler is _what_ can be called back to change
0009  application behavior.
0010
0011 All hooks are defined in the [hooks.py](../lvtplg/hooks.py) file. All handlers are defined in one of the handler files
0012 in the [handlers.py](../lvtplg/handlers.py) file. Handlers may return application data structures, such as an "Entity".
0013 Those are available in the [plugin data types file](../lvtplg/ct_lvtplg_plugindatatypes.h).
0014
0015 In order for the application to recognize the plugins, they need to be in a specific place and they need to have a
0016 specific set of files. This is the file structure each plugin must have:
0017
0018 ```
0019 $plugin_name/
0020 + $plugin_name.[py|so]
0021 + metadata.json
0022 + README.md
0023 ```
0024
0025 Where `$plugin_name` is the plugin's name. `metadata.json` file follows the [kcoreaddons](https://api.kde.org/frameworks/kcoreaddons/html/)
0026 specification (There's an example below). And the `README.md` file should contain a brief description, and
0027 possibly examples on how to use the plugin.
0028
0029 The `$plugin_name` folder must be copied to one of those paths, so that the application can find the plugin:
0030
0031 - `$user_home/lks-plugins/` (Preferred for local development)
0032 - `$app_installation_path/lks-plugins/` (Used for plugins that are bundled with the app)
0033 - `$app_local_data/plugins/` (Used for downloaded plugins)
0034
0035 There are a few working examples in the [plugins folder](../plugins/). There's also some [plugins for integration test](../lvtplg/testplugins/)
0036 that may be useful as simple examples. But just to give the  reader a more step-by-step explanation, this section will show a working plugin written in Python.
0037 There's also a [python template plugin](../plugins/python_template_plugin/) that may be used as starting point.
0038
0039 **Step 1**: Create the following folder structure inside `$user_home/lks-plugins/` (example: `/home/tarcisio/lks-plugins/`):
0040
0041 ```
0042 myfirstplugin/
0043 + myfirstplugin.py
0044 + metadata.json
0045 + README.md
0046 ```
0047
0048 **Step 2**: Populate the `metadata.json` file with the following contents:
0049
0050 ```
0051  {
0052   "KPlugin": {
0053      "Name": "My first plugin",
0054      "Description": "Example plugin",
0055      "Icon": "none",
0056      "Authors": [ { "Name": "YourName", "Email": "YourEmail" } ],
0057      "Category": "Codevis Plugins",
0058      "EnabledByDefault": true,
0059      "License": "YourLicense",
0060      "Id": "myfirstplugin",
0061      "Version": "0.1",
0062      "Website": "YourPluginWebsite"
0063   }
0064 }
0065 ```
0066
0067 **Step 3**: Populate the `myfirstplugin.py` file with the actual plugin code:
0068
0069 ```python
0070 import pyLksPlugin as plg # Contains Codevis data structures
0071
0072 def hookSetupPlugin(handler):
0073 # This will be executed once when the application starts
0074 print("Hello world from Python plugin!")
0075
0076
0077 def hookTeardownPlugin(handler):
0078 # This will be executed once when the application closes
0079 print("Okay then. Bye!")
0080 ```
0081
0082 **Step 4**: Save all files and start the Codevis application using your terminal. You should see the messages in the
0083 console.
0084
0085 Codevis comes with a builtin plugin editor that can be used for editing the plugins. To access it just click on
0086 `View > Plugin Editor`.