[Doc] Restructured the plugins section so it makes more sense
This commit is contained in:
Gina Häußge
parent
5c228e6071
commit
8a41cef00b
10 changed files with 231 additions and 252 deletions
|
|
@ -10,3 +10,4 @@ Features
|
|||
custom_controls.rst
|
||||
gcode_scripts.rst
|
||||
action_commands.rst
|
||||
plugins.rst
|
||||
|
|
|
|||
64
docs/features/plugins.rst
Normal file
64
docs/features/plugins.rst
Normal file
|
|
@ -0,0 +1,64 @@
|
|||
.. _sec-features-plugins:
|
||||
|
||||
*******
|
||||
Plugins
|
||||
*******
|
||||
|
||||
Starting with OctoPrint 1.2.0, there's now a plugin system in place which allows to individually
|
||||
extend OctoPrint's functionality.
|
||||
|
||||
Right now plugins can be used to extend OctoPrint's web interface, to execute specific tasks on server startup and
|
||||
shutdown, to provide custom (API) endpoints or whole user interfaces with special functionality, to react to system
|
||||
events or progress reports or to add support for additional slicers. More plugin types are planned for the future.
|
||||
|
||||
.. _sec-features-plugins-available:
|
||||
|
||||
Finding Plugins
|
||||
===============
|
||||
|
||||
Currently there's no such thing as a centralized plugin repository for available plugins.
|
||||
|
||||
Plugins may be found in the lists provided in `the OctoPrint wiki <https://github.com/foosel/OctoPrint/wiki#plugins>`_
|
||||
and on the `OctoPrint organization Github page <https://github.com/OctoPrint>`_.
|
||||
|
||||
.. _sec-features-plugins-installing:
|
||||
|
||||
Installing Plugins
|
||||
==================
|
||||
|
||||
Plugins can be installed either by unpacking them into one of the configured plugin folders (regularly those are
|
||||
``<octoprint source root>/plugins`` and ``<octoprint config folder>/plugins`` [#f1]_ or by installing them as regular python
|
||||
modules via ``pip`` [#f2]_.
|
||||
|
||||
Please refer to the documentation of the plugin for installations instructions.
|
||||
|
||||
For a plugin available on the Python Package Index (PyPi), the process is as simple as issuing a
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
pip install <plugin_name>
|
||||
|
||||
For plugins not available on PyPi, you'll have to give ``pip`` an URL from which to install the package (e.g. the URL to
|
||||
a ZIP file of the current master branch of a Github repository hosting a plugin, or even a ``git+https`` URL), example:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
pip install https://github.com/OctoPrint/OctoPrint-Growl/archive/master.zip
|
||||
|
||||
See `the pip install documentation <http://pip.readthedocs.org/en/latest/reference/pip_install.html>`_ for what URL
|
||||
types are possible.
|
||||
|
||||
.. _sec-features-plugins-developing:
|
||||
|
||||
Developing Plugins
|
||||
==================
|
||||
|
||||
See :ref:`Developing Plugins <sec-plugins>`.
|
||||
|
||||
.. rubric:: Footnotes
|
||||
|
||||
.. [#f1] For Linux that will be ``~/.octoprint/plugins``, for Windows it will be ``%APPDATA%/OctoPrint/plugins`` and for
|
||||
Mac ``~/Library/Application Support/OctoPrint``
|
||||
.. [#f2] Make sure to use the exact same Python installation for installing the plugin that you also used for
|
||||
installing & running OctoPrint. For OctoPi this means using ``~/oprint/bin/pip`` for installing plugins
|
||||
instead of just ``pip``.
|
||||
|
|
@ -4,7 +4,7 @@ Concepts
|
|||
========
|
||||
|
||||
OctoPrint's plugins are `Python Packages <https://docs.python.org/2/tutorial/modules.html#packages>`_ which in their
|
||||
top-level module define a bunch of :ref:`control properties <sec-plugins-infrastructure-controlproperties>` defining
|
||||
top-level module define a bunch of :ref:`control properties <sec-plugin-concepts-controlproperties>` defining
|
||||
metadata (like name, version etc of the plugin) as well as information on how to initialize the plugin and into what
|
||||
parts of the system the plugin will actually plug in to perform its job.
|
||||
|
||||
|
|
@ -13,6 +13,57 @@ There are three types of ways a plugin might attach itself to the system, throug
|
|||
:ref:`hook <sec-plugin-concepts-hooks>` or by offering :ref:`helper <sec-plugin-concepts-helpers>` functionality to be
|
||||
used by other plugins.
|
||||
|
||||
Plugin mixin implementations will get a bunch of :ref:`properties injected <sec-plugins-concepts-injectedproperties>`
|
||||
by OctoPrint plugin system to help them work.
|
||||
|
||||
.. _sec-plugin-concepts-controlproperties:
|
||||
|
||||
Control Properties
|
||||
------------------
|
||||
|
||||
As already mentioned above, plugins are Python packages which provide certain pieces of metadata to tell OctoPrint's
|
||||
plugin subsystem about themselves. These are simple package attributes defined in the top most package file, e.g.:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
import octoprint.plugin
|
||||
|
||||
# ...
|
||||
|
||||
__plugin_name__ = "My Plugin"
|
||||
def __plugin_init__():
|
||||
# whatever you need to do to init your plugin, if anything at all
|
||||
pass
|
||||
|
||||
The following properties are recognized:
|
||||
|
||||
``__plugin_name__``
|
||||
Name of your plugin, optional, overrides the name specified in ``setup.py`` if provided. If neither this property nor
|
||||
a name from ``setup.py`` is available to the plugin subsystem, the plugin's identifier (= package name) will be
|
||||
used instead.
|
||||
``__plugin_version__``
|
||||
Version of your plugin, optional, overrides the version specified in ``setup.py`` if provided.
|
||||
``__plugin_description__``
|
||||
Description of your plugin, optional, overrides the description specified in ``setup.py`` if provided.
|
||||
``__plugin_author__``
|
||||
Author of your plugin, optional, overrides the author specified in ``setup.py`` if provided.
|
||||
``__plugin_url__``
|
||||
URL of the webpage of your plugin, e.g. the Github repository, optional, overrides the URL specified in ``setup.py`` if
|
||||
provided.
|
||||
``__plugin_license__``
|
||||
License of your plugin, optional, overrides the license specified in ``setup.py`` if provided.
|
||||
``__plugin_implementation__``
|
||||
Instance of an implementation of one or more :ref:`plugin mixins <sec-plugins-mixins>`.
|
||||
``__plugin_hooks__``
|
||||
Handlers for one or more of the various :ref:`plugin hooks <sec-plugins-hooks>`.
|
||||
``__plugin_check__``
|
||||
Method called upon discovery of the plugin by the plugin subsystem, should return ``True`` if the
|
||||
plugin can be instantiated later on, ``False`` if there are reasons why not, e.g. if dependencies
|
||||
are missing.
|
||||
``__plugin_init__``
|
||||
Method called upon initializing of the plugin by the plugin subsystem, can be used to instantiate
|
||||
plugin implementations, connecting them to hooks etc.
|
||||
|
||||
.. _sec-plugin-concepts-mixins:
|
||||
|
||||
Mixins
|
||||
|
|
@ -223,4 +274,52 @@ them as (hopefully) documented.
|
|||
return flask.jsonify(dict(
|
||||
browsing_enabled=True,
|
||||
growl_instances=growl_instances
|
||||
))
|
||||
))
|
||||
|
||||
.. _sec-plugins-concepts-injectedproperties:
|
||||
|
||||
Injected Properties
|
||||
-------------------
|
||||
|
||||
OctoPrint's plugin subsystem will inject a bunch of properties into each :ref:`mixin implementation <sec-plugin-concepts-mixins>`.
|
||||
An overview of these properties follows.
|
||||
|
||||
``self._identifier``
|
||||
The plugin's identifier.
|
||||
``self._plugin_name``
|
||||
The plugin's name, as taken from either the ``__plugin_name__`` control property or the package info.
|
||||
``self._plugin_version``
|
||||
The plugin's version, as taken from either the ``__plugin_version__`` control property or the package info.
|
||||
``self._basefolder``
|
||||
The plugin's base folder where it's installed. Can be used to refer to files relative to the plugin's installation
|
||||
location, e.g. included scripts, templates or assets.
|
||||
``self._logger``
|
||||
A `python logger instance <https://docs.python.org/2/library/logging.html>`_ logging to the log target
|
||||
``octoprint.plugin.<plugin identifier>``.
|
||||
``self._settings``
|
||||
The plugin's personalized settings manager, injected only into plugins that include the :class:`~octoprint.plugin.SettingsPlugin` mixin.
|
||||
An instance of :class:`octoprint.plugin.PluginSettings`.
|
||||
``self._plugin_manager``
|
||||
OctoPrint's plugin manager object, an instance of :class:`octoprint.plugin.core.PluginManager`.
|
||||
``self._printer_profile_manager``
|
||||
OctoPrint's printer profile manager, an instance of :class:`octoprint.printer.profile.PrinterProfileManager`.
|
||||
``self._event_bus``
|
||||
OctoPrint's event bus, an instance of :class:`octoprint.events.EventManager`.
|
||||
``self._analysis_queue``
|
||||
OctoPrint's analysis queue for analyzing GCODEs or other files, an instance of :class:`octoprint.filemanager.analysis.AnalysisQueue`.
|
||||
``self._slicing_manager``
|
||||
OctoPrint's slicing manager, an instance of :class:`octoprint.slicing.SlicingManager`.
|
||||
``self._file_manager``
|
||||
OctoPrint's file manager, an instance of :class:`octoprint.filemanager.FileManager`.
|
||||
``self._printer``
|
||||
OctoPrint's printer management object, an instance of :class:`octoprint.printer.PrinterInterface`.
|
||||
``self._app_session_manager``
|
||||
OctoPrint's application session manager, an instance of :class:`octoprint.server.util.flask.AppSessionManager`.
|
||||
|
||||
.. seealso::
|
||||
|
||||
:class:`~octoprint.plugin.core.Plugin` and :class:`~octoprint.plugin.types.OctoPrintPlugin`
|
||||
Class documentation also containing the properties shared among all mixing implementations.
|
||||
|
||||
:ref:`Available Mixins <sec-plugins-mixins>`
|
||||
Some mixin types trigger the injection of additional properties.
|
||||
|
|
|
|||
|
|
@ -3,25 +3,44 @@
|
|||
Distributing your plugin
|
||||
========================
|
||||
|
||||
You can distribute a plugin with OctoPrint via two ways:
|
||||
You can distribute a plugin with OctoPrint via two ways.
|
||||
|
||||
- You can have your users copy it to OctoPrint's plugin folder (normally located at ``~/.octoprint/plugins`` under Linux,
|
||||
``%APPDATA%\OctoPrint\plugins`` on Windows and ... on Mac). In this case your plugin will be distributed directly
|
||||
as a Python module (a single ``.py`` file containing all of your plugin's code directly and named
|
||||
like your plugin) or a package (a folder named like your plugin + ``__init.py__`` contained within).
|
||||
- You can have your users install it via ``pip`` and register it for the `entry point <https://pythonhosted.org/setuptools/setuptools.html#dynamic-discovery-of-services-and-plugins>`_ ``octoprint.plugin`` via
|
||||
your plugin's ``setup.py``, this way it will be found automatically by OctoPrint upon initialization of the
|
||||
plugin subsystem [#f1]_.
|
||||
.. _sec-plugins-distribution-manual:
|
||||
|
||||
For an example of how the directory structure and related files would look like in this case, please take a
|
||||
look at the `helloworld example from OctoPrint's example plugins <https://github.com/OctoPrint/Plugin-Examples/tree/master/helloworld>`_.
|
||||
Manual file distribution
|
||||
------------------------
|
||||
|
||||
This variant is highly recommended for pretty much any plugin besides the most basic ones since it also allows
|
||||
requirements management and pretty much any thing else that Python's setuptools provide to the developer.
|
||||
You can have your users copy it to OctoPrint's plugin folder (normally located at ``~/.octoprint/plugins`` under Linux,
|
||||
``%APPDATA%\OctoPrint\plugins`` on Windows and ... on Mac). In this case your plugin will be distributed directly
|
||||
as a Python module (a single ``.py`` file containing all of your plugin's code directly and named
|
||||
like your plugin) or a package (a folder named like your plugin + ``__init.py__`` contained within).
|
||||
|
||||
.. _sec-plugins-distribution-pip:
|
||||
|
||||
Proper packages installable via pip
|
||||
-----------------------------------
|
||||
|
||||
You can have your users install it via ``pip`` and register it for the `entry point <https://pythonhosted.org/setuptools/setuptools.html#dynamic-discovery-of-services-and-plugins>`_ ``octoprint.plugin`` via
|
||||
your plugin's ``setup.py``, this way it will be found automatically by OctoPrint upon initialization of the
|
||||
plugin subsystem [#f1]_.
|
||||
|
||||
For an example of how the directory structure and related files would look like in this case, please take a
|
||||
look at the `helloworld example from OctoPrint's example plugins <https://github.com/OctoPrint/Plugin-Examples/tree/master/helloworld>`_.
|
||||
|
||||
This variant is highly recommended for pretty much any plugin besides the most basic ones since it also allows
|
||||
requirements management and pretty much any thing else that Python's setuptools provide to the developer.
|
||||
|
||||
.. seealso::
|
||||
|
||||
`OctoPrint Plugin Skeleton <https://github.com/OctoPrint/OctoPrint-PluginSkeleton>`_
|
||||
A basic plugin skeleton providing you with all you need to get started with distributing your plugin as a proper
|
||||
package. See the :ref:`Getting Started Guide <sec-plugins-gettingstarted>` for an
|
||||
:ref:`example <sec-plugins-gettingstarted-growingup>` on how to use this.
|
||||
|
||||
.. rubric:: Footnotes
|
||||
|
||||
.. [#f1] The automatic registration will only work within the same Python installation (this also includes virtual
|
||||
environments), so make sure to instruct your users to use the exact same Python installation for installing
|
||||
the plugin that they also used for installing & running OctoPrint.
|
||||
the plugin that they also used for installing & running OctoPrint. For OctoPi this means using
|
||||
``~/oprint/bin/pip`` for installing plugins instead of just ``pip``.
|
||||
|
||||
|
|
|
|||
|
|
@ -22,8 +22,13 @@ We'll start at the most basic form a plugin can take - just a couple of simple l
|
|||
Saving this as ``helloworld.py`` in ``~/.octoprint/plugins`` yields you something resembling these log entries upon server startup::
|
||||
|
||||
2015-01-27 11:14:35,124 - octoprint.server - INFO - Starting OctoPrint 1.2.0-dev-448-gd96e56e (devel branch)
|
||||
[...]
|
||||
2015-01-27 11:14:35,124 - octoprint.plugin.core - INFO - Loading plugins from /home/pi/.octoprint/plugins, /home/pi/OctoPrint/src/octoprint/plugins and installed plugin packages...
|
||||
2015-01-27 11:14:36,135 - octoprint.plugin.core - INFO - Found 3 plugin(s): Hello World (1.0), CuraEngine (0.1), Discovery (0.1)
|
||||
[...]
|
||||
2015-01-27 11:14:36,135 - octoprint.plugin.core - INFO - 3 plugin(s) registered with the system:
|
||||
| CuraEngine (bundled) = /home/pi/OctoPrint/src/octoprint/plugins/cura
|
||||
| Discovery (bundled) = /home/pi/OctoPrint/src/octoprint/plugins/discovery
|
||||
| Hello World (1.0) = /home/pi/.octoprint/plugins/helloworld.py
|
||||
|
||||
OctoPrint found that plugin in the folder and took a look into it. The name and the version it displays in that log
|
||||
entry it got from the ``__plugin_name__`` and ``__plugin_version__`` lines. It also read the description from
|
||||
|
|
@ -68,7 +73,7 @@ used :func:`~octoprint.plugin.StartupPlugin.on_startup` instead, in which case o
|
|||
up and ready to serve requests.
|
||||
|
||||
You'll also note that we are using ``self._logger`` for logging. Where did that one come from? OctoPrint's plugin system
|
||||
injects :ref:`a couple of useful objects <sec-plugins-infrastructure-injections>` into our plugin implementation classes,
|
||||
injects :ref:`a couple of useful objects <sec-plugins-concepts-injectedproperties>` into our plugin implementation classes,
|
||||
one of those being a fully instantiated `python logger <https://docs.python.org/2/library/logging.html>`_ ready to be
|
||||
used by your plugin. As you can see in the log output above, that logger uses the namespace ``octoprint.plugins.helloworld``
|
||||
for our little plugin here, or more generally ``octoprint.plugins.<plugin identifier>``.
|
||||
|
|
@ -85,8 +90,7 @@ You basically have two options to distribute your plugin. One would be about the
|
|||
as a simple python file following the naming convention ``<plugin identifier>.py`` that your users add to their
|
||||
``~/.octoprint/plugins`` folder. You already know how that works. But let's say you have more than just a simple plugin
|
||||
that can be done in one file. Distributing multiple files and getting your users to install them in the right way
|
||||
so that OctoPrint will be able to actually find and load them is certainly not impossible (see :ref:`the plugin distribution
|
||||
documentation <sec-plugins-distribution>` if you want to take a closer look at that option), but we want to do it in the
|
||||
so that OctoPrint will be able to actually find and load them is certainly not impossible, but we want to do it in the
|
||||
best way possible, meaning we want to make our plugin a fully installable python module that your users will be able to
|
||||
install directly via Python's standard package manager ``pip`` or alternatively via `OctoPrint's own plugin manager <https://github.com/OctoPrint/OctoPrint-PluginManager>`_.
|
||||
|
||||
|
|
@ -130,8 +134,13 @@ discoverable by OctoPrint, however we don't have to reinstall it after any chang
|
|||
Restart OctoPrint. Your plugin should still be properly discovered and the log line should be printed::
|
||||
|
||||
2015-01-27 13:43:34,134 - octoprint.server - INFO - Starting OctoPrint 1.2.0-dev-448-gd96e56e (devel branch)
|
||||
[...]
|
||||
2015-01-27 13:43:34,134 - octoprint.plugin.core - INFO - Loading plugins from /home/pi/.octoprint/plugins, /home/pi/OctoPrint/src/octoprint/plugins and installed plugin packages...
|
||||
2015-01-27 13:43:34,818 - octoprint.plugin.core - INFO - Found 3 plugin(s): Hello World (1.0), CuraEngine (0.1), Discovery (0.1)
|
||||
[...]
|
||||
2015-01-27 13:43:34,818 - octoprint.plugin.core - INFO - 3 plugin(s) registered with the system:
|
||||
| CuraEngine (bundled) = /home/pi/OctoPrint/src/octoprint/plugins/cura
|
||||
| Discovery (bundled) = /home/pi/OctoPrint/src/octoprint/plugins/discovery
|
||||
| Hello World (1.0) = /home/pi/OctoPrint-HelloWorld/octoprint_helloworld
|
||||
[...]
|
||||
2015-01-27 13:43:38,997 - octoprint.plugins.helloworld - INFO - Hello World!
|
||||
|
||||
|
|
@ -142,13 +151,16 @@ of information now defined twice:
|
|||
|
||||
.. code-block:: python
|
||||
:linenos:
|
||||
:caption: __init__.py
|
||||
|
||||
# __init__.py:
|
||||
__plugin_name__ = "Hello World"
|
||||
__plugin_version__ = "1.0"
|
||||
__plugin_description__ = "A quick \"Hello World\" example plugin for OctoPrint"
|
||||
|
||||
# setup.py
|
||||
.. code-block:: python
|
||||
:linenos:
|
||||
:caption: setup.py
|
||||
|
||||
plugin_name = "OctoPrint-HelloWorld"
|
||||
plugin_version = "1.0"
|
||||
plugin_description = "A quick \"Hello World\" example plugin for OctoPrint"
|
||||
|
|
@ -173,7 +185,10 @@ and ``__plugin_description__`` from ``__init__.py``:
|
|||
|
||||
and restart OctoPrint::
|
||||
|
||||
2015-01-27 13:46:33,786 - octoprint.plugin.core - INFO - Found 3 plugin(s): OctoPrint-HelloWorld (1.0), CuraEngine (0.1), Discovery (0.1)
|
||||
2015-01-27 13:46:33,786 - octoprint.plugin.core - INFO - 3 plugin(s) registered with the system:
|
||||
| CuraEngine (bundled) = /home/pi/OctoPrint/src/octoprint/plugins/cura
|
||||
| Discovery (bundled) = /home/pi/OctoPrint/src/octoprint/plugins/discovery
|
||||
| OctoPrint-HelloWorld (1.0) = /home/pi/OctoPrint-HelloWorld/octoprint_helloworld
|
||||
|
||||
Our "Hello World" Plugin still gets detected fine, but it's now listed under the same name it's installed under,
|
||||
"OctoPrint-HelloWorld". That's a bit redundant and squashed, so we'll override that bit via ``__plugin_name__`` again:
|
||||
|
|
@ -197,10 +212,13 @@ Our "Hello World" Plugin still gets detected fine, but it's now listed under the
|
|||
|
||||
Restart OctoPrint again::
|
||||
|
||||
2015-01-27 13:48:54,122 - octoprint.plugin.core - INFO - Found 3 plugin(s): Hello World (1.0), CuraEngine (0.1), Discovery (0.1)
|
||||
2015-01-27 13:48:54,122 - octoprint.plugin.core - INFO - 3 plugin(s) registered with the system:
|
||||
| CuraEngine (bundled) = /home/pi/OctoPrint/src/octoprint/plugins/cura
|
||||
| Discovery (bundled) = /home/pi/OctoPrint/src/octoprint/plugins/discovery
|
||||
| Hello World (1.0) = /home/pi/OctoPrint-HelloWorld/octoprint_helloworld
|
||||
|
||||
Much better! You can override pretty much all of the metadata defined within ``setup.py`` from within your Plugin itself --
|
||||
take a look at :ref:`the available control properties <sec-plugins-infrastructure-controlproperties>` for all available
|
||||
take a look at :ref:`the available control properties <sec-plugin-concepts-controlproperties>` for all available
|
||||
overrides.
|
||||
|
||||
Following the README of the `Plugin Skeleton <https://github.com/OctoPrint/OctoPrint-PluginSkeleton>`_ you could now
|
||||
|
|
|
|||
|
|
@ -1,24 +1,14 @@
|
|||
.. _sec-plugins:
|
||||
|
||||
#######
|
||||
Plugins
|
||||
#######
|
||||
|
||||
Starting with OctoPrint 1.2.0, there's now a plugin system in place which allows to individually
|
||||
extend OctoPrint's functionality.
|
||||
|
||||
Right now plugins can be used to extend OctoPrint's web interface, to execute specific tasks on server startup and
|
||||
shutdown, to provide custom (API) endpoints with special functionality, to react on system events or to add support for
|
||||
additional slicers. More plugin types are planned for the future.
|
||||
##################
|
||||
Developing Plugins
|
||||
##################
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 3
|
||||
|
||||
using.rst
|
||||
concepts.rst
|
||||
gettingstarted.rst
|
||||
infrastructure.rst
|
||||
templates.rst
|
||||
concepts.rst
|
||||
distributing.rst
|
||||
mixins.rst
|
||||
hooks.rst
|
||||
|
|
|
|||
|
|
@ -1,70 +0,0 @@
|
|||
.. _sec-plugins-infrastructure:
|
||||
|
||||
Plugin Infrastructure
|
||||
=====================
|
||||
|
||||
.. _sec-plugins-infrastructure-controlproperties:
|
||||
|
||||
Control Properties
|
||||
------------------
|
||||
|
||||
``__plugin_name__``
|
||||
Name of your plugin, optional, overrides the name specified in ``setup.py`` if provided.
|
||||
``__plugin_version__``
|
||||
Version of your plugin, optional, overrides the version specified in ``setup.py`` if provided.
|
||||
``__plugin_description__``
|
||||
Description of your plugin, optional, overrides the description specified in ``setup.py`` if provided.
|
||||
``__plugin_author__``
|
||||
Author of your plugin, optional, overrides the author specified in ``setup.py`` if provided.
|
||||
``__plugin_url__``
|
||||
URL of the webpage of your plugin, e.g. the Github repository, optional, overrides the URL specified in ``setup.py`` if
|
||||
provided.
|
||||
``__plugin_license__``
|
||||
License of your plugin, optional, overrides the license specified in ``setup.py`` if provided.
|
||||
``__plugin_implementation__``
|
||||
Instance of an implementation of one or more :ref:`plugin mixins <sec-plugins-mixins>`
|
||||
``__plugin_hooks__``
|
||||
Handlers for one or more of the various :ref:`plugin hooks <sec-plugins-hooks>`
|
||||
``__plugin_check__``
|
||||
Method called upon discovery of the plugin by the plugin subsystem, should return ``True`` if the
|
||||
plugin can be instantiated later on, ``False`` if there are reasons why not, e.g. if dependencies
|
||||
are missing.
|
||||
``__plugin_init__``
|
||||
Method called upon initializing of the plugin by the plugin subsystem, can be used to instantiate
|
||||
plugin implementations, connecting them to hooks etc.
|
||||
|
||||
.. _sec-plugins-infrastructure-injections:
|
||||
|
||||
Injected Properties
|
||||
-------------------
|
||||
|
||||
``self._identifier``
|
||||
The plugin's identifier.
|
||||
``self._plugin_name``
|
||||
The plugin's name, as taken from either the ``__plugin_name__`` control property or the package info.
|
||||
``self._plugin_version``
|
||||
The plugin's version, as taken from either the ``__plugin_version__`` control property or the package info.
|
||||
``self._basefolder``
|
||||
The plugin's base folder where it's installed. Can be used to refer to files relative to the plugin's installation
|
||||
location, e.g. included scripts, templates or assets.
|
||||
``self._logger``
|
||||
A `python logger instance <https://docs.python.org/2/library/logging.html>`_ logging to the log target
|
||||
``octoprint.plugin.<plugin identifier>``.
|
||||
``self._settings``
|
||||
The plugin's personalized settings manager, injected only into plugins that include the :class:`SettingsPlugin` mixin.
|
||||
``self._plugin_manager``
|
||||
OctoPrint's plugin manager.
|
||||
``self._printer_profile_manager``
|
||||
OctoPrint's printer profile manager.
|
||||
``self._event_bus``
|
||||
OctoPrint's event bus.
|
||||
``self._analysis_queue``
|
||||
OctoPrint's analysis queue for analyzing GCODEs or other files.
|
||||
``self._slicing_manager``
|
||||
OctoPrint's slicing manager.
|
||||
``self._file_manager``
|
||||
OctoPrint's file manager.
|
||||
``self._printer``
|
||||
OctoPrint's printer management object.
|
||||
``self._app_session_manager``
|
||||
OctoPrint's application session manager.
|
||||
|
|
@ -1,98 +0,0 @@
|
|||
.. _sec-plugins-templates:
|
||||
|
||||
Component Templates
|
||||
===================
|
||||
|
||||
OctoPrint allows plugins to extend the UI of OctoPrint through the use of the :class:`~octoprint.plugin.TemplatePlugin`
|
||||
mixin. By implementing this mixing and providing templates and their configuration through it, Plugins may currently
|
||||
create one or more of navbar, sidebar, tabs, settings and generic components.
|
||||
|
||||
.. figure:: ../images/template-plugin-types-main.png
|
||||
:align: center
|
||||
:alt: Template injection types in the main part of the interface
|
||||
|
||||
Template injection types in the main part of the interface
|
||||
|
||||
.. figure:: ../images/template-plugin-types-settings.png
|
||||
:align: center
|
||||
:alt: Template injection types in the settings
|
||||
|
||||
Template injection types in the settings
|
||||
|
||||
You can find an example for a simple plugin which injects navbar, sidebar, tab and settings content into the interface in
|
||||
`the "helloworld" plugin in OctoPrint's collection of plugin examples <https://github.com/OctoPrint/Plugin-Examples/tree/master/helloworld>`_.
|
||||
|
||||
.. _sec-plugins-templates-navbar:
|
||||
|
||||
Navbar
|
||||
------
|
||||
|
||||
The right part of the navigation bar located at the top of the UI can be enriched with additional links. Note that
|
||||
with the current implementation, plugins will always be located *to the left* of the existing links.
|
||||
|
||||
The included template must be called ``<pluginname>_navbar.jinja2`` (e.g. ``myplugin_navbar.jinja2``) unless
|
||||
overridden by the configuration supplied through :func:`get_template_configs`.
|
||||
|
||||
The template will be already wrapped into the necessary structure, plugins just need to supply the pure content. The
|
||||
wrapper structure will have all additional classes and styles applied as specified via the configuration supplied
|
||||
through :func:`get_template_configs`.
|
||||
|
||||
.. _sec-plugins-templates-sidebar:
|
||||
|
||||
Sidebar
|
||||
-------
|
||||
|
||||
The left side bar containing Connection, State and Files sections can be enriched with additional sections. Note
|
||||
that with the current implementations, plugins will always be located *beneath* the existing sections.
|
||||
|
||||
The included template must be called ``<pluginname>_sidebar.jinja2`` (e.g. ``myplugin_sidebar.jinja2``) unless
|
||||
overridden by the configuration supplied through :func:`get_template_configs`.
|
||||
|
||||
The template will be already wrapped into the necessary structure, plugins just need to supply the pure content. The
|
||||
wrapper divs for both the whole box as well as the content pane will have all additional classes and styles applied
|
||||
as specified via the configuration supplied through :func:`get_template_configs`.
|
||||
|
||||
.. _sec-plugins-templates-tabs:
|
||||
|
||||
Tabs
|
||||
----
|
||||
|
||||
The available tabs of the main part of the interface may be extended with additional tabs originating from within
|
||||
plugins. Note that with the current implementation, plugins will always be located *to the right* of the existing
|
||||
tabs.
|
||||
|
||||
The included template must be called ``<pluginname>_tab.jinja2`` (e.g. ``myplugin_tab.jinja2``) unless
|
||||
overridden by the configuration supplied through :func:`get_template_configs`.
|
||||
|
||||
The template will be already wrapped into the necessary structure, plugins just need to supply the pure content. The
|
||||
wrapper div and the link in the navigation will have the additional classes and styles applied as specified via the
|
||||
configuration supplied through :func:`get_template_configs`.
|
||||
|
||||
.. _sec-plugins-templates-settings:
|
||||
|
||||
Settings
|
||||
--------
|
||||
|
||||
Plugins may inject a dialog into the existing settings view. Note that with the current implementations, plugins
|
||||
will always be listed beneath the "Plugins" header in the settings link list, ordered alphabetically after
|
||||
their displayed name.
|
||||
|
||||
The included template must be called ``<pluginname>_settings.jinja2`` (e.g. ``myplugin_settings.jinja2``) unless
|
||||
overridden by the configuration supplied through :func:`get_template_configs`.
|
||||
|
||||
The template will be already wrapped into the necessary structure, plugins just need to supply the pure content. The
|
||||
wrapper div and the link in the navigation will have the additional classes and styles applied as defined via the
|
||||
supplied configuration supplied through :func:`get_template_configs`.
|
||||
|
||||
.. _sec-plugins-templates-generic:
|
||||
|
||||
Generic
|
||||
-------
|
||||
|
||||
Plugins may also inject arbitrary templates into the page of the web interface itself, e.g. in order to
|
||||
add overlays or dialogs to be called from within the plugin's javascript code.
|
||||
|
||||
.. _sec-plugins-templates-replacement:
|
||||
|
||||
Replacing existing components
|
||||
-----------------------------
|
||||
|
|
@ -1,44 +0,0 @@
|
|||
.. _sec-plugins-using:
|
||||
|
||||
*************
|
||||
Using Plugins
|
||||
*************
|
||||
|
||||
.. _sec-plugins-using-available:
|
||||
|
||||
Finding Plugins
|
||||
===============
|
||||
|
||||
Currently there's no such thing as a centralized plugin repository for available plugins.
|
||||
|
||||
Plugins may be found in the lists provided in `the OctoPrint wiki <https://github.com/foosel/OctoPrint/wiki#plugins>`_
|
||||
and on the `OctoPrint organization Github page <https://github.com/OctoPrint>`_.
|
||||
|
||||
.. _sec-plugins-using-installing:
|
||||
|
||||
Installing Plugins
|
||||
==================
|
||||
|
||||
Plugins can be installed either by unpacking them into one of the configured plugin folders (regularly those are
|
||||
``<octoprint-root>/plugins`` and ``~/.octoprint/plugins`` or by installing them as regular python modules via ``pip``.
|
||||
Please refer to the documentation of the plugin for installations instructions.
|
||||
|
||||
The latter is the more common case since all currently published plugins not bundled with OctoPrint can and should be installed
|
||||
this way.
|
||||
|
||||
For a plugin available on the Python Package Index (PyPi), the process is as simple as issuing a
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
pip install <plugin_name>
|
||||
|
||||
For plugins not available on PyPi, you'll have to give ``pip`` an URL from which to install the package (e.g. the URL to
|
||||
a ZIP file of the current master branch of a Github repository hosting a plugin, or even a ``git+https`` URL), example:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
pip install https://github.com/OctoPrint/OctoPrint-Growl/archive/master.zip
|
||||
|
||||
See `the pip install documentation <http://pip.readthedocs.org/en/latest/reference/pip_install.html>`_ for what URL
|
||||
types are possible.
|
||||
|
||||
|
|
@ -35,7 +35,7 @@ class PluginInfo(object):
|
|||
implementations, hooks and helpers.
|
||||
|
||||
It works on Python module objects and extracts the relevant data from those via accessing the
|
||||
:ref:`control properties <sec-plugins-infrastructure-controlproperties>`.
|
||||
:ref:`control properties <sec-plugin-concepts-controlproperties>`.
|
||||
|
||||
Arguments:
|
||||
key (str): Identifier of the plugin
|
||||
|
|
|
|||
Loading…
Reference in a new issue