mirror of
https://github.com/inventree/inventree-docs.git
synced 2025-04-28 05:36:46 +00:00
Oliver
GitHub
commit
44eb5c621e
@ -16,9 +16,59 @@ Plugins are discovered and loaded when the server is started.
|
||||
!!! info "Enable Plugin Support"
|
||||
To enable custom plugins, plugin support must be activated in the [server configuration](../start/config.md).
|
||||
|
||||
Multiple plugins are supported:
|
||||
### Plugin Base Class
|
||||
|
||||
- [Reporting plugins](./plugins/report.md)
|
||||
- [Barcode plugins](./plugins/barcode.md)
|
||||
- [Action plugins](./plugins/action.md)
|
||||
- [Integration plugins](./plugins/integration.md)
|
||||
Custom plugins must inherit from the [IntegrationPluginBase class](https://github.com/inventree/InvenTree/blob/master/InvenTree/plugin/integration.py). Any plugins installed via the methods outlined above will be "discovered" when the InvenTree server launches.
|
||||
|
||||
### Plugin Options
|
||||
|
||||
Some metadata options can be defined as constants in the plugins class
|
||||
|
||||
``` python
|
||||
PLUGIN_SLUG = None # Used in URLs, setting-names etc. when a unique slug as a reference is needed -> the plugin name is used if not set
|
||||
PLUGIN_TITLE = None # A nice human friendly name for the plugin -> used in titles, as plugin name etc.
|
||||
|
||||
AUTHOR = None # Author of the plugin, git commit information is used if not present
|
||||
PUBLISH_DATE = None # Publishing date of the plugin, git commit information is used if not present
|
||||
VERSION = None # Version of the plugin
|
||||
WEBSITE = None # Website for the plugin, developer etc. -> is shown in plugin overview if set
|
||||
```
|
||||
|
||||
Refer to the [sample plugins](https://github.com/inventree/InvenTree/tree/master/InvenTree/plugin/samples) for further examples.
|
||||
|
||||
### Plugin Config
|
||||
|
||||
A *PluginConfig* database entry will be created for each plugin "discovered" when the server launches. This configuration entry is used to determine if a particular plugin is enabled.
|
||||
|
||||
The configuration entries must be enabled via the [InvenTree admin interface](../settings/admin.md).
|
||||
|
||||
!!! warning "Disabled by Default"
|
||||
Newly discovered plugins are disabled by default, and must be manually enabled by an admin user
|
||||
|
||||
### Plugin Mixins
|
||||
|
||||
Common use cases are covered by pre-supplied modules in the form of mixins (similar to how [django](https://docs.djangoproject.com/en/stable/topics/class-based-views/mixins/) does it). Each mixin enables the integration into a specific area of InvenTree. Sometimes it also enhances the plugin with helper functions to supply often used functions out-of-the-box.
|
||||
|
||||
Supported mixin classes are:
|
||||
|
||||
- [ActionMixin](./plugins/action.md)
|
||||
- [APICallMixin](./plugins/api.md)
|
||||
- [AppMixin](./plugins/app.md)
|
||||
- [BarcodeMixin](./plugins/barcode.md)
|
||||
- [EventMixin](./plugins/event.md)
|
||||
- [NavigationMixin](./plugins/navigation.md)
|
||||
- [ScheduleMixin](./plugins/schedule.md)
|
||||
- [SettingsMixin](./plugins/settings.md)
|
||||
- [UrlsMixin](./plugins/urls.md)
|
||||
|
||||
## Installing a Plugin
|
||||
|
||||
Plugins can either be loaded from paths in the InvenTree install directory or as a plugin installed via pip. We recommend installation via pip as this enables hassle-free upgrades.
|
||||
|
||||
For development new plugins can be placed ina a subdirectory in `src/InvenTree/plugins`. Built-In plugins ship in `src/InvenTree/plugin/builtin`. To achive full unit-testing for all mixins there are some sample implementations in `src/InvenTree/plugin/samples`. These are not loaded in production mode.
|
||||
|
||||
### Plugin Installation File
|
||||
|
||||
Plugins installation can be simplified by providing a list of plugins in a plugin configuration file. This file (by default, 'plugins.txt' in the same directory as the server configuration file) contains a list of required plugin packages.
|
||||
|
||||
Plugins can be installed from this file by simply running the command `invoke plugins`.
|
||||
|
||||
@ -2,7 +2,7 @@
|
||||
title: Action Plugins
|
||||
---
|
||||
|
||||
### Action Plugins
|
||||
## ActionMixin
|
||||
|
||||
Arbitrary "actions" can be called by POSTing data to the `/api/action/` endpoint. The POST request must include the name of the action to be performed, and a matching ActionPlugin plugin must be loaded by the server. Arbitrary data can also be provided to the action plugin via the POST data:
|
||||
|
||||
|
||||
7
docs/extend/plugins/api.md
Normal file
7
docs/extend/plugins/api.md
Normal file
@ -0,0 +1,7 @@
|
||||
---
|
||||
title: Schedule Mixin
|
||||
---
|
||||
|
||||
## APICallMixin
|
||||
|
||||
The APICallMixin class provides basic functionality for integration with an external API.
|
||||
10
docs/extend/plugins/app.md
Normal file
10
docs/extend/plugins/app.md
Normal file
@ -0,0 +1,10 @@
|
||||
---
|
||||
title: App Mixin
|
||||
---
|
||||
|
||||
## AppMixin
|
||||
|
||||
If this mixin is added to a plugin the directory the plugin class is defined in is added to the list of `INSTALLED_APPS` in the InvenTree server configuration.
|
||||
|
||||
!!! warning "Danger Zone"
|
||||
Only use this mixin if you have an understanding of djangos [app system](https://docs.djangoproject.com/en/stable/ref/applications). Plugins with this mixin are deeply integrated into InvenTree and can cause difficult to reproduce or long-running errors. Use the built-in testing functions of django to make sure your code does not cause unwanted behaviour in InvenTree before releasing.
|
||||
@ -1,5 +1,5 @@
|
||||
---
|
||||
title: Barcode Plugins
|
||||
title: Barcode Mixin
|
||||
---
|
||||
|
||||
### Barcode Plugins
|
||||
|
||||
36
docs/extend/plugins/event.md
Normal file
36
docs/extend/plugins/event.md
Normal file
@ -0,0 +1,36 @@
|
||||
---
|
||||
title: Event Mixin
|
||||
---
|
||||
|
||||
## EventMixin
|
||||
|
||||
The `EventMixin` class enables plugins to respond to certain triggered events.
|
||||
|
||||
When a certain (server-side) event occurs, the background worker passes the event information to any plugins which inherit from the `EventMixin` base class.
|
||||
|
||||
Implementing classes must provide a `process_event` function:
|
||||
|
||||
```python
|
||||
class EventPlugin(EventMixin, IntegrationPluginBase):
|
||||
"""
|
||||
A simple example plugin which responds to events on the InvenTree server.
|
||||
|
||||
This example simply prints out the event information.
|
||||
A more complex plugin could respond to specific events however it wanted.
|
||||
"""
|
||||
|
||||
PLUGIN_NAME = "EventPlugin"
|
||||
PLUGIN_SLUG = "event"
|
||||
PLUGIN_TITLE = "Triggered Events"
|
||||
|
||||
def process_event(self, event, *args, **kwargs):
|
||||
print(f"Processing triggered event: '{event}'")
|
||||
```
|
||||
|
||||
### Events
|
||||
|
||||
Events are passed through using a string identifier, e.g. 'build.completed'
|
||||
|
||||
The arguments (and keyword arguments) passed to the receiving function depend entirely on the type of event.
|
||||
|
||||
Implementing a response to a particular event requires a working knowledge of the InvenTree code base, especially related to that event being received.
|
||||
@ -24,12 +24,7 @@ WEBSITE = None # Website for the plugin, developer etc. -> is shown in plugin o
|
||||
|
||||
|
||||
|
||||
#### Installing a Plugin
|
||||
|
||||
Plugins can either be loaded from paths in the InvenTree install directory or as a plugin installed via pip. We recommend installation via pip as this enables hassle-free upgrades.
|
||||
|
||||
For development new plugins can be placed ina a subdirectroy in `src/InvenTree/plugins`. Built-In plugins ship in `src/InvenTree/plugin/builtin`. To achive full unit-testing for all mixins there are some sample implementations in `src/InvenTree/plugin/samples`. These are not loaded in production mode.
|
||||
|
||||
##
|
||||
#### Mixins
|
||||
|
||||
Common use cases are covered by pre-supplied modules in the form of mixins (similar to how [django](https://docs.djangoproject.com/en/stable/topics/class-based-views/mixins/) does it). Each mixin enables the integration into a specific area of InvenTree. Sometimes it also enhances the plugin with helper functions to supply often used functions out-of-the-box.
|
||||
|
||||
25
docs/extend/plugins/navigation.md
Normal file
25
docs/extend/plugins/navigation.md
Normal file
@ -0,0 +1,25 @@
|
||||
---
|
||||
title: Navigation Mixin
|
||||
---
|
||||
|
||||
## NavigationMixin
|
||||
|
||||
Use the class constant `NAVIGATION` for a array of links that should be added to InvenTrees navigation header.
|
||||
The array must contain at least one dict that at least define a name and a link for each element. The link must be formatted for a URL pattern name lookup - links to external sites are not possible directly. The optional icon must be a class reference to an icon (InvenTree ships with fontawesome 4 by default).
|
||||
|
||||
``` python
|
||||
class MyNavigationPlugin(NavigationMixin, IntegrationPluginBase):
|
||||
|
||||
PLUGIN_NAME = "NavigationPlugin"
|
||||
|
||||
NAVIGATION = [
|
||||
{'name': 'SampleIntegration', 'link': 'plugin:sample:hi', 'icon': 'fas fa-box'},
|
||||
]
|
||||
|
||||
NAVIGATION_TAB_NAME = "Sample Nav"
|
||||
NAVIGATION_TAB_ICON = 'fas fa-plus'
|
||||
```
|
||||
|
||||
The optional class constants `NAVIGATION_TAB_NAME` and `NAVIGATION_TAB_ICON` can be used to change the name and icon for the parent navigation node.
|
||||
|
||||
|
||||
@ -1,10 +0,0 @@
|
||||
---
|
||||
title: Reporting Plugins
|
||||
---
|
||||
|
||||
### Reporting Plugins
|
||||
|
||||
InvenTree can generate customized reports (for example stocktake information, packing lists, acceptance test reports, etc).
|
||||
|
||||
!!! missing "TODO"
|
||||
Include more information here on reporting plugins
|
||||
52
docs/extend/plugins/schedule.md
Normal file
52
docs/extend/plugins/schedule.md
Normal file
@ -0,0 +1,52 @@
|
||||
---
|
||||
title: Schedule Mixin
|
||||
---
|
||||
|
||||
## ScheduleMixin
|
||||
|
||||
The ScheduleMixin class provides a plugin with the ability to call functions at regular intervals.
|
||||
|
||||
- Functions are registered with the InvenTree worker which runs as a background process.
|
||||
- Scheduled functions do not accept any arguments
|
||||
- Plugin member functions can be called
|
||||
- Global functions can be specified using dotted notation
|
||||
|
||||
### Example
|
||||
|
||||
An example of a plugin which supports scheduled tasks:
|
||||
|
||||
```python
|
||||
class ScheduledTaskPlugin(ScheduleMixin, SettingsMixin, IntegrationPluginBase):
|
||||
"""
|
||||
Sample plugin which runs a scheduled task, and provides user configuration.
|
||||
"""
|
||||
|
||||
PLUGIN_NAME = "Scheduled Tasks"
|
||||
PLUGIN_SLUG = 'schedule'
|
||||
|
||||
SCHEDULED_TASKS = {
|
||||
'global': {
|
||||
'func': 'some_module.function',
|
||||
'schedule': 'H', # Run every hour
|
||||
},
|
||||
'member': {
|
||||
'func': 'foo',
|
||||
'schedule': 'I', # Minutes
|
||||
'minutes': 15,
|
||||
},
|
||||
}
|
||||
|
||||
SETTINGS = {
|
||||
'SECRET': {
|
||||
'name': 'A secret',
|
||||
'description': 'User configurable value',
|
||||
},
|
||||
}
|
||||
|
||||
def foo(self):
|
||||
"""
|
||||
This function runs every 15 minutes
|
||||
"""
|
||||
secret_value = self.get_setting('SECRET')
|
||||
print(f"foo - SECRET = {secret_value})
|
||||
```
|
||||
48
docs/extend/plugins/settings.md
Normal file
48
docs/extend/plugins/settings.md
Normal file
@ -0,0 +1,48 @@
|
||||
---
|
||||
title: Settings Mixin
|
||||
---
|
||||
|
||||
## SettingsMixin
|
||||
|
||||
The *SettingsMixin* allows the plugin to save and load persistent settings to the database.
|
||||
|
||||
- Plugin settings are stored against the individual plugin, and thus do not have to be unique
|
||||
- Plugin settings are stored using a "key:value" pair
|
||||
|
||||
Use the class constant `SETTINGS` for a dict of settings that should be added as global database settings.
|
||||
|
||||
The dict must be formatted similar to the following sample. Take a look at the settings defined in `InvenTree.common.models.InvenTreeSetting` for all possible parameters.
|
||||
|
||||
|
||||
``` python
|
||||
class PluginWithSettings(SettingsMixin, IntegrationPluginBase):
|
||||
|
||||
PLUGIN_NAME = "PluginWithSettings"
|
||||
|
||||
SETTINGS = {
|
||||
'API_ENABLE': {
|
||||
'name': 'API Functionality',
|
||||
'description': 'Enable remote API queries',
|
||||
'validator': bool,
|
||||
'default': True,
|
||||
},
|
||||
'API_KEY': {
|
||||
'name': 'API Key',
|
||||
'description': 'Security key for accessing remote API',
|
||||
'default': '',
|
||||
},
|
||||
'API_URL': {
|
||||
'name': _('API URL'),
|
||||
'description': _('Base URL for remote server'),
|
||||
'default': 'http://remote.url/api',
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
This mixin defines the helper functions `plugin.get_setting` and `plugin.set_seting` to access all plugin specific settings:
|
||||
|
||||
```python
|
||||
api_url = self.get_setting('API_URL')
|
||||
```
|
||||
|
||||
|
||||
23
docs/extend/plugins/urls.md
Normal file
23
docs/extend/plugins/urls.md
Normal file
@ -0,0 +1,23 @@
|
||||
---
|
||||
title: URLs Mixin
|
||||
---
|
||||
|
||||
## UrlsMixin
|
||||
|
||||
Use the class constant `URLS` for a array of URLs that should be added to InvenTrees URL paths or override the `plugin.setup_urls` function.
|
||||
|
||||
The array has to contain valid URL patterns as defined in the [django documentation](https://docs.djangoproject.com/en/stable/topics/http/urls/).
|
||||
|
||||
``` python
|
||||
class MyUrlsPlugin(URLsMixin, IntegrationPluginBase):
|
||||
|
||||
PLUGIN_NAME = "UrlsMixin"
|
||||
|
||||
URLS = [
|
||||
url(r'increase/(?P<location>\d+)/(?P<pk>\d+)/', self.view_increase, name='increase-level'),
|
||||
]
|
||||
```
|
||||
|
||||
The URLs get exposed under `/plugin/{plugin.slug}/*` and get exposed to the template engine with the prefix `plugin:{plugin.slug}:` (for usage with the [url tag](https://docs.djangoproject.com/en/stable/ref/templates/builtins/#url)).
|
||||
|
||||
|
||||
13
mkdocs.yml
13
mkdocs.yml
@ -111,10 +111,15 @@ nav:
|
||||
- Python Interface: extend/python.md
|
||||
- Plugins:
|
||||
- Overview: extend/plugins.md
|
||||
- Reporting: extend/plugins/report.md
|
||||
- Barcode: extend/plugins/barcode.md
|
||||
- Action: extend/plugins/action.md
|
||||
- Integration: extend/plugins/integration.md
|
||||
- Action Mixin: extend/plugins/action.md
|
||||
- API Mixin: extend/plugins/api.md
|
||||
- App Mixin: extend/plugins/app.md
|
||||
- Barcode Mixin: extend/plugins/barcode.md
|
||||
- Event Mixin: extend/plugins/event.md
|
||||
- Navigation Mixin: extend/plugins/navigation.md
|
||||
- Schedule Mixin: extend/plugins/schedule.md
|
||||
- Settings Mixin: extend/plugins/settings.md
|
||||
- URL Mixin: extend/plugins/urls.md
|
||||
- Themes: extend/themes.md
|
||||
- Third-Party: extend/integrate.md
|
||||
- App:
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user