mirror of
https://github.com/inventree/inventree-docs.git
synced 2025-04-27 21:26:43 +00:00
Plugin external dir (#322)
* Additional information on plugin configuration options * Better information on plugin installation * Update label printing docs * Rearrange plugin menu * More menu tweaks * Fix links to app images
This commit is contained in:
Oliver
GitHub
parent
2e99477478
commit
3def121be2
@ -154,11 +154,11 @@ This barcode can then be used to track the stock item.
|
||||
|
||||
If the server supports [label printing plugins](../extend/plugins/label.md), then an option to print a label for the selected stock item:
|
||||
|
||||
{% with id="label_print_1", url="app/stock_print_label_1.png", description="Print label via plugin" %}
|
||||
{% with id="label_print_1", url="stock_print_label_1.png", description="Print label via plugin" %}
|
||||
{% include 'app_img.html' %}
|
||||
{% endwith %}
|
||||
|
||||
{% with id="label_print_2", url="app/stock_print_label_2", description="Print label via plugin" %}
|
||||
{% with id="label_print_2", url="stock_print_label_2.png", description="Print label via plugin" %}
|
||||
{% include 'app_img.html' %}
|
||||
{% endwith %}
|
||||
|
||||
|
||||
@ -104,25 +104,3 @@ Supported mixin classes are:
|
||||
- [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.
|
||||
|
||||
### Builtin 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.
|
||||
|
||||
### Local Directory
|
||||
|
||||
Custom plugins can be placed in the `src/InvenTree/plugins/` directory, where they will be automatically discovered. This can be useful for developing and testing plugins, but can prove more difficult in production (e.g. when using Docker).
|
||||
|
||||
### Plugin Installation File (PIP)
|
||||
|
||||
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 then installed from this file by simply running the command `invoke plugins`.
|
||||
|
||||
!!! success "Auto Update"
|
||||
When the server installation is updated via the `invoke update` command, the plugins (as specified in *plugins.txt*) will also be updated automatically.
|
||||
|
||||
|
||||
51
docs/extend/plugins/install.md
Normal file
51
docs/extend/plugins/install.md
Normal file
@ -0,0 +1,51 @@
|
||||
---
|
||||
title: Installing Plugins
|
||||
---
|
||||
|
||||
|
||||
## 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.
|
||||
|
||||
### Plugin Installation File (PIP)
|
||||
|
||||
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 then installed from this file by simply running the command `invoke plugins`.
|
||||
|
||||
Installation via PIP (using the *plugins.txt* file) provides a number of advantages:
|
||||
|
||||
- Any required secondary packages are installed automatically
|
||||
- You can update plugins simply by specifying version numbers in *plugins.txt*
|
||||
- Migrating plugins between systems is simplified
|
||||
- You can install plugins via any source supported by PIP
|
||||
|
||||
!!! success "Auto Update"
|
||||
When the server installation is updated via the `invoke update` command, the plugins (as specified in *plugins.txt*) will also be updated automatically.
|
||||
|
||||
|
||||
### Builtin 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`.
|
||||
|
||||
!!! info "Debug Only"
|
||||
The sample plugins are not loaded in production mode.
|
||||
|
||||
### Local Directory
|
||||
|
||||
Custom plugins can be placed in the `src/InvenTree/plugins/` directory, where they will be automatically discovered. This can be useful for developing and testing plugins, but can prove more difficult in production (e.g. when using Docker).
|
||||
|
||||
!!! info "Git Tracking"
|
||||
The `src/InvenTree/plugins/` directory is excluded from Git version tracking - any plugin files here will be hidden from Git
|
||||
|
||||
!!! warning "Not Recommended For Production"
|
||||
Loading plugins via the local *plugins* directory is not recommended for production. If you cannot use PIP installation (above), specify a custom plugin directory (below).
|
||||
|
||||
### Custom Directory
|
||||
|
||||
If you wish to install plugins from local source, rather than PIP, it is better to place your plugins in a directory outside the InvenTree source directory.
|
||||
|
||||
To achieve this, set the `INVENTREE_PLUGIN_DIR` environment variable to the directory where locally sourced plugins are located. Refer to the [configuration options](../../start/config.md#plugin-options) for further information.
|
||||
|
||||
!!! info "Docker"
|
||||
When running InvenTree in docker, a *plugins* directory is automatically created in the mounted data volume. Any plugins can be placed there, and will be automatically loaded when the server is started.
|
||||
@ -38,18 +38,29 @@ class MyLabelPrinter(LabelPrintingMixin, InvenTreePlugin):
|
||||
SLUG = "mylabel"
|
||||
TITLE = "A dummy printer"
|
||||
|
||||
def print_label(self, label, **kwargs):
|
||||
def print_label(self, **kwargs):
|
||||
"""
|
||||
Send the label to the printer
|
||||
|
||||
Arguments:
|
||||
label: A PIL (pillow) Image file
|
||||
kwargs:
|
||||
pdf_data: An in-memory PDF file of the label
|
||||
png_file: An in-memory PIL (pillow) Image file of the label
|
||||
filename: The filename of the printed label (if applicable)
|
||||
label_instance: The Label model instance
|
||||
width: width of the label (in mm)
|
||||
height: height of the label (in mm)
|
||||
user: The user who printed this label
|
||||
"""
|
||||
|
||||
width = kwargs['width']
|
||||
height = kwargs['height']
|
||||
|
||||
printer_backend.print(label, w=width, h=height)
|
||||
# This dummy printer supports printing of raw image files
|
||||
printer_backend.print(png_file, w=width, h=height)
|
||||
```
|
||||
|
||||
### Available Data
|
||||
|
||||
The *label* data are supplied to the plugin in both `PDF` and `PNG` formats. This provides compatibility with a great range of label printers "out of the box". Conversion to other formats, if required, is left as an exercise for the plugin developer.
|
||||
|
||||
Other arguments provided to the `print_label` function are documented in the code sample above.
|
||||
|
||||
@ -46,7 +46,6 @@ The following basic options are available:
|
||||
| --- | --- | --- | --- |
|
||||
| INVENTREE_DEBUG | debug | Enable debug mode | True |
|
||||
| INVENTREE_LOG_LEVEL | log_level | Set level of logging to terminal | WARNING |
|
||||
| INVENTREE_PLUGINS_ENABLED | plugins_enabled | Enable plugin support | False |
|
||||
|
||||
## Administrator Account
|
||||
|
||||
@ -181,6 +180,16 @@ If you want to remove the InvenTree branding as far as possible from your end-us
|
||||
!!! info "Custom Logo Path"
|
||||
The provided *custom logo* path must be specified *relative* to the location of thr `/media/` directory.
|
||||
|
||||
## Plugin Options
|
||||
|
||||
The following [plugin](../extend/plugins.md) configuration options are available:
|
||||
|
||||
| Environment Variable | Settings File | Description | Default |
|
||||
| --- | --- | --- | --- |
|
||||
| INVENTREE_PLUGINS_ENABLED | plugins_enabled | Enable plugin support | False |
|
||||
| INVENTREE_PLUGIN_FILE | *N/A* | Location of plugin installation file | `./InvenTree/plugins.txt` |
|
||||
| INVENTREE_PLUGIN_DIR | *N/A* | Location of external plugin directory | *Not set* |
|
||||
|
||||
## Other Options
|
||||
|
||||
### Middleware
|
||||
|
||||
@ -127,7 +127,9 @@ nav:
|
||||
- Extend:
|
||||
- Plugins:
|
||||
- Overview: extend/plugins.md
|
||||
- How To: extend/how_to_plugin.md
|
||||
- Installation: extend/plugins/install.md
|
||||
- Developing a Plugin: extend/how_to_plugin.md
|
||||
- Plugin Mixins:
|
||||
- Action Mixin: extend/plugins/action.md
|
||||
- API Mixin: extend/plugins/api.md
|
||||
- App Mixin: extend/plugins/app.md
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user