diff --git a/docs/docs/extend/plugins/panel.md b/docs/docs/extend/plugins/panel.md index f91c175ab1..d19c568475 100644 --- a/docs/docs/extend/plugins/panel.md +++ b/docs/docs/extend/plugins/panel.md @@ -4,6 +4,12 @@ title: Panel Mixin ## PanelMixin +!!! warning "Legacy User Interface" + This plugin mixin class is designed specifically for the the *legacy* user interface (which is rendered on the server using django templates). The new user interface (which is rendered on the client using React) does not support this mixin class. Instead, refer to the new [User Interface Mixin](./ui.md) class. + +!!! warning "Deprecated Class" + This mixin class is considered deprecated, and will be removed in the 1.0.0 release. + The `PanelMixin` enables plugins to render custom content to "panels" on individual pages in the web interface. Most pages in the web interface support multiple panels, which are selected via the sidebar menu on the left side of the screen: diff --git a/docs/docs/extend/plugins/ui.md b/docs/docs/extend/plugins/ui.md new file mode 100644 index 0000000000..33b58faabe --- /dev/null +++ b/docs/docs/extend/plugins/ui.md @@ -0,0 +1,102 @@ +--- +title: User Interface Mixin +--- + +## User Interface Mixin + +The *User Interface* mixin class provides a set of methods to implement custom functionality for the InvenTree web interface. + +### Enable User Interface Mixin + +To enable user interface plugins, the global setting `ENABLE_PLUGINS_INTERFACE` must be enabled, in the [plugin settings](../../settings/global.md#plugin-settings). + +## Plugin Context + +When rendering certain content in the user interface, the rendering functions are passed a `context` object which contains information about the current page being rendered. The type of the `context` object is defined in the `PluginContext` file: + +{{ includefile("src/frontend/src/components/plugins/PluginContext.tsx", title="Plugin Context", fmt="javascript") }} + +## Custom Panels + +Many of the pages in the InvenTree web interface are built using a series of "panels" which are displayed on the page. Custom panels can be added to these pages, by implementing the `get_custom_panels` method: + +::: plugin.base.integration.UserInterfaceMixin.UserInterfaceMixin.get_custom_panels + options: + show_bases: False + show_root_heading: False + show_root_toc_entry: False + show_sources: True + summary: False + members: [] + +The custom panels can display content which is generated either on the server side, or on the client side (see below). + +### Server Side Rendering + +The panel content can be generated on the server side, by returning a 'content' attribute in the response. This 'content' attribute is expected to be raw HTML, and is rendered directly into the page. This is particularly useful for displaying static content. + +Server-side rendering is simple to implement, and can make use of the powerful Django templating system. + +Refer to the [sample plugin](#sample-plugin) for an example of how to implement server side rendering for custom panels. + +**Advantages:** + +- Simple to implement +- Can use Django templates to render content +- Has access to the full InvenTree database, and content not available on the client side (via the API) + +**Disadvantages:** + +- Content is rendered on the server side, and cannot be updated without a page refresh +- Content is not interactive + +### Client Side Rendering + +The panel content can also be generated on the client side, by returning a 'source' attribute in the response. This 'source' attribute is expected to be a URL which points to a JavaScript file which will be loaded by the client. + +Refer to the [sample plugin](#sample-plugin) for an example of how to implement client side rendering for custom panels. + +#### Panel Render Function + +The JavaScript file must implement a `renderPanel` function, which is called by the client when the panel is rendered. This function is passed two parameters: + +- `target`: The HTML element which the panel content should be rendered into +- `context`: A dictionary of context data which can be used to render the panel content + + +**Example** + +```javascript +export function renderPanel(target, context) { + target.innerHTML = "

Hello, world!

"; +} +``` + +#### Panel Visibility Function + +The JavaScript file can also implement a `isPanelHidden` function, which is called by the client to determine if the panel is displayed. This function is passed a single parameter, *context* - which is the same as the context data passed to the `renderPanel` function. + +The `isPanelHidden` function should return a boolean value, which determines if the panel is displayed or not, based on the context data. + +If the `isPanelHidden` function is not implemented, the panel will be displayed by default. + +**Example** + +```javascript +export function isPanelHidden(context) { + // Only visible for active parts + return context.model == 'part' && context.instance?.active; +} +``` + +## Sample Plugin + +A sample plugin which implements custom user interface functionality is provided in the InvenTree source code: + +::: plugin.samples.integration.user_interface_sample.SampleUserInterfacePlugin + options: + show_bases: False + show_root_heading: False + show_root_toc_entry: False + show_source: True + members: [] diff --git a/docs/docs/settings/global.md b/docs/docs/settings/global.md index d2ecaf44e4..5c4f4b9f5a 100644 --- a/docs/docs/settings/global.md +++ b/docs/docs/settings/global.md @@ -208,7 +208,6 @@ Refer to the [return order settings](../order/return_order.md#return-order-setti ### Plugin Settings - | Name | Description | Default | Units | | ---- | ----------- | ------- | ----- | {{ globalsetting("PLUGIN_ON_STARTUP") }} @@ -218,3 +217,4 @@ Refer to the [return order settings](../order/return_order.md#return-order-setti {{ globalsetting("ENABLE_PLUGINS_APP") }} {{ globalsetting("ENABLE_PLUGINS_SCHEDULE") }} {{ globalsetting("ENABLE_PLUGINS_EVENTS") }} +{{ globalsetting("ENABLE_PLUGINS_INTERFACE") }} diff --git a/docs/docs/start/config.md b/docs/docs/start/config.md index 5653b8a659..0fa4cf1af8 100644 --- a/docs/docs/start/config.md +++ b/docs/docs/start/config.md @@ -26,7 +26,7 @@ The InvenTree server tries to locate the `config.yaml` configuration file on sta The configuration file *template* can be found on [GitHub]({{ sourcefile("src/backend/InvenTree/config_template.yaml") }}), and is shown below: -{{ includefile("src/backend/InvenTree/config_template.yaml", "Configuration File Template", format="yaml") }} +{{ includefile("src/backend/InvenTree/config_template.yaml", "Configuration File Template", fmt="yaml") }} !!! info "Template File" The default configuration file (as defined by the template linked above) will be copied to the specified configuration file location on first run, if a configuration file is not found in that location. diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 059a7fb10b..b9d4fdd137 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -213,6 +213,7 @@ nav: - Schedule Mixin: extend/plugins/schedule.md - Settings Mixin: extend/plugins/settings.md - URL Mixin: extend/plugins/urls.md + - User Interface Mixin: extend/plugins/ui.md - Validation Mixin: extend/plugins/validation.md - Machines: - Overview: extend/machines/overview.md diff --git a/src/backend/InvenTree/InvenTree/api_version.py b/src/backend/InvenTree/InvenTree/api_version.py index eca68cac40..d7f0ffa89b 100644 --- a/src/backend/InvenTree/InvenTree/api_version.py +++ b/src/backend/InvenTree/InvenTree/api_version.py @@ -1,13 +1,16 @@ """InvenTree API version information.""" # InvenTree API version -INVENTREE_API_VERSION = 253 +INVENTREE_API_VERSION = 254 """Increment this API version number whenever there is a significant change to the API that any clients need to know about.""" INVENTREE_API_TEXT = """ +v254 - 2024-09-14 : https://github.com/inventree/InvenTree/pull/7470 + - Implements new API endpoints for enabling custom UI functionality via plugins + v253 - 2024-09-14 : https://github.com/inventree/InvenTree/pull/7944 - Adjustments for user API endpoints diff --git a/src/backend/InvenTree/InvenTree/management/commands/collectplugins.py b/src/backend/InvenTree/InvenTree/management/commands/collectplugins.py index 77b00f73b5..ce7df416fc 100644 --- a/src/backend/InvenTree/InvenTree/management/commands/collectplugins.py +++ b/src/backend/InvenTree/InvenTree/management/commands/collectplugins.py @@ -8,6 +8,7 @@ class Command(BaseCommand): def handle(self, *args, **kwargs): """Run the management command.""" - from plugin.staticfiles import collect_plugins_static_files + import plugin.staticfiles - collect_plugins_static_files() + plugin.staticfiles.collect_plugins_static_files() + plugin.staticfiles.clear_plugins_static_files() diff --git a/src/backend/InvenTree/InvenTree/models.py b/src/backend/InvenTree/InvenTree/models.py index c57a0ccbcb..2d2b558b4e 100644 --- a/src/backend/InvenTree/InvenTree/models.py +++ b/src/backend/InvenTree/InvenTree/models.py @@ -439,7 +439,7 @@ class ReferenceIndexingMixin(models.Model): ) # Check that the reference field can be rebuild - cls.rebuild_reference_field(value, validate=True) + return cls.rebuild_reference_field(value, validate=True) @classmethod def rebuild_reference_field(cls, reference, validate=False): diff --git a/src/backend/InvenTree/InvenTree/settings.py b/src/backend/InvenTree/InvenTree/settings.py index 8529397770..8c10edfb08 100644 --- a/src/backend/InvenTree/InvenTree/settings.py +++ b/src/backend/InvenTree/InvenTree/settings.py @@ -133,6 +133,34 @@ STATIC_URL = '/static/' # Web URL endpoint for served media files MEDIA_URL = '/media/' +# Are plugins enabled? +PLUGINS_ENABLED = get_boolean_setting( + 'INVENTREE_PLUGINS_ENABLED', 'plugins_enabled', False +) + +PLUGINS_INSTALL_DISABLED = get_boolean_setting( + 'INVENTREE_PLUGIN_NOINSTALL', 'plugin_noinstall', False +) + +PLUGIN_FILE = config.get_plugin_file() + +# Plugin test settings +PLUGIN_TESTING = get_setting( + 'INVENTREE_PLUGIN_TESTING', 'PLUGIN_TESTING', TESTING +) # Are plugins being tested? + +PLUGIN_TESTING_SETUP = get_setting( + 'INVENTREE_PLUGIN_TESTING_SETUP', 'PLUGIN_TESTING_SETUP', False +) # Load plugins from setup hooks in testing? + +PLUGIN_TESTING_EVENTS = False # Flag if events are tested right now + +PLUGIN_RETRY = get_setting( + 'INVENTREE_PLUGIN_RETRY', 'PLUGIN_RETRY', 3, typecast=int +) # How often should plugin loading be tried? + +PLUGIN_FILE_CHECKED = False # Was the plugin file checked? + STATICFILES_DIRS = [] # Translated Template settings @@ -153,6 +181,12 @@ if DEBUG and 'collectstatic' not in sys.argv: if web_dir.exists(): STATICFILES_DIRS.append(web_dir) + # Append directory for sample plugin static content (if in debug mode) + if PLUGINS_ENABLED: + print('Adding plugin sample static content') + STATICFILES_DIRS.append(BASE_DIR.joinpath('plugin', 'samples', 'static')) + + print('-', STATICFILES_DIRS[-1]) STATFILES_I18_PROCESSORS = ['InvenTree.context.status_codes'] # Color Themes Directory @@ -1254,29 +1288,6 @@ IGNORED_ERRORS = [Http404, django.core.exceptions.PermissionDenied] MAINTENANCE_MODE_RETRY_AFTER = 10 MAINTENANCE_MODE_STATE_BACKEND = 'InvenTree.backends.InvenTreeMaintenanceModeBackend' -# Are plugins enabled? -PLUGINS_ENABLED = get_boolean_setting( - 'INVENTREE_PLUGINS_ENABLED', 'plugins_enabled', False -) -PLUGINS_INSTALL_DISABLED = get_boolean_setting( - 'INVENTREE_PLUGIN_NOINSTALL', 'plugin_noinstall', False -) - -PLUGIN_FILE = config.get_plugin_file() - -# Plugin test settings -PLUGIN_TESTING = get_setting( - 'INVENTREE_PLUGIN_TESTING', 'PLUGIN_TESTING', TESTING -) # Are plugins being tested? -PLUGIN_TESTING_SETUP = get_setting( - 'INVENTREE_PLUGIN_TESTING_SETUP', 'PLUGIN_TESTING_SETUP', False -) # Load plugins from setup hooks in testing? -PLUGIN_TESTING_EVENTS = False # Flag if events are tested right now -PLUGIN_RETRY = get_setting( - 'INVENTREE_PLUGIN_RETRY', 'PLUGIN_RETRY', 3, typecast=int -) # How often should plugin loading be tried? -PLUGIN_FILE_CHECKED = False # Was the plugin file checked? - # Flag to allow table events during testing TESTING_TABLE_EVENTS = False diff --git a/src/backend/InvenTree/InvenTree/unit_test.py b/src/backend/InvenTree/InvenTree/unit_test.py index 100b450019..c6409fd6c8 100644 --- a/src/backend/InvenTree/InvenTree/unit_test.py +++ b/src/backend/InvenTree/InvenTree/unit_test.py @@ -291,6 +291,18 @@ class InvenTreeAPITestCase(ExchangeRateMixin, UserMixin, APITestCase): self.assertLess(n, value, msg=msg) + @classmethod + def setUpTestData(cls): + """Setup for API tests. + + - Ensure that all global settings are assigned default values. + """ + from common.models import InvenTreeSetting + + InvenTreeSetting.build_default_values() + + super().setUpTestData() + def check_response(self, url, response, expected_code=None): """Debug output for an unexpected response.""" # Check that the response returned the expected status code diff --git a/src/backend/InvenTree/InvenTree/urls.py b/src/backend/InvenTree/InvenTree/urls.py index 03712320e1..7f6d6c6b37 100644 --- a/src/backend/InvenTree/InvenTree/urls.py +++ b/src/backend/InvenTree/InvenTree/urls.py @@ -484,7 +484,7 @@ if settings.ENABLE_PLATFORM_FRONTEND: urlpatterns += frontendpatterns -# Append custom plugin URLs (if plugin support is enabled) +# Append custom plugin URLs (if custom plugin support is enabled) if settings.PLUGINS_ENABLED: urlpatterns.append(get_plugin_urls()) diff --git a/src/backend/InvenTree/build/filters.py b/src/backend/InvenTree/build/filters.py new file mode 100644 index 0000000000..ff3c02a523 --- /dev/null +++ b/src/backend/InvenTree/build/filters.py @@ -0,0 +1,25 @@ +"""Queryset filtering helper functions for the Build app.""" + + +from django.db import models +from django.db.models import Sum, Q +from django.db.models.functions import Coalesce + + +def annotate_allocated_quantity(queryset: Q) -> Q: + """ + Annotate the 'allocated' quantity for each build item in the queryset. + + Arguments: + queryset: The BuildLine queryset to annotate + + """ + + queryset = queryset.prefetch_related('allocations') + + return queryset.annotate( + allocated=Coalesce( + Sum('allocations__quantity'), 0, + output_field=models.DecimalField() + ) + ) diff --git a/src/backend/InvenTree/build/models.py b/src/backend/InvenTree/build/models.py index 899145f98d..9b13dbf1ed 100644 --- a/src/backend/InvenTree/build/models.py +++ b/src/backend/InvenTree/build/models.py @@ -9,7 +9,7 @@ from django.contrib.auth.models import User from django.core.exceptions import ValidationError from django.core.validators import MinValueValidator from django.db import models, transaction -from django.db.models import Sum, Q +from django.db.models import F, Sum, Q from django.db.models.functions import Coalesce from django.db.models.signals import post_save from django.dispatch.dispatcher import receiver @@ -24,6 +24,7 @@ from rest_framework import serializers from build.status_codes import BuildStatus, BuildStatusGroups from stock.status_codes import StockStatus, StockHistoryCode +from build.filters import annotate_allocated_quantity from build.validators import generate_next_build_reference, validate_build_order_reference from generic.states import StateTransitionMixin @@ -124,8 +125,7 @@ class Build( def save(self, *args, **kwargs): """Custom save method for the BuildOrder model""" - self.validate_reference_field(self.reference) - self.reference_int = self.rebuild_reference_field(self.reference) + self.reference_int = self.validate_reference_field(self.reference) # Check part when initially creating the build order if not self.pk or self.has_field_changed('part'): @@ -987,12 +987,13 @@ class Build( items_to_save = [] items_to_delete = [] - lines = self.untracked_line_items - lines = lines.prefetch_related('allocations') + lines = self.untracked_line_items.all() + lines = lines.exclude(bom_item__consumable=True) + lines = annotate_allocated_quantity(lines) for build_line in lines: - reduce_by = build_line.allocated_quantity() - build_line.quantity + reduce_by = build_line.allocated - build_line.quantity if reduce_by <= 0: continue @@ -1290,18 +1291,20 @@ class Build( """Returns a list of BuildLine objects which have not been fully allocated.""" lines = self.build_lines.all() + # Remove any 'consumable' line items + lines = lines.exclude(bom_item__consumable=True) + if tracked is True: lines = lines.filter(bom_item__sub_part__trackable=True) elif tracked is False: lines = lines.filter(bom_item__sub_part__trackable=False) - unallocated_lines = [] + lines = annotate_allocated_quantity(lines) - for line in lines: - if not line.is_fully_allocated(): - unallocated_lines.append(line) + # Filter out any lines which have been fully allocated + lines = lines.filter(allocated__lt=F('quantity')) - return unallocated_lines + return lines def is_fully_allocated(self, tracked=None): """Test if the BuildOrder has been fully allocated. @@ -1314,19 +1317,24 @@ class Build( Returns: True if the BuildOrder has been fully allocated, otherwise False """ - lines = self.unallocated_lines(tracked=tracked) - return len(lines) == 0 + + return self.unallocated_lines(tracked=tracked).count() == 0 def is_output_fully_allocated(self, output): """Determine if the specified output (StockItem) has been fully allocated for this build Args: - output: StockItem object + output: StockItem object (the "in production" output to test against) To determine if the output has been fully allocated, we need to test all "trackable" BuildLine objects """ - for line in self.build_lines.filter(bom_item__sub_part__trackable=True): + + lines = self.build_lines.filter(bom_item__sub_part__trackable=True) + lines = lines.exclude(bom_item__consumable=True) + + # Find any lines which have not been fully allocated + for line in lines: # Grab all BuildItem objects which point to this output allocations = BuildItem.objects.filter( build_line=line, @@ -1350,11 +1358,14 @@ class Build( Returns: True if any BuildLine has been over-allocated. """ - for line in self.build_lines.all(): - if line.is_overallocated(): - return True - return False + lines = self.build_lines.all().exclude(bom_item__consumable=True) + lines = annotate_allocated_quantity(lines) + + # Find any lines which have been over-allocated + lines = lines.filter(allocated__gt=F('quantity')) + + return lines.count() > 0 @property def is_active(self): @@ -1692,6 +1703,9 @@ class BuildItem(InvenTree.models.InvenTreeMetadataModel): - If the referenced part is trackable, the stock item will be *installed* into the build output - If the referenced part is *not* trackable, the stock item will be *consumed* by the build order + + TODO: This is quite expensive (in terms of number of database hits) - and requires some thought + """ item = self.stock_item diff --git a/src/backend/InvenTree/common/models.py b/src/backend/InvenTree/common/models.py index 2b8dc5aca3..03c6d8b0ac 100644 --- a/src/backend/InvenTree/common/models.py +++ b/src/backend/InvenTree/common/models.py @@ -2095,6 +2095,13 @@ class InvenTreeSetting(BaseInvenTreeSetting): 'validator': bool, 'after_save': reload_plugin_registry, }, + 'ENABLE_PLUGINS_INTERFACE': { + 'name': _('Enable interface integration'), + 'description': _('Enable plugins to integrate into the user interface'), + 'default': False, + 'validator': bool, + 'after_save': reload_plugin_registry, + }, 'PROJECT_CODES_ENABLED': { 'name': _('Enable project codes'), 'description': _('Enable project codes for tracking projects'), diff --git a/src/backend/InvenTree/plugin/api.py b/src/backend/InvenTree/plugin/api.py index 1d3f6763f8..a8a9cb1c48 100644 --- a/src/backend/InvenTree/plugin/api.py +++ b/src/backend/InvenTree/plugin/api.py @@ -11,11 +11,13 @@ from django_filters.rest_framework import DjangoFilterBackend from drf_spectacular.utils import extend_schema from rest_framework import permissions, status from rest_framework.exceptions import NotFound +from rest_framework.permissions import IsAuthenticated from rest_framework.response import Response from rest_framework.views import APIView import plugin.serializers as PluginSerializers from common.api import GlobalSettingsPermissions +from common.settings import get_global_setting from InvenTree.api import MetadataView from InvenTree.filters import SEARCH_ORDER_FILTER from InvenTree.mixins import ( @@ -414,6 +416,38 @@ class RegistryStatusView(APIView): return Response(result) +class PluginPanelList(APIView): + """API endpoint for listing all available plugin panels.""" + + permission_classes = [IsAuthenticated] + serializer_class = PluginSerializers.PluginPanelSerializer + + @extend_schema(responses={200: PluginSerializers.PluginPanelSerializer(many=True)}) + def get(self, request): + """Show available plugin panels.""" + target_model = request.query_params.get('target_model', None) + target_id = request.query_params.get('target_id', None) + + panels = [] + + if get_global_setting('ENABLE_PLUGINS_INTERFACE'): + # Extract all plugins from the registry which provide custom panels + for _plugin in registry.with_mixin('ui', active=True): + # Allow plugins to fill this data out + plugin_panels = _plugin.get_custom_panels( + target_model, target_id, request + ) + + if plugin_panels and type(plugin_panels) is list: + for panel in plugin_panels: + panel['plugin'] = _plugin.slug + + # TODO: Validate each panel before inserting + panels.append(panel) + + return Response(PluginSerializers.PluginPanelSerializer(panels, many=True).data) + + class PluginMetadataView(MetadataView): """Metadata API endpoint for the PluginConfig model.""" @@ -428,6 +462,21 @@ plugin_api_urls = [ path( 'plugins/', include([ + path( + 'ui/', + include([ + path( + 'panels/', + include([ + path( + '', + PluginPanelList.as_view(), + name='api-plugin-panel-list', + ) + ]), + ) + ]), + ), # Plugin management path('reload/', PluginReload.as_view(), name='api-plugin-reload'), path('install/', PluginInstall.as_view(), name='api-plugin-install'), diff --git a/src/backend/InvenTree/plugin/base/integration/UserInterfaceMixin.py b/src/backend/InvenTree/plugin/base/integration/UserInterfaceMixin.py new file mode 100644 index 0000000000..252c18705b --- /dev/null +++ b/src/backend/InvenTree/plugin/base/integration/UserInterfaceMixin.py @@ -0,0 +1,76 @@ +"""UserInterfaceMixin class definition. + +Allows integration of custom UI elements into the React user interface. +""" + +import logging +from typing import TypedDict + +from rest_framework.request import Request + +logger = logging.getLogger('inventree') + + +class CustomPanel(TypedDict): + """Type definition for a custom panel. + + Attributes: + name: The name of the panel (required, used as a DOM identifier). + label: The label of the panel (required, human readable). + icon: The icon of the panel (optional, must be a valid icon identifier). + content: The content of the panel (optional, raw HTML). + source: The source of the panel (optional, path to a JavaScript file). + """ + + name: str + label: str + icon: str + content: str + source: str + + +class UserInterfaceMixin: + """Plugin mixin class which handles injection of custom elements into the front-end interface. + + - All content is accessed via the API, as requested by the user interface. + - This means that content can be dynamically generated, based on the current state of the system. + """ + + class MixinMeta: + """Metaclass for this plugin mixin.""" + + MIXIN_NAME = 'ui' + + def __init__(self): + """Register mixin.""" + super().__init__() + self.add_mixin('ui', True, __class__) + + def get_custom_panels( + self, instance_type: str, instance_id: int, request: Request + ) -> list[CustomPanel]: + """Return a list of custom panels to be injected into the UI. + + Args: + instance_type: The type of object being viewed (e.g. 'part') + instance_id: The ID of the object being viewed (e.g. 123) + request: HTTPRequest object (including user information) + + Returns: + list: A list of custom panels to be injected into the UI + + - The returned list should contain a dict for each custom panel to be injected into the UI: + - The following keys can be specified: + { + 'name': 'panel_name', # The name of the panel (required, must be unique) + 'label': 'Panel Title', # The title of the panel (required, human readable) + 'icon': 'icon-name', # Icon name (optional, must be a valid icon identifier) + 'content': '

Panel content

', # HTML content to be rendered in the panel (optional) + 'source': 'static/plugin/panel.js', # Path to a JavaScript file to be loaded (optional) + } + + - Either 'source' or 'content' must be provided + + """ + # Default implementation returns an empty list + return [] diff --git a/src/backend/InvenTree/plugin/base/integration/test_mixins.py b/src/backend/InvenTree/plugin/base/integration/test_mixins.py index 43bd7b9d1f..83caccad30 100644 --- a/src/backend/InvenTree/plugin/base/integration/test_mixins.py +++ b/src/backend/InvenTree/plugin/base/integration/test_mixins.py @@ -8,7 +8,8 @@ from django.urls import include, path, re_path, reverse from error_report.models import Error -from InvenTree.unit_test import InvenTreeTestCase +from common.models import InvenTreeSetting +from InvenTree.unit_test import InvenTreeAPITestCase, InvenTreeTestCase from plugin import InvenTreePlugin from plugin.base.integration.PanelMixin import PanelMixin from plugin.helpers import MixinNotImplementedError @@ -341,7 +342,10 @@ class APICallMixinTest(BaseMixinDefinition, TestCase): class PanelMixinTests(InvenTreeTestCase): - """Test that the PanelMixin plugin operates correctly.""" + """Test that the PanelMixin plugin operates correctly. + + TODO: This class will be removed in the future, as the PanelMixin is deprecated. + """ fixtures = ['category', 'part', 'location', 'stock'] @@ -475,3 +479,100 @@ class PanelMixinTests(InvenTreeTestCase): plugin = Wrong() plugin.get_custom_panels('abc', 'abc') + + +class UserInterfaceMixinTests(InvenTreeAPITestCase): + """Test the UserInterfaceMixin plugin mixin class.""" + + roles = 'all' + + fixtures = ['part', 'category', 'location', 'stock'] + + @classmethod + def setUpTestData(cls): + """Set up the test case.""" + super().setUpTestData() + + # Ensure that the 'sampleui' plugin is installed and active + registry.set_plugin_state('sampleui', True) + + # Ensure that UI plugins are enabled + InvenTreeSetting.set_setting('ENABLE_PLUGINS_INTERFACE', True, change_user=None) + + def test_installed(self): + """Test that the sample UI plugin is installed and active.""" + plugin = registry.get_plugin('sampleui') + self.assertTrue(plugin.is_active()) + + plugins = registry.with_mixin('ui') + self.assertGreater(len(plugins), 0) + + def test_panels(self): + """Test that the sample UI plugin provides custom panels.""" + from part.models import Part + + plugin = registry.get_plugin('sampleui') + + _part = Part.objects.first() + + # Ensure that the part is active + _part.active = True + _part.save() + + url = reverse('api-plugin-panel-list') + + query_data = {'target_model': 'part', 'target_id': _part.pk} + + # Enable *all* plugin settings + plugin.set_setting('ENABLE_PART_PANELS', True) + plugin.set_setting('ENABLE_PURCHASE_ORDER_PANELS', True) + plugin.set_setting('ENABLE_BROKEN_PANELS', True) + plugin.set_setting('ENABLE_DYNAMIC_PANEL', True) + + # Request custom panel information for a part instance + response = self.get(url, data=query_data) + + # There should be 4 active panels for the part by default + self.assertEqual(4, len(response.data)) + + _part.active = False + _part.save() + + response = self.get(url, data=query_data) + + # As the part is not active, only 3 panels left + self.assertEqual(3, len(response.data)) + + # Disable the "ENABLE_PART_PANELS" setting, and try again + plugin.set_setting('ENABLE_PART_PANELS', False) + + response = self.get(url, data=query_data) + + # There should still be 3 panels + self.assertEqual(3, len(response.data)) + + # Check for the correct panel names + self.assertEqual(response.data[0]['name'], 'sample_panel') + self.assertIn('content', response.data[0]) + self.assertNotIn('source', response.data[0]) + + self.assertEqual(response.data[1]['name'], 'broken_panel') + self.assertEqual(response.data[1]['source'], '/this/does/not/exist.js') + self.assertNotIn('content', response.data[1]) + + self.assertEqual(response.data[2]['name'], 'dynamic_panel') + self.assertEqual(response.data[2]['source'], '/static/plugin/sample_panel.js') + self.assertNotIn('content', response.data[2]) + + # Next, disable the global setting for UI integration + InvenTreeSetting.set_setting( + 'ENABLE_PLUGINS_INTERFACE', False, change_user=None + ) + + response = self.get(url, data=query_data) + + # There should be no panels available + self.assertEqual(0, len(response.data)) + + # Set the setting back to True for subsequent tests + InvenTreeSetting.set_setting('ENABLE_PLUGINS_INTERFACE', True, change_user=None) diff --git a/src/backend/InvenTree/plugin/installer.py b/src/backend/InvenTree/plugin/installer.py index c8b0094ae3..4d706aaad2 100644 --- a/src/backend/InvenTree/plugin/installer.py +++ b/src/backend/InvenTree/plugin/installer.py @@ -10,6 +10,7 @@ from django.core.exceptions import ValidationError from django.utils.translation import gettext_lazy as _ import plugin.models +import plugin.staticfiles from InvenTree.exceptions import log_error logger = logging.getLogger('inventree') @@ -119,6 +120,10 @@ def install_plugins_file(): log_error('pip') return False + # Update static files + plugin.staticfiles.collect_plugins_static_files() + plugin.staticfiles.clear_plugins_static_files() + # At this point, the plugins file has been installed return True @@ -256,6 +261,9 @@ def install_plugin(url=None, packagename=None, user=None, version=None): registry.reload_plugins(full_reload=True, force_reload=True, collect=True) + # Update static files + plugin.staticfiles.collect_plugins_static_files() + return ret @@ -320,6 +328,9 @@ def uninstall_plugin(cfg: plugin.models.PluginConfig, user=None, delete_config=T # Remove the plugin configuration from the database cfg.delete() + # Remove static files associated with this plugin + plugin.staticfiles.clear_plugin_static_files(cfg.key) + # Reload the plugin registry registry.reload_plugins(full_reload=True, force_reload=True, collect=True) diff --git a/src/backend/InvenTree/plugin/mixins/__init__.py b/src/backend/InvenTree/plugin/mixins/__init__.py index 1fa960c306..1de17d613d 100644 --- a/src/backend/InvenTree/plugin/mixins/__init__.py +++ b/src/backend/InvenTree/plugin/mixins/__init__.py @@ -14,6 +14,7 @@ from plugin.base.integration.ReportMixin import ReportMixin from plugin.base.integration.ScheduleMixin import ScheduleMixin from plugin.base.integration.SettingsMixin import SettingsMixin from plugin.base.integration.UrlsMixin import UrlsMixin +from plugin.base.integration.UserInterfaceMixin import UserInterfaceMixin from plugin.base.integration.ValidationMixin import ValidationMixin from plugin.base.label.mixins import LabelPrintingMixin from plugin.base.locate.mixins import LocateMixin @@ -38,5 +39,7 @@ __all__ = [ 'SingleNotificationMethod', 'SupplierBarcodeMixin', 'UrlsMixin', + 'UrlsMixin', + 'UserInterfaceMixin', 'ValidationMixin', ] diff --git a/src/backend/InvenTree/plugin/registry.py b/src/backend/InvenTree/plugin/registry.py index 7663fecb2a..65166a7921 100644 --- a/src/backend/InvenTree/plugin/registry.py +++ b/src/backend/InvenTree/plugin/registry.py @@ -742,11 +742,12 @@ class PluginsRegistry: def plugin_settings_keys(self): """A list of keys which are used to store plugin settings.""" return [ - 'ENABLE_PLUGINS_URL', - 'ENABLE_PLUGINS_NAVIGATION', 'ENABLE_PLUGINS_APP', - 'ENABLE_PLUGINS_SCHEDULE', 'ENABLE_PLUGINS_EVENTS', + 'ENABLE_PLUGINS_INTERFACE', + 'ENABLE_PLUGINS_NAVIGATION', + 'ENABLE_PLUGINS_SCHEDULE', + 'ENABLE_PLUGINS_URL', ] def calculate_plugin_hash(self): diff --git a/src/backend/InvenTree/plugin/samples/integration/templates/uidemo/custom_part_panel.html b/src/backend/InvenTree/plugin/samples/integration/templates/uidemo/custom_part_panel.html new file mode 100644 index 0000000000..72815ed67e --- /dev/null +++ b/src/backend/InvenTree/plugin/samples/integration/templates/uidemo/custom_part_panel.html @@ -0,0 +1,30 @@ +{% load i18n %} + +

Custom Plugin Panel

+ +

+This content has been rendered by a custom plugin, and will be displayed for any "part" instance +(as long as the plugin is enabled). +This content has been rendered on the server, using the django templating system. +

+ +
Part Details
+ + + + + + + + + + + + + + + + + + +
Part Name{{ part.name }}
Part Description{{ part.description }}
Part Category{{ part.category.pathstring }}
Part IPN{% if part.IPN %}{{ part.IPN }}{% else %}No IPN specified{% endif %}
diff --git a/src/backend/InvenTree/plugin/samples/integration/user_interface_sample.py b/src/backend/InvenTree/plugin/samples/integration/user_interface_sample.py new file mode 100644 index 0000000000..5b0fbf2f77 --- /dev/null +++ b/src/backend/InvenTree/plugin/samples/integration/user_interface_sample.py @@ -0,0 +1,124 @@ +"""Sample plugin which demonstrates user interface integrations.""" + +from django.utils.translation import gettext_lazy as _ + +from part.models import Part +from plugin import InvenTreePlugin +from plugin.helpers import render_template, render_text +from plugin.mixins import SettingsMixin, UserInterfaceMixin + + +class SampleUserInterfacePlugin(SettingsMixin, UserInterfaceMixin, InvenTreePlugin): + """A sample plugin which demonstrates user interface integrations.""" + + NAME = 'SampleUI' + SLUG = 'sampleui' + TITLE = 'Sample User Interface Plugin' + DESCRIPTION = 'A sample plugin which demonstrates user interface integrations' + VERSION = '1.0' + + SETTINGS = { + 'ENABLE_PART_PANELS': { + 'name': _('Enable Part Panels'), + 'description': _('Enable custom panels for Part views'), + 'default': True, + 'validator': bool, + }, + 'ENABLE_PURCHASE_ORDER_PANELS': { + 'name': _('Enable Purchase Order Panels'), + 'description': _('Enable custom panels for Purchase Order views'), + 'default': False, + 'validator': bool, + }, + 'ENABLE_BROKEN_PANELS': { + 'name': _('Enable Broken Panels'), + 'description': _('Enable broken panels for testing'), + 'default': True, + 'validator': bool, + }, + 'ENABLE_DYNAMIC_PANEL': { + 'name': _('Enable Dynamic Panel'), + 'description': _('Enable dynamic panels for testing'), + 'default': True, + 'validator': bool, + }, + } + + def get_custom_panels(self, instance_type: str, instance_id: int, request): + """Return a list of custom panels to be injected into the UI.""" + panels = [] + + # First, add a custom panel which will appear on every type of page + # This panel will contain a simple message + + content = render_text( + """ + This is a sample panel which appears on every page. + It renders a simple string of HTML content. + +
+
Instance Details:
+ + """, + context={'instance_type': instance_type, 'instance_id': instance_id}, + ) + + panels.append({ + 'name': 'sample_panel', + 'label': 'Sample Panel', + 'content': content, + }) + + # A broken panel which tries to load a non-existent JS file + if self.get_setting('ENABLE_BROKEN_PANElS'): + panels.append({ + 'name': 'broken_panel', + 'label': 'Broken Panel', + 'source': '/this/does/not/exist.js', + }) + + # A dynamic panel which will be injected into the UI (loaded from external file) + if self.get_setting('ENABLE_DYNAMIC_PANEL'): + panels.append({ + 'name': 'dynamic_panel', + 'label': 'Dynamic Part Panel', + 'source': '/static/plugin/sample_panel.js', + 'icon': 'part', + }) + + # Next, add a custom panel which will appear on the 'part' page + # Note that this content is rendered from a template file, + # using the django templating system + if self.get_setting('ENABLE_PART_PANELS') and instance_type == 'part': + try: + part = Part.objects.get(pk=instance_id) + except (Part.DoesNotExist, ValueError): + part = None + + # Note: This panel will *only* be available if the part is active + if part and part.active: + content = render_template( + self, 'uidemo/custom_part_panel.html', context={'part': part} + ) + + panels.append({ + 'name': 'part_panel', + 'label': 'Part Panel', + 'content': content, + }) + + # Next, add a custom panel which will appear on the 'purchaseorder' page + if ( + self.get_setting('ENABLE_PURCHASE_ORDER_PANELS') + and instance_type == 'purchaseorder' + ): + panels.append({ + 'name': 'purchase_order_panel', + 'label': 'Purchase Order Panel', + 'content': 'This is a custom panel which appears on the Purchase Order view page.', + }) + + return panels diff --git a/src/backend/InvenTree/plugin/samples/static/plugin/sample_panel.js b/src/backend/InvenTree/plugin/samples/static/plugin/sample_panel.js new file mode 100644 index 0000000000..c0a0f5d1f4 --- /dev/null +++ b/src/backend/InvenTree/plugin/samples/static/plugin/sample_panel.js @@ -0,0 +1,47 @@ +/** + * A sample panel plugin for InvenTree. + * + * This plugin file is dynamically loaded, + * as specified in the plugin/samples/integration/user_interface_sample.py + * + * It provides a simple example of how panels can be dynamically rendered, + * as well as dynamically hidden, based on the provided context. + */ + +export function renderPanel(target, context) { + + if (!target) { + console.error("No target provided to renderPanel"); + return; + } + + target.innerHTML = ` +

Dynamic Panel Content

+ +

This panel has been dynamically rendered by the plugin system.

+

It can be hidden or displayed based on the provided context.

+ +
+
Context:
+ +