From fde543f19e4e19ca63645ed1b5b6d7ea3c2b895c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gina=20H=C3=A4u=C3=9Fge?= Date: Mon, 8 Jun 2015 12:05:29 +0200 Subject: [PATCH] [doc] octoprint.ui.web.templatetypes hook is now documented --- docs/plugins/hooks.rst | 115 +++++++++++++++++++++++++++++++++- src/octoprint/plugin/types.py | 11 ++-- src/octoprint/server/views.py | 5 +- 3 files changed, 123 insertions(+), 8 deletions(-) diff --git a/docs/plugins/hooks.rst b/docs/plugins/hooks.rst index 9e4b7e1a..6096fc86 100644 --- a/docs/plugins/hooks.rst +++ b/docs/plugins/hooks.rst @@ -405,4 +405,117 @@ octoprint.server.http.routes :param list server_routes: read-only list of the currently configured server routes :return: a list of 3-tuples with additional routes as defined above - :rtype: list \ No newline at end of file + :rtype: list + +.. _sec-plugins-hook-ui-web-templatetypes: + +octoprint.ui.web.templatetypes +------------------------------ + +.. py:function:: hook(template_sorting, template_rules, *args, **kwargs) + + Allows extending the set of supported template types in the web interface. This is interesting for plugins which want + to offer other plugins to hook into their own offered UIs. Handlers must return a list of additional template + specifications in form of 3-tuples. + + The first entry of the tuple must be the name of the template type and will be automatically prefixed with + ``plugin__``. + + The second entry must be a sorting specification that defines how OctoPrint should sort multiple templates injected + through plugins of this template type. The sorting specification should be a dict with the following possible + entries: + + .. list-table:: + :widths: 5 95 + + * - **Key** + - **Description** + * - key + - The sorting key within the template config to use for sorting the list of template injections. This may be + ``None`` in which case no sorting will be taking place. Defaults to ``name``. + * - add + - Usually irrelevant for custom template types, only listed for the sake of completeness. The method of adding + the sorted list of template injections from plugins to the template injections from the + core. May be ``append`` to append the list, ``prepend`` to prepend the list, or ``custom_append`` or + ``custom_prepend`` to append respectively prepend but going so after preprocessing the entries and order data + with custom functions (e.g. to inject additional entries such as the "Plugins" section header in the settings + dialog). For custom template types this defaults to ``append``. + * - custom_add_entries + - Usually irrelevant for custom template types, only listed for the sake of completeness. Custom preprocessor + for the entries provided through plugins, before they are added to the general template entries + context variable for the current template type. + * - custom_add_order + - Usually irrelevant for custom template types, only listed for the sake of completeness. Custom preprocessor + for the template order provided through plugins, before they are added to the general template order + context variable for the current template type. + + The third entry must be a rule specification in form of a dict which tells OctoPrint how to process the template + configuration entries provided by :func:`~octoprint.plugin.TemplatePlugin.get_template_configs` by providing + transformation functions of various kinds: + + .. list-table:: + :widths: 5 95 + + * - **Key** + - **Description** + * - div + - Function that returns the id of the container for template content if not explicitely provided by the template + config, input parameter is the name of the plugin providing the currently processed template config. If not + provided this defaults to a lambda function of the form ``lambda x: "_