inventree/InvenTree
2
0
Fork 0
mirror of https://github.com/inventree/InvenTree.git synced 2025-06-16 03:55:41 +00:00
Code Activity

[Plugin] Plugin context (#9439)

Browse Source 
* Pass more stuff to window

* Expose form functions to plugin context

* Breaking: Render plugin component in context tree

- Required due to createRoot function
- Adds necessary context providers

* Fix context

* Provide MantineThemeContext

* Bundle mantine/core

* Hack for useNavigate within ApiForm

- Errors out if called within plugin context
- Workaround to catch the error

* Update build cmd

* Define config for building "Library" mode

* Update package.json

* Add basic index file

* Factor out ApiEndpoints

* factor out ModelType

* Factor out role enums

* Further refactoring

* More refactoring

* Cleanup

* Expose apiUrl function

* Add instance data to plugin context type def

* Tweaks for loading plugin components

- LanguageContext must be on the inside

* Tweak StylishText

* Externalize notifications system

* Update lingui config

* Add functions for checking plugin interface version

* Extract package version at build time

* Enhance version checking

* Revert variable name change

* Public package

* Add README.md

* adjust packge name

* Adjust name to include org

* Update project files

* Add basic changelog info

* Refactoring to expose URL functions

* Refactor navigation functions

* Update package and README

* Improve navigateToLink function

* Refactor stylish text

- Move into ./lib
- Do not require user state

* Revert changes

- StylishText throws error in plugin
- Low priority, can work out later

* expose function to refresh page index

* Provide RemoteComponent with a method to reload itself

* Bump version

* Cleanup tests

* Prevent duplicate --emptyOutDir arg

* Tweak playwright tests

* Expose role and permission enums

* Fix imports

* Updated docs

* Fix spelling, typos, etc

* Include more package version information

* Expose more version context

* Cleanup

* Probably don't need hooks

* Fix links

* Docs updates

* Fix links
This commit is contained in:
Oliver
2025-04-16 00:30:34 +10:00
committed by GitHub
parent f3d804d5ea
commit 5e7e258289
276 changed files with 2797 additions and 1854 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
docs/docs/extend/how_to_plugin.md
View File

@ -18,7 +18,8 @@ If you add a lot of code (over ~1000 LOC) maybe split it into multiple plugins t
Great. Now please read the [plugin documentation](./plugins.md) to get an overview of the architecture. It is rather short as a the (builtin) mixins come with extensive docstrings.
### Pick your building blocks
Consider the usecase for your plugin and define the exact function of the plugin, maybe write it down in a short readme. Then pick the mixins you need (they help reduce custom code and keep the system reliable if internal calls change).
Consider the use-case for your plugin and define the exact function of the plugin, maybe write it down in a short readme. Then pick the mixins you need (they help reduce custom code and keep the system reliable if internal calls change).
- Is it just a simple REST-endpoint that runs a function ([ActionMixin](./plugins/action.md)) or a parser for a custom barcode format ([BarcodeMixin](./plugins/barcode.md))?
- How does the user interact with the plugin? Is it a UI separate from the main InvenTree UI ([UrlsMixin](./plugins/urls.md)), does it need multiple pages with navigation-links ([NavigationMixin](./plugins/navigation.md)).
@ -30,7 +31,7 @@ Consider the usecase for your plugin and define the exact function of the plugin
- Do you need the full power of Django with custom models and all the complexity that comes with that – welcome to the danger zone and [AppMixin](./plugins/app.md). The plugin will be treated as a app by django and can maybe rack the whole instance.
### Define the metadata
Do not forget to [declare the metadata](./plugins.md#plugin-options) for your plugin, those will be used in the settings. At least provide a weblink so users can file issues / reach you.
Do not forget to [declare the metadata](./plugins.md#plugin-options) for your plugin, those will be used in the settings. At least provide a web link so users can file issues / reach you.
### Development guidelines
If you want to make your life easier, try to follow these guidelines; break where it makes sense for your use case.
@ -139,9 +140,7 @@ from plugin.mixins import ActionMixin
class SampleActionPlugin(ActionMixin, InvenTreePlugin):
"""
Use docstrings for everything... pls
"""
"""Use docstrings for everything."""
NAME = "SampleActionPlugin"
ACTION_NAME = "sample"

38
docs/docs/extend/integrate.md
View File

@ -4,40 +4,8 @@ title: Third Party Integrations
## Third Party Integrations
A list of known third-party InvenTree extensions is provided below. If you have an extension that should be listed here, contact the InvenTree team on [GitHub](https://github.com/inventree/).
A list of known third-party InvenTree extensions is provided [on our website](https://inventree.org/extend/integrate/) If you have an extension that should be listed here, contact the InvenTree team on [GitHub](https://github.com/inventree/).
### Ki-nTree
## Available Plugins
[Ki-nTree](https://github.com/sparkmicro/Ki-nTree/) is a fantastic tool for automated creation of [KiCad](https://www.kicad.org/) library parts, with direct integration with InvenTree.
### PK2InvenTree
[PK2InvenTree](https://github.com/rgilham/PK2InvenTree) is an open-source tool for migrating an existing [PartKeepr](https://github.com/partkeepr/PartKeepr) database to InvenTree.
### Digikey-Inventree-Integration
[Digikey-Inventree-Integration](https://github.com/EUdds/Digikey-Inventree-Integration) is a simple project that takes a digikey part number to creates a part in InvenTree.
### F360-InvenTree
[F360-InvenTree](https://github.com/matmair/F360-InvenTree/) is a tool for creating links between Autodesk Fusion 360 components and InvenTree parts.
Still under heavy development.
### DigitalOcean droplet
[InvenTree droplet](https://inventree.org/digitalocean) is a 1-click solution to deploy InvenTree in the cloud with DigitalOcean. You still have to administer and update your instance.
The source code for this droplet can be found in [inventree_droplet](https://github.com/invenhost/inventree_droplet).
### InvenTree zebra plugin
[InvenTree zebra plugin](https://github.com/SergeoLacruz/inventree-zebra-plugin) is a plugin to print labels with zebra printers.
Currently only the GK420T printer is supported.
### InvenTree Apprise
[InvenTree Apprise](https://github.com/matmair/inventree-apprise) is a plugin to send notifications via Apprise. This enables a wide variety of targets.
## First party plugins
### InvenTree brother plugin
[InvenTree brother plugin](https://github.com/inventree/inventree-brother-plugin) is a plugin to print labels with brother Q series printers.
Refer to the [InvenTree website](https://inventree.org/plugins.html) for a (non exhaustive) list of plugins that are available for InvenTree. This includes both official and third-party plugins.

9
docs/docs/extend/plugins.md
View File

@ -4,7 +4,7 @@ title: Plugins
## InvenTree Plugin Architecture
The InvenTree server code supports an extensible plugin architecture, allowing custom plugins to be integrated directly into the database server. This allows development of complex behaviours which are decoupled from core InvenTree code.
The InvenTree server code supports an extensible plugin architecture, allowing custom plugins to be integrated directly into the database server. This allows development of complex behaviors which are decoupled from core InvenTree code.
Plugins can be added from multiple sources:
@ -35,8 +35,8 @@ create-inventree-plugin
Custom plugins must inherit from the [InvenTreePlugin class]({{ sourcefile("src/backend/InvenTree/plugin/plugin.py") }}). Any plugins installed via the methods outlined above will be "discovered" when the InvenTree server launches.
!!! warning "Namechange"
The name of the base class was changed with `0.7.0` from `IntegrationPluginBase` to `InvenTreePlugin`. While the old name is still available till `0.8.0` we strongly suggest upgrading your plugins. Deprecation warnings are raised if the old name is used.
!!! warning "Name Change"
The name of the base class was changed with `0.7.0` from `IntegrationPluginBase` to `InvenTreePlugin`.
### Imports
@ -66,7 +66,7 @@ Mixins are split up internally to keep the source tree clean and enable better t
#### Models and other internal InvenTree APIs
!!! warning "Danger Zone"
The APIs outside of the `plugin` namespace are not structured for public usage and require a more in-depth knowledge of the Django framework. Please ask in GitHub discussions of the `ÌnvenTree` org if you are not sure you are using something the intended way.
The APIs outside of the `plugin` namespace are not structured for public usage and require a more in-depth knowledge of the Django framework. Please ask in GitHub discussions of the `InvenTree` org if you are not sure you are using something the intended way.
We do not provide stable interfaces to models or any other internal python APIs. If you need to integrate into these parts please make yourself familiar with the codebase. We follow general Django patterns and only stray from them in limited, special cases.
If you need to react to state changes please use the [EventMixin](./plugins/event.md).
@ -121,6 +121,7 @@ Supported mixin classes are:
| [ReportMixin](./plugins/report.md) | Add custom context data to reports |
| [ScheduleMixin](./plugins/schedule.md) | Schedule periodic tasks |
| [SettingsMixin](./plugins/settings.md) | Integrate user configurable settings |
| [UserInterfaceMixin](./plugins/ui.md) | Add custom user interface features |
| [UrlsMixin](./plugins/urls.md) | Respond to custom URL endpoints |
| [ValidationMixin](./plugins/validation.md) | Provide custom validation of database models |

2
docs/docs/extend/plugins/app.md
View File

@ -7,4 +7,4 @@ title: App Mixin
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]({% include "django.html" %}/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.
Only use this mixin if you have an understanding of Django's [app system]({% include "django.html" %}/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.

2
docs/docs/extend/plugins/navigation.md
View File

@ -5,7 +5,7 @@ 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).
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.
``` python
class MyNavigationPlugin(NavigationMixin, InvenTreePlugin):

44
docs/docs/extend/plugins/ui.md
View File

@ -217,3 +217,47 @@ We are working to develop and distribute a library of custom InvenTree component
### Examples
Refer to some of the existing InvenTree plugins linked above for examples of building custom UI plugins using the Mantine component library for seamless integration.
## Building a User Interface Plugin
The technology stack which allows custom plugins to hook into the InvenTree user interface utilizes the following components:
- [React](https://react.dev)
- [Mantine](https://mantine.dev)
- [TypeScript](https://www.typescriptlang.org/)
- [Vite](https://vitejs.dev/)
While you don't need to be an expert in all of these technologies, it is recommended that you have a basic understanding of how they work together to build the InvenTree user interface. To get started, you should familiarize yourself with the frontend code (at `./src/frontend/`) as well as the vite configuration for the [InvenTree plugin creator](httsps://github.com/inventree/plugin-creator).
### Bundled with InvenTree
If a plugin is bundled with a separate copy of React libraries, issues may arise either due to version mismatches or because the React context is not shared between the InvenTree core and the plugin. This can lead to issues with rendering components, as the React context may not be shared between the two libraries.
To avoid issues, the InvenTree UI provides globally accessible components, which can be used as external modules by the plugin. This allows the plugin to use the same React context as the InvenTree core, and ensures that the plugin is compatible with the InvenTree user interface.
The following modules are provided as global objects at runtime:
- `React`
- `ReactDOM`
- `ReactDOMClient`
Additionally, for the Mantine library, the following modules are provided as global objects at runtime:
- `@mantine/core`
- `@mantine/hooks`
- `@mantine/notifications`
To use these modules in your plugin, they must be correctly *externalized* in the Vite configuration. Getting this right is crucial to ensure that the plugin is compatible with the InvenTree user interface. The [InvenTree plugin creator](https://github.com/inventree/plugin-creator) provides a good starting point for this configuration, and can be used to generate a new plugin with the correct configuration.
!!! info "Bundled Version"
Keep in mind that the version of React and Mantine used in the InvenTree core may differ from the version used in your plugin. It is recommended to use the same version as the InvenTree core to avoid compatibility issues.
### Plugin Creator
The [InvenTree plugin creator](https://github.com/inventree/plugin-creator) provides an out-of-the-box setup for creating InvenTree plugins which integrate into the user interface. This includes a pre-configured Vite setup, which allows you to quickly get started with building your own custom UI plugins.
Using the plugin creator tool is the recommended way to get started with building custom UI plugins for InvenTree, as it provides a solid foundation to build upon. It is also the only method which is officially supported by the InvenTree development team!
### DIY
Of course, you can also build your own custom UI plugins from scratch. This is a more advanced option, and requires a good understanding of the InvenTree codebase, as well as the technologies used to build the user interface. You are free to use other web technologies, however if you choose to do this, don't expect any support from the InvenTree development team. We will only provide support for plugins which are built using the recommended stack, and which follow the guidelines outlined in this documentation.

2
docs/docs/extend/plugins/validation.md
View File

@ -69,7 +69,7 @@ from plugin.mixins import ValidationMixin
import part.models
class MyValidationMixin(Validationixin, InvenTreePlugin):
class MyValidationMixin(ValidationMixin, InvenTreePlugin):
"""Custom validation plugin."""
def validate_model_instance(self, instance, deltas=None):