display loaded plugins in footer

Makefile

@@ -15,13 +15,14 @@ test:
 # ---- Documentation ---
 
 update-docs:
-	pip3 install sphinx==3.5.4 sphinxcontrib.httpdomain  # sphinx4 is not supported yet by sphinx-contrib/httpdomain, see https://github.com/sphinx-contrib/httpdomain/issues/46
+	pip3 install sphinx==3.5.4 sphinxcontrib.httpdomain sphinx-rtd-theme  # sphinx4 is not supported yet by sphinx-contrib/httpdomain, see https://github.com/sphinx-contrib/httpdomain/issues/46
 	cd documentation; make clean; make html; cd ..
 
 update-docs-pdf:
 	@echo "NOTE: PDF documentation requires packages (on Debian: latexmk texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended)"
 	@echo "NOTE: Currently, the docs require some pictures which are not in the git repo atm. Ask the devs."
-	pip3 install sphinx sphinx-rtd-theme sphinxcontrib.httpdomain
+	pip3 install sphinx sphinxcontrib.httpdomain sphinx-rtd-theme
+
 	cd documentation; make clean; make latexpdf; make latexpdf; cd ..  # make latexpdf can require two passes
 
 # ---- Installation ---

documentation/changelog.rst

@@ -12,6 +12,7 @@ New features
 -----------
 * Allow plugins to overwrite UI routes and customise the teaser on the login form [see `PR #106 <http://www.github.com/SeitaBV/flexmeasures/pull/106>`_]
 * Allow plugins to customise the copyright notice and credits in the UI footer [see `PR #123 <http://www.github.com/SeitaBV/flexmeasures/pull/123>`_]
+* Display loaded plugins in footer and support plugin versioning [see `PR #139 <http://www.github.com/SeitaBV/flexmeasures/pull/139>`_]
 
 Bugfixes
 -----------

documentation/dev/plugins.rst

@@ -17,7 +17,7 @@ Use the config setting :ref:`plugin-config` to point to your plugin(s).
 
 Here are the assumptions FlexMeasures makes to be able to import your Blueprint:
 
-- The plugin folder contains an __init__.py file.
+- The plugin folder contains an ``__init__.py`` file.
 - In this init, you define a Blueprint object called ``<plugin folder>_bp``.
 
 We'll refer to the plugin with the name of your plugin folder.
@@ -26,14 +26,14 @@ We'll refer to the plugin with the name of your plugin folder.
 Showcase
 ^^^^^^^^^
 
-Here is a showcase file which constitutes a FlexMeasures plugin. We imagine that we made a plugin to implement some custom logic for a client. 
+Here is a showcase file which constitutes a FlexMeasures plugin called ``our_client``.
 
-We created the file ``<some_folder>/our_client/__init__.py``. So, ``our_client`` is the plugin folder and becomes the plugin name.
-All else that is needed for this showcase (not shown here) is ``<some_folder>/our_client/templates/metrics.html``, which works just as other FlexMeasures templates (they are Jinja2 templates and you can start them with ``{% extends "base.html" %}`` for integration into the FlexMeasures structure).
+* We demonstrate adding a view, which can be rendered using the FlexMeasures base templates.
+* We also showcase a CLI function which has access to the FlexMeasures `app` object. It can be called via ``flexmeasures our_client test``. 
 
+We first create the file ``<some_folder>/our_client/__init__.py``. This means that ``our_client`` is the plugin folder and becomes the plugin name.
 
-* We demonstrate adding a view which can be rendered via the FlexMeasures base templates.
-* We also showcase a CLI function which has access to the FlexMeasures `app` object. It can be called via ``flexmeasures our_client test``. 
+With the ``__init__.py`` below, plus the custom Jinja2 template, ``our_client`` is a complete plugin.
 
 .. code-block:: python
 
@@ -46,17 +46,18 @@ All else that is needed for this showcase (not shown here) is ``<some_folder>/ou
     our_client_bp = Blueprint('our_client', 'our_client',
                               template_folder='templates')
 
+    __version__ = "2.0"
 
     # Showcase: Adding a view
 
     @our_client_bp.route('/')
-    @our_client_bp.route('/metrics')
+    @our_client_bp.route('/my-page')
     @login_required
     def metrics():
-        msg = "I am part of FM !"
+        msg = "I am a FlexMeasures plugin !"
         # Note that we render via the in-built FlexMeasures way
         return render_flexmeasures_template(
-            "metrics.html",
+            "my_page.html",
             message=msg,
         )
 
@@ -76,16 +77,73 @@ All else that is needed for this showcase (not shown here) is ``<some_folder>/ou
         print(f"I am a CLI command, part of FlexMeasures: {current_app}")
 
 
-.. note:: You can overwrite FlexMeasures routes here. In our example above, we set the root route ``/``. FlexMeasures registers plugin routes before its own, so in this case visiting the root URL of your app will display this plugged-in view (the same you'd see at `/metrics`).
+.. note:: You can overwrite FlexMeasures routing in your plugin. In our example above, we are using the root route ``/``. FlexMeasures registers plugin routes before its own, so in this case visiting the root URL of your app will display this plugged-in view (the same you'd see at `/my-page`).
+
+.. note:: The ``__version__`` attribute is being displayed in the standard FlexMeasures UI footer, where we show loaded plugins. Of course, it can also be useful for your own maintenance.
+
+
+The template would live at ``<some_folder>/our_client/templates/my_page.html``, which works just as other FlexMeasures templates (they are Jinja2 templates):
+
+.. code-block:: html
+
+    {% extends "base.html" %}
+
+    {% set active_page = "my-page" %}
+
+    {% block title %} Our client Dashboard {% endblock %}
+
+    {% block divs %}
+
+        <!-- This is where your custom content goes... -->
+
+        {{ message }}
+
+    {% endblock %}
+
+
+.. note:: Plugin views can also be added to the FlexMeasures UI menu ― just name them in the config setting :ref:`menu-config`. In this example, add ``my-page``. This also will make the ``active_page`` setting in the above template useful (highlights the current page in the menu).
+
+Starting the template with ``{% extends "base.html" %}`` integrates your page content into the FlexMeasures UI structure. You can also extend a different base template. For instance, we find it handy to extend ``base.html`` with a custom base template, to extend the footer, as shown below:
+
+ .. code-block:: html
+
+    {% extends "base.html" %}
+
+    {% block copyright_notice %}
+
+    Created by <a href="https://seita.nl/">Seita Energy Flexibility</a>,
+    in cooperation with <a href="https://ourclient.nl/">Our Client</a>
+    &copy
+    <script>var CurrentYear = new Date().getFullYear(); document.write(CurrentYear)</script>.
+
+    {% endblock copyright_notice %}
 
-.. note:: Plugin views can also be added to the FlexMeasures UI menu ― just name them in the config setting :ref:`menu-config`.
+We'd name this file ``our_client_base.html``. Then, we'd extend our page template from ``our_client_base.html``, instead of ``base.html``.
+
+
+Using other files in your plugin
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Say you want to include other Python files in your plugin, importing them in your ``__init__.py`` file.
+This can be done if you put the plugin path on the import path. Do it like this in your ``__init__.py``:
 
-Validating data with marshmallow
+.. code-block:: python
+
+    import os
+    import sys
+
+    HERE = os.path.dirname(os.path.abspath(__file__))
+    sys.path.insert(0, HERE)
+
+    from my_other_file import my_function
+
+
+Validating arguments in your CLI commands with marshmallow
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-FlexMeasures validates input data using `marshmallow <https://marshmallow.readthedocs.io/>`_.
-Data fields can be made suitable for use in CLI commands through our ``MarshmallowClickMixin``.
-An example:
+Arguments to CLI commands can be validated using `marshmallow <https://marshmallow.readthedocs.io/>`_.
+FlexMeasures is using this functionality (via the ``MarshmallowClickMixin`` class) and also defines some custom field schemas.
+We demonstrate this here, and also show how you can add your own custom field schema:
 
 .. code-block:: python
 
@@ -97,14 +155,17 @@ An example:
     from flexmeasures.data.schemas.utils import MarshmallowClickMixin
     from marshmallow import fields
 
-    class StrField(fields.Str, MarshmallowClickMixin):
-        """String field validator usable for UI routes and CLI functions."""
+    class CLIStrField(fields.Str, MarshmallowClickMixin):
+        """
+        String field validator, made usable for CLI functions.
+        You could also define your own validations here.
+        """
 
     @click.command("meet")
     @click.option(
         "--where",
         required=True,
-        type=StrField(),  # see above: we just made this field suitable for CLI functions
+        type=CLIStrField(),
         help="(Required) Where we meet",
     )
     @click.option(
@@ -120,24 +181,7 @@ An example:
         print(f"Okay, see you {where} on {when}.")
 
 
-Using other files in your plugin
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Say you want to include other Python files in your plugin, importing them in your ``__init__.py`` file.
-This can be done if you put the plugin path on the import path. Do it like this in your ``__init__.py``:
-
-.. code-block:: python
-
-    import os
-    import sys
-
-    HERE = os.path.dirname(os.path.abspath(__file__))
-    sys.path.insert(0, HERE)
-
-    from my_other_file import my_function
-
-
-Customising the login teaser
+Customising the login page teaser
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 FlexMeasures shows an image carousel next to its login form (see ``ui/templates/admin/login_user.html``).
@@ -158,4 +202,6 @@ Place this template file in the template folder of your plugin blueprint (see ab
 
 Finally, add this config setting to your FlexMeasures config file (using the template filename you chose, obviously):
 
+ .. code-block:: bash
+
     SECURITY_LOGIN_USER_TEMPLATE = "my_user_login.html"

flexmeasures/ui/templates/base.html

@@ -284,7 +284,7 @@ <h3>Icons from <a href="https://www.flaticon.com/" title="Flaticon">Flaticon</a>
                 {% endif %}
                 {% if not current_user.has_role('anonymous') %}
                     {% if flexmeasures_version %}
-                        on version {{ flexmeasures_version }}
+                        on version {{ flexmeasures_version }}.
                     {% else %}
                         {% if git_version != "Unknown" %}
                         on version {{ git_version }}+{{ git_commits_since }}.
@@ -293,6 +293,9 @@ <h3>Icons from <a href="https://www.flaticon.com/" title="Flaticon">Flaticon</a>
                         {% endif %}
                     {% endif %}
                 {% endif %}
+                {% if loaded_plugins %}
+                    Loaded plugins: {{ loaded_plugins }}.
+                {% endif %}
             </div>
             <div>
                 <a href="https://seita.nl/"><i class="icon-seita_bird supersize"></i></a>

flexmeasures/ui/utils/view_utils.py

@@ -71,6 +71,10 @@ def render_flexmeasures_template(html_filename: str, **variables):
     ) = get_git_description()
     app_start_time = current_app.config.get("START_TIME")
     variables["app_running_since"] = time_utils.naturalized_datetime_str(app_start_time)
+    variables["loaded_plugins"] = ",".join(
+        f"{p_name} (v{p_version})"
+        for p_name, p_version in current_app.config.get("LOADED_PLUGINS", {}).items()
+    )
 
     variables["user_is_logged_in"] = current_user.is_authenticated
     variables[

flexmeasures/utils/app_utils.py

@@ -84,6 +84,7 @@ def register_plugins(app: Flask):
             f"The value of FLEXMEASURES_PLUGIN_PATHS is not a list: {plugin_paths}. Cannot install plugins ..."
         )
         return
+    app.config["LOADED_PLUGINS"] = {}
     for plugin_path in plugin_paths:
         plugin_name = plugin_path.split("/")[-1]
         if not os.path.exists(os.path.join(plugin_path, "__init__.py")):
@@ -95,9 +96,11 @@ def register_plugins(app: Flask):
         spec = importlib.util.spec_from_file_location(
             plugin_name, os.path.join(plugin_path, "__init__.py")
         )
-        app.logger.debug(spec)
         module = importlib.util.module_from_spec(spec)
-        app.logger.debug(module)
         sys.modules[plugin_name] = module
         spec.loader.exec_module(module)
-        app.register_blueprint(getattr(module, f"{plugin_name}_bp"))
+        plugin_blueprint = getattr(module, f"{plugin_name}_bp")
+        app.register_blueprint(plugin_blueprint)
+        plugin_version = getattr(plugin_blueprint, "__version__", "0.1")
+        app.config["LOADED_PLUGINS"][plugin_name] = plugin_version
+    app.logger.info(f"Loaded plugins: {app.config['LOADED_PLUGINS']}")