Permalink
Fetching contributors…
Cannot retrieve contributors at this time
296 lines (200 sloc) 8.74 KB

Mixins

General Concepts

Plugin mixins are the heart of OctoPrint's plugin system. They are :ref:`special base classes <sec-plugins-mixins>` which are to be subclassed and extended to add functionality to OctoPrint. Plugins declare their instances that implement one or multiple mixins using the __plugin_implementation__ control property. OctoPrint's plugin core collects those from the plugins and offers methods to access them based on the mixin type, which get used at multiple locations within OctoPrint.

Using mixins always follows the pattern of retrieving the matching implementations from the plugin subsystem, then calling the specific mixin's methods as defined and necessary.

The following snippet taken from OctoPrint's code for example shows how all :class:`~octoprint.plugin.AssetPlugin` implementations are collected and then all assets they return via their get_assets methods are retrieved and merged into one big asset map (differing between javascripts and stylesheets of various types) for use during rendition of the UI.

.. seealso::

   :ref:`The Plugin Tutorial <sec-plugins-gettingstarted>`
       Tutorial on how to write a simple OctoPrint module utilizing mixins for various types of extension.

Execution Order

Some mixin types, such as :class:`~octoprint.plugin.StartupPlugin`, :class:`~octoprint.plugin.ShutdownPlugin` and :class:`~octoprint.plugin.UiPlugin`, support influencing the execution order for various execution contexts by also implementing the :class:`~octoprint.plugin.core.SortablePlugin` mixin.

If a method is to be called on a plugin implementation for which a sorting context is defined (see the mixin documentation for information on this), OctoPrint's plugin subsystem will ensure that the order in which the implementation calls are done is as follows:

  • Plugins with a return value that is not None for :meth:`~octoprint.plugin.core.SortablePlugin.get_sorting_key` for the provided sorting context will be ordered among each other first. If the returned order number is equal for two or more implementations, the plugin's identifier will be the next sorting criteria.
  • After that follow plugins which returned None (the default). They are sorted by their identifier.

Example: Consider three plugin implementations implementing the :class:`~octoprint.plugin.StartupPlugin` mixin, called plugin_a, plugin_b and plugin_c. plugin_a doesn't override :meth:`~octoprint.plugin.core.SortablePlugin.get_sorting_key`. plugin_b and plugin_c both return 1 for the sorting context StartupPlugin.on_startup, None otherwise:

OctoPrint will detect that plugin_b and plugin_c define a order number, and since it's identical for both (1) will order both plugins based on their plugin identifier. plugin_a doesn't define a sort key and hence will be put after the other two. The execution order of the on_startup method will hence be plugin_b, plugin_c, plugin_a.

Now, the execution order of the on_after_startup method will be determined based on another sorting context, StartupPlugin.on_after_startup for which all of the plugins return None. Hence, the execution order of the on_after_startup method will be purely ordered by plugin identifier, plugin_a, plugin_b, plugin_c.

Injected Properties

OctoPrint's plugin subsystem will inject a bunch of properties into each :ref:`mixin implementation <sec-plugins-mixins>`. An overview of these properties can be found in the section :ref:`Injected Properties <sec-plugins-injectedproperties>`.

.. seealso::

   :class:`~octoprint.plugin.core.Plugin` and :class:`~octoprint.plugin.types.OctoPrintPlugin`
       Class documentation also containing the properties shared among all mixin implementations.

Available plugin mixins

The following plugin mixins are currently available:

Please note that all plugin mixins inherit from :class:`~octoprint.plugin.core.Plugin` and :class:`~octoprint.plugin.types.OctoPrintPlugin`, which also provide attributes of interest to plugin developers.

StartupPlugin

.. autoclass:: octoprint.plugin.StartupPlugin
   :members:
   :show-inheritance:

ShutdownPlugin

.. autoclass:: octoprint.plugin.ShutdownPlugin
   :members:
   :show-inheritance:

SettingsPlugin

.. autoclass:: octoprint.plugin.SettingsPlugin
   :members:
   :show-inheritance:

AssetPlugin

.. autoclass:: octoprint.plugin.AssetPlugin
   :members:
   :show-inheritance:

TemplatePlugin

.. autoclass:: octoprint.plugin.TemplatePlugin
   :members:
   :show-inheritance:

WizardPlugin

.. autoclass:: octoprint.plugin.WizardPlugin
   :members:
   :show-inheritance:

UiPlugin

.. autoclass:: octoprint.plugin.UiPlugin
   :members:
   :show-inheritance:

SimpleApiPlugin

.. autoclass:: octoprint.plugin.SimpleApiPlugin
   :members:
   :show-inheritance:

BlueprintPlugin

.. autoclass:: octoprint.plugin.BlueprintPlugin
   :members:
   :show-inheritance:

EventHandlerPlugin

.. autoclass:: octoprint.plugin.EventHandlerPlugin
   :members:
   :show-inheritance:

ProgressPlugin

.. autoclass:: octoprint.plugin.ProgressPlugin
   :members:
   :show-inheritance:

SlicerPlugin

.. autoclass:: octoprint.plugin.SlicerPlugin
   :members:
   :show-inheritance:

RestartNeedingPlugin

.. autoclass:: octoprint.plugin.RestartNeedingPlugin
   :members:
   :show-inheritance:

ReloadNeedingPlugin

.. autoclass:: octoprint.plugin.ReloadNeedingPlugin
   :members:
   :show-inheritance: