User Interface Mixin

User Interface Mixin¶

The UserInterfaceMixin 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.

Custom UI Features¶

The InvenTree user interface functionality can be extended in various ways using plugins. Multiple types of user interface features can be added to the InvenTree user interface.

The entrypoint for user interface plugins is the UserInterfaceMixin class, which provides a number of methods which can be overridden to provide custom functionality. The get_ui_features method is used to extract available user interface features from the plugin:

Return a list of custom features to be injected into the UI.

Parameters:

Name	Type	Description	Default
`feature_type`	`FeatureType`	The type of feature being requested	required
`context`	`dict`	Additional context data provided by the UI (query parameters)	required
`request`	`Request`	HTTPRequest object (including user information)	required

Returns:

Name	Type	Description
`list`	`list[UIFeature]`	A list of custom UIFeature dicts to be injected into the UI

Source code in src/backend/InvenTree/plugin/base/ui/mixins.py

def get_ui_features(
    self, feature_type: FeatureType, context: dict, request: Request, **kwargs
) -> list[UIFeature]:
    """Return a list of custom features to be injected into the UI.

    Arguments:
        feature_type: The type of feature being requested
        context: Additional context data provided by the UI (query parameters)
        request: HTTPRequest object (including user information)

    Returns:
        list: A list of custom UIFeature dicts to be injected into the UI

    """
    feature_map = {
        'dashboard': self.get_ui_dashboard_items,
        'panel': self.get_ui_panels,
        'template_editor': self.get_ui_template_editors,
        'template_preview': self.get_ui_template_previews,
        'navigation': self.get_ui_navigation_items,
    }

    if feature_type in feature_map:
        return feature_map[feature_type](request, context, **kwargs)
    else:
        logger.warning(f'Invalid feature type: {feature_type}')
        return []

Note here that the get_ui_features calls other methods to extract the available features from the plugin, based on the requested feature type. These methods can be overridden to provide custom functionality.

Implementation

Your custom plugin does not need to override the get_ui_features method. Instead, override one of the other methods to provide custom functionality.

UIFeature Return Type¶

The get_ui_features method should return a list of UIFeature objects, which define the available user interface features for the plugin. The UIFeature class is defined as follows:

Base type definition for a ui feature.

Attributes:

Name	Type	Description
`key`	`str`	The key of the feature (required, must be a unique identifier)
`title`	`str`	The title of the feature (required, human readable)
`description`	`str`	The long-form description of the feature (optional, human readable)
`icon`	`str`	The icon of the feature (optional, must be a valid icon identifier)
`feature_type`	`FeatureType`	The feature type (required, see documentation for all available types)
`options`	`dict`	Feature options (required, see documentation for all available options for each type)
`context`	`dict`	Additional context data to be passed to the rendering function (optional, dict)
`source`	`str`	The source of the feature (required, path to a JavaScript file, with optional function name).

Source code in src/backend/InvenTree/plugin/base/ui/mixins.py

class UIFeature(TypedDict):
    """Base type definition for a ui feature.

    Attributes:
        key: The key of the feature (required, must be a unique identifier)
        title: The title of the feature (required, human readable)
        description: The long-form description of the feature (optional, human readable)
        icon: The icon of the feature (optional, must be a valid icon identifier)
        feature_type: The feature type (required, see documentation for all available types)
        options: Feature options (required, see documentation for all available options for each type)
        context: Additional context data to be passed to the rendering function (optional, dict)
        source: The source of the feature (required, path to a JavaScript file, with optional function name).
    """

    key: str
    title: str
    description: str
    icon: str
    feature_type: FeatureType
    options: dict
    context: dict
    source: str

Note that the options field contains fields which may be specific to a particular feature type - read the documentation below on each feature type for more information.

Dynamic Feature Loading¶

Each of the provided feature types can be loaded dynamically by the plugin, based on the information provided in the API request. For example, the plugin can choose to show or hide a particular feature based on the user permissions, or the current state of the system.

For examples of this dynamic feature loading, refer to the sample plugin implementation which demonstrates how to dynamically load custom panels based on the provided context.

Javascript Source Files¶

The rendering function for the custom user interface features expect that the plugin provides a Javascript source file which contains the necessary code to render the custom content. The path to this file should be provided in the source field of the UIFeature object.

Note that the source field can include the name of the function to be called (if this differs from the expected default function name).

For example:

"source": "/static/plugins/my_plugin/my_plugin.js:my_custom_function"

Available UI Feature Types¶

The following user interface feature types are available:

Dashboard Items¶

The InvenTree dashboard is a collection of "items" which are displayed on the main dashboard page. Custom dashboard items can be added to the dashboard by implementing the get_ui_dashboard_items method:

Return a list of custom dashboard items to be injected into the UI.

Parameters:

Name	Type	Description	Default
`request`	`Request`	HTTPRequest object (including user information)	required
`context`	`dict`	Additional context data provided by the UI (query parameters)	required

Returns:

Name	Type	Description
`list`	`list[UIFeature]`	A list of custom dashboard items to be injected into the UI

Source code in src/backend/InvenTree/plugin/base/ui/mixins.py

def get_ui_dashboard_items(
    self, request: Request, context: dict, **kwargs
) -> list[UIFeature]:
    """Return a list of custom dashboard items to be injected into the UI.

    Args:
        request: HTTPRequest object (including user information)
        context: Additional context data provided by the UI (query parameters)

    Returns:
        list: A list of custom dashboard items to be injected into the UI
    """
    # Default implementation returns an empty list
    return []

Dashboard Item Options¶

The options field in the returned UIFeature object can contain the following properties:

Options type definition for a custom dashboard item.

Attributes:

Name	Type	Description
`width`	`int`	The minimum width of the dashboard item (integer, defaults to 2)
`height`	`int`	The minimum height of the dashboard item (integer, defaults to 2)

Source code in src/backend/InvenTree/plugin/base/ui/mixins.py

class CustomDashboardItemOptions(TypedDict):
    """Options type definition for a custom dashboard item.

    Attributes:
        width: The minimum width of the dashboard item (integer, defaults to 2)
        height: The minimum height of the dashboard item (integer, defaults to 2)
    """

    width: int
    height: int

Source Function¶

The frontend code expects a path to a javascript file containing a function named renderDashboardItem which will be called to render the custom dashboard item. Note that this function name can be overridden by appending the function name in the source field of the UIFeature object.

Example¶

Refer to the sample plugin for an example of how to implement server side rendering for custom panels.

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_ui_panels method:

Return a list of custom panels to be injected into the UI.

Parameters:

Name	Type	Description	Default
`request`	`Request`	HTTPRequest object (including user information)	required
`context`	`dict`	Additional context data provided by the UI (query parameters)	required

Returns:

Name	Type	Description
`list`	`list[UIFeature]`	A list of custom panels to be injected into the UI

Source code in src/backend/InvenTree/plugin/base/ui/mixins.py

def get_ui_panels(
    self, request: Request, context: dict, **kwargs
) -> list[UIFeature]:
    """Return a list of custom panels to be injected into the UI.

    Args:
        request: HTTPRequest object (including user information)
        context: Additional context data provided by the UI (query parameters)

    Returns:
        list: A list of custom panels to be injected into the UI
    """
    # Default implementation returns an empty list
    return []

Panel Options¶

The options field in the returned UIFeature object can contain the following properties:

Options type definition for a custom panel.

Attributes:

Name	Type	Description
`icon`		The icon of the panel (optional, must be a valid icon identifier).

Source code in src/backend/InvenTree/plugin/base/ui/mixins.py

class CustomPanelOptions(TypedDict):
    """Options type definition for a custom panel.

    Attributes:
        icon: The icon of the panel (optional, must be a valid icon identifier).
    """

Source Function¶

The frontend code expects a path to a javascript file containing a function named renderPanel which will be called to render the custom panel. Note that this function name can be overridden by appending the function name in the source field of the UIFeature object.

Example¶

Refer to the sample plugin for an example of how to implement server side rendering for custom panels.

Template Editors¶

The get_ui_template_editors feature type can be used to provide custom template editors.

Return a list of custom template editors to be injected into the UI.

Parameters:

Name	Type	Description	Default
`request`	`Request`	HTTPRequest object (including user information)	required
`context`	`dict`	Additional context data provided by the UI (query parameters)	required

Returns:

Name	Type	Description
`list`	`list[UIFeature]`	A list of custom template editors to be injected into the UI

Source code in src/backend/InvenTree/plugin/base/ui/mixins.py

def get_ui_template_editors(
    self, request: Request, context: dict, **kwargs
) -> list[UIFeature]:
    """Return a list of custom template editors to be injected into the UI.

    Args:
        request: HTTPRequest object (including user information)
        context: Additional context data provided by the UI (query parameters)

    Returns:
        list: A list of custom template editors to be injected into the UI
    """
    # Default implementation returns an empty list
    return []

Template previews¶

The get_ui_template_previews feature type can be used to provide custom template previews:

Return a list of custom template previews to be injected into the UI.

Parameters:

Name	Type	Description	Default
`request`	`Request`	HTTPRequest object (including user information)	required
`context`	`dict`	Additional context data provided by the UI (query parameters)	required

Returns:

Name	Type	Description
`list`	`list[UIFeature]`	A list of custom template previews to be injected into the UI

Source code in src/backend/InvenTree/plugin/base/ui/mixins.py

def get_ui_template_previews(
    self, request: Request, context: dict, **kwargs
) -> list[UIFeature]:
    """Return a list of custom template previews to be injected into the UI.

    Args:
        request: HTTPRequest object (including user information)
        context: Additional context data provided by the UI (query parameters)

    Returns:
        list: A list of custom template previews to be injected into the UI
    """
    # Default implementation returns an empty list
    return []

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:

Plugin Context

import { useMantineColorScheme, useMantineTheme } from '@mantine/core';
import { useMemo } from 'react';
import { useNavigate } from 'react-router-dom';
import { useShallow } from 'zustand/react/shallow';
import { api, queryClient } from '../../App';
import { useLocalState } from '../../states/LocalState';
import {
  useGlobalSettingsState,
  useUserSettingsState
} from '../../states/SettingsState';
import { useUserState } from '../../states/UserState';

import {
  INVENTREE_MANTINE_VERSION,
  INVENTREE_PLUGIN_VERSION,
  INVENTREE_REACT_VERSION,
  type InvenTreePluginContext
} from '@lib/types/Plugins';
import {
  useBulkEditApiFormModal,
  useCreateApiFormModal,
  useDeleteApiFormModal,
  useEditApiFormModal
} from '../../hooks/UseForm';

export const useInvenTreeContext = () => {
  const [locale, host] = useLocalState(useShallow((s) => [s.language, s.host]));
  const navigate = useNavigate();
  const user = useUserState();
  const { colorScheme } = useMantineColorScheme();
  const theme = useMantineTheme();
  const globalSettings = useGlobalSettingsState();
  const userSettings = useUserSettingsState();

  const contextData = useMemo<InvenTreePluginContext>(() => {
    return {
      version: {
        inventree: INVENTREE_PLUGIN_VERSION,
        react: INVENTREE_REACT_VERSION,
        reactDom: INVENTREE_REACT_VERSION,
        mantine: INVENTREE_MANTINE_VERSION
      },
      user: user,
      host: host,
      locale: locale,
      api: api,
      queryClient: queryClient,
      navigate: navigate,
      globalSettings: globalSettings,
      userSettings: userSettings,
      theme: theme,
      colorScheme: colorScheme,
      forms: {
        bulkEdit: useBulkEditApiFormModal,
        create: useCreateApiFormModal,
        delete: useDeleteApiFormModal,
        edit: useEditApiFormModal
      }
    };
  }, [
    user,
    host,
    api,
    locale,
    queryClient,
    navigate,
    globalSettings,
    userSettings,
    theme,
    colorScheme
  ]);

  return contextData;
};

This context data can be used to provide additional information to the rendering functions, and can be used to dynamically render content based on the current state of the system.

Additional Context¶

Note that additional context can be passed to the rendering functions by adding additional key-value pairs to the context field in the UIFeature return type (provided by the backend via the API). This field is optional, and can be used at the discretion of the plugin developer.

File Distribution¶

When distributing a custom UI plugin, the plugin should include the necessary frontend code to render the custom content. This frontend code should be included in the plugin package, and should be made available to the InvenTree frontend when the plugin is installed.

The simplest (and recommended) way to achieve this is to distribute the compiled javascript files with the plugin package, in a top-level static directory. This directory will be automatically collected by InvenTree when the plugin is installed, and the files will be copied to the appropriate location.

Read more about static plugin files for more information.

Sample Plugin¶

A (very simple) sample plugin which implements custom user interface functionality is provided in the InvenTree source code, which provides a full working example of how to implement custom user interface functionality.

A sample plugin which demonstrates user interface integrations.

Source code in src/backend/InvenTree/plugin/samples/integration/user_interface_sample.py

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 = '2.0'

    ADMIN_SOURCE = 'ui_settings.js'

    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_ui_panels(self, request, context, **kwargs):
        """Return a list of custom panels to be injected into the UI."""
        panels = []
        context = context or {}

        # First, add a custom panel which will appear on every type of page
        # This panel will contain a simple message

        target_model = context.get('target_model', None)
        target_id = context.get('target_id', None)

        # A broken panel which tries to load a non-existent JS file
        if target_id is not None and self.get_setting('ENABLE_BROKEN_PANElS'):
            panels.append({
                'key': 'broken-panel',
                'title': 'Broken Panel',
                'source': '/this/does/not/exist.js',
            })

        # A dynamic panel which will be injected into the UI (loaded from external file)
        # Note that we additionally provide some "context" data to the front-end render function
        if self.get_setting('ENABLE_DYNAMIC_PANEL'):
            panels.append({
                'key': 'dynamic-panel',
                'title': 'Dynamic Panel',
                'source': self.plugin_static_file('sample_panel.js'),
                'icon': 'ti:wave-saw-tool:outline',
                'context': {
                    'version': INVENTREE_SW_VERSION,
                    'plugin_version': self.VERSION,
                    'random': random.randint(1, 100),
                    'time': time.time(),
                },
            })

        # 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 target_model == 'part':
            try:
                part = Part.objects.get(pk=target_id)
            except (Part.DoesNotExist, ValueError):
                part = None

            panels.append({
                'key': 'part-panel',
                'title': _('Part Panel'),
                'source': self.plugin_static_file('sample_panel.js:renderPartPanel'),
                'icon': 'ti:package_outline',
                'context': {'part_name': part.name if part else ''},
            })

        # Next, add a custom panel which will appear on the 'purchaseorder' page
        if target_model == 'purchaseorder' and self.get_setting(
            'ENABLE_PURCHASE_ORDER_PANELS'
        ):
            panels.append({
                'key': 'purchase_order_panel',
                'title': 'Purchase Order Panel',
                'source': self.plugin_static_file('sample_panel.js:renderPoPanel'),
            })

        # Admin panel - only visible to admin users
        if request.user.is_superuser:
            panels.append({
                'key': 'admin-panel',
                'title': 'Admin Panel',
                'source': self.plugin_static_file(
                    'sample_panel.js:renderAdminOnlyPanel'
                ),
            })

        return panels

    def get_ui_dashboard_items(self, request, context, **kwargs):
        """Return a list of custom dashboard items."""
        items = [
            {
                'key': 'broken-dashboard-item',
                'title': _('Broken Dashboard Item'),
                'description': _(
                    'This is a broken dashboard item - it will not render!'
                ),
                'source': '/this/does/not/exist.js',
            },
            {
                'key': 'sample-dashboard-item',
                'title': _('Sample Dashboard Item'),
                'description': _(
                    'This is a sample dashboard item. It renders a simple string of HTML content.'
                ),
                'source': self.plugin_static_file('sample_dashboard_item.js'),
            },
            {
                'key': 'dynamic-dashboard-item',
                'title': _('Context Dashboard Item'),
                'description': 'A dashboard item which passes context data from the server',
                'source': self.plugin_static_file(
                    'sample_dashboard_item.js:renderContextItem'
                ),
                'context': {'foo': 'bar', 'hello': 'world'},
                'options': {'width': 3, 'height': 2},
            },
        ]

        # Admin item - only visible to users with superuser access
        if request.user.is_superuser:
            items.append({
                'key': 'admin-dashboard-item',
                'title': _('Admin Dashboard Item'),
                'description': _('This is an admin-only dashboard item.'),
                'source': self.plugin_static_file('admin_dashboard_item.js'),
                'options': {'width': 4, 'height': 2},
                'context': {'secret-key': 'this-is-a-secret'},
            })

        return items

    def get_ui_template_editors(self, request, context, **kwargs):
        """Return a list of custom template editors."""
        # If the context is a label template, return a custom template editor
        if context.get('template_type') == 'labeltemplate':
            return [
                {
                    'key': 'sample-template-editor',
                    'title': 'Sample Template Editor',
                    'icon': 'ti:tags:outline',
                    'source': self.plugin_static_file(
                        'sample_template.js:getTemplateEditor'
                    ),
                }
            ]

        return []

    def get_ui_template_previews(self, request, context, **kwargs):
        """Return a list of custom template previews."""
        return [
            {
                'key': 'sample-template-preview',
                'title': 'Sample Template Preview',
                'icon': 'ti:category:outline',
                'source': self.plugin_static_file(
                    'sample_preview.js:getTemplatePreview'
                ),
            }
        ]

    def get_ui_navigation_items(self, request, context, **kwargs):
        """Return a list of custom navigation items."""
        return [
            {
                'key': 'sample-nav-item',
                'title': 'Sample Nav Item',
                'icon': 'ti:menu',
                'options': {'url': '/sample/page/'},
            }
        ]

    def get_admin_context(self) -> dict:
        """Return custom context data which can be rendered in the admin panel."""
        return {'apple': 'banana', 'foo': 'bar', 'hello': 'world'}

More Examples¶

Some more complex examples of user interface plugins can be found on the InvenTree GitHub repository:

Consistent Theming¶

When developing a custom UI plugin for InvenTree, the plugin should aim to match the existing InvenTree theme as closely as possible. This will help to ensure that the custom content fits seamlessly into the existing user interface.

To achieve this, we strongly recommend that you use the same framework as the InvenTree frontend - which is built using React on top of the Mantine UI component library.

Mantine¶

The Mantine UI component library is used throughout the InvenTree frontend, and provides a consistent look and feel to the user interface. By using Mantine components in your custom UI plugin, you can ensure that your custom content fits seamlessly into the existing InvenTree theme.

InvenTree Component Library¶

We are working to develop and distribute a library of custom InvenTree components which can be used to build custom UI plugins. This library will be made available to plugin developers in the near future.

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:

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.

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 provides a good starting point for this configuration, and can be used to generate a new plugin with the correct configuration.

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 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.