87 lines
2.9 KiB
Markdown
87 lines
2.9 KiB
Markdown
# Plugin Development Guide
|
|
|
|
This guide explains how to create new plugins for the Superset Tools application.
|
|
|
|
## 1. Plugin Structure
|
|
|
|
A plugin is a single Python file located in the `backend/src/plugins/` directory. Each plugin file must contain a class that inherits from `PluginBase`.
|
|
|
|
## 2. Implementing `PluginBase`
|
|
|
|
The `PluginBase` class is an abstract base class that defines the interface for all plugins. You must implement the following properties and methods:
|
|
|
|
- **`id`**: A unique string identifier for your plugin (e.g., `"my-cool-plugin"`).
|
|
- **`name`**: A human-readable name for your plugin (e.g., `"My Cool Plugin"`).
|
|
- **`description`**: A brief description of what your plugin does.
|
|
- **`version`**: The version of your plugin (e.g., `"1.0.0"`).
|
|
- **`get_schema()`**: A method that returns a JSON schema dictionary defining the input parameters for your plugin. This schema is used to automatically generate a form in the frontend.
|
|
- **`execute(params: Dict[str, Any])`**: An `async` method that contains the main logic of your plugin. The `params` argument is a dictionary containing the input data from the user, validated against the schema you defined.
|
|
|
|
## 3. Example Plugin
|
|
|
|
Here is an example of a simple "Hello World" plugin:
|
|
|
|
```python
|
|
# backend/src/plugins/hello.py
|
|
# [DEF:HelloWorldPlugin:Plugin]
|
|
# @SEMANTICS: hello, world, example, plugin
|
|
# @PURPOSE: A simple "Hello World" plugin example.
|
|
# @LAYER: Domain (Plugin)
|
|
# @RELATION: Inherits from PluginBase
|
|
# @PUBLIC_API: execute
|
|
|
|
from typing import Dict, Any
|
|
from ..core.plugin_base import PluginBase
|
|
|
|
class HelloWorldPlugin(PluginBase):
|
|
@property
|
|
def id(self) -> str:
|
|
return "hello-world"
|
|
|
|
@property
|
|
def name(self) -> str:
|
|
return "Hello World"
|
|
|
|
@property
|
|
def description(self) -> str:
|
|
return "A simple plugin that prints a greeting."
|
|
|
|
@property
|
|
def version(self) -> str:
|
|
return "1.0.0"
|
|
|
|
def get_schema(self) -> Dict[str, Any]:
|
|
return {
|
|
"type": "object",
|
|
"properties": {
|
|
"name": {
|
|
"type": "string",
|
|
"title": "Name",
|
|
"description": "The name to greet.",
|
|
"default": "World",
|
|
}
|
|
},
|
|
"required": ["name"],
|
|
}
|
|
|
|
async def execute(self, params: Dict[str, Any]):
|
|
name = params["name"]
|
|
print(f"Hello, {name}!")
|
|
```
|
|
|
|
## 4. Logging
|
|
|
|
You can use the global logger instance to log messages from your plugin. The logger is available in the `superset_tool.utils.logger` module.
|
|
|
|
```python
|
|
from superset_tool.utils.logger import SupersetLogger
|
|
|
|
logger = SupersetLogger()
|
|
|
|
async def execute(self, params: Dict[str, Any]):
|
|
logger.info("My plugin is running!")
|
|
```
|
|
|
|
## 5. Testing
|
|
|
|
To test your plugin, simply run the application and navigate to the web UI. Your plugin should appear in the list of available tools. |