From 3dc0452a45a7d9b518851ebee1489a7097de292f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gina=20H=C3=A4u=C3=9Fge?= Date: Wed, 3 Jun 2015 20:21:12 +0200 Subject: [PATCH] Adjusted docs to describe new web asset handling --- docs/configuration/config_yaml.rst | 11 +++++ docs/plugins/gettingstarted.rst | 75 ++++++++++++++++++++++-------- src/octoprint/plugin/types.py | 8 +++- src/octoprint/server/__init__.py | 3 +- 4 files changed, 75 insertions(+), 22 deletions(-) diff --git a/docs/configuration/config_yaml.rst b/docs/configuration/config_yaml.rst index c5dc8ab8..d2d60264 100644 --- a/docs/configuration/config_yaml.rst +++ b/docs/configuration/config_yaml.rst @@ -249,6 +249,17 @@ The following settings are only relevant to you if you want to do OctoPrint deve # Developers may specify less here too. stylesheet: css + # Settings for OctoPrint's web asset merging and minifying + webassets: + # If set to true, OctoPrint will merge all JS, all CSS and all Less files into one file per type + # to reduce request count. Setting it to false will load all assets individually. Note: if this is set to + # false, no minification will take place regardless of the minify setting below. + bundle: true + + # If set to true, OctoPrint will minify its viewmodels (that includes those of plugins). Note: if bundle is + # set to false, no minification will take place either. + minify: true + # Settings for the virtual printer virtualPrinter: diff --git a/docs/plugins/gettingstarted.rst b/docs/plugins/gettingstarted.rst index 8c9d0ddf..f571f40b 100644 --- a/docs/plugins/gettingstarted.rst +++ b/docs/plugins/gettingstarted.rst @@ -754,8 +754,21 @@ a reference to our CSS file: __plugin_name__ = "Hello World" __plugin_implementation__ = HelloWorldPlugin() +OctoPrint by default bundles all CSS, JavaScript and LESS files to reduce the amount of requests necessary to fully +load the page. But in order to fully be able to see how what we just did changes how our plugin interacts with OctoPrint +we want to disable that behaviour for now. Open up OctoPrint's ``config.yaml`` and disable bundling of the webassets: + +.. code-block:: yaml + :emphasize-lines: 2-4 + + # [...] + devel: + webassets: + bundle: false + # [...] + Restart OctoPrint, shift-reload your browser and take a look. Everything should still look like before, but now -OctoPrint linked to our stylesheet and the style information for the ``iframe`` is taken from that instead of +OctoPrint included our stylesheet and the style information for the ``iframe`` is taken from that instead of hardcoded in our template. Way better! Now, if you had something more complicated than just the couple of line of CSS we used here, you might want to use @@ -828,11 +841,13 @@ Then adjust our returned assets to include our LESS file as well: and enable LESS mode by adjusting one of OctoPrint's ``devel`` flags via the ``config.yaml`` file: .. code-block:: yaml - :emphasize-lines: 2-3 + :emphasize-lines: 3 # [...] devel: stylesheet: less + webassets: + bundle: false # [...] Restart OctoPrint and shift-reload. Your "Hello World" tab should still look like before. Take a look at the site's @@ -841,18 +856,14 @@ embedded the ``helloworld.less`` file instead: .. code-block:: html :linenos: - :emphasize-lines: 7 + :emphasize-lines: 5 - - - - - - - + + + @@ -866,23 +877,23 @@ setting it to ``css``, e.g. # [...] devel: stylesheet: css + webassets: + bundle: false # [...] Restart and shift-reload and take another look at the ``head``: .. code-block:: html :linenos: - :emphasize-lines: 7 + :emphasize-lines: 5 - - - - - - + + + + @@ -890,6 +901,32 @@ Now the CSS file is linked and no trace of the LESS links is left in the source. tremendously when you have to work with complex stylesheets, just don't forgot to check the generated CSS file in with the rest of your plugin or people will miss it when trying to run your plugin! +Remember when I mentioned that OctoPrint by default bundles all our assets for us? We adjusted our ``config.yaml`` to +stop it from doing that at the start of this section, we should switch this back now: + +.. code-block:: yaml + + # [...] + devel: + stylesheet: css + # [...] + +Just out of curiousity, restart, shift-reload and take a final look at the ``head``: + +.. code-block:: html + :linenos: + :emphasize-lines: 3-5 + + + + + + + + + +Way more compact, isn't it? + .. note:: If your plugin only provides CSS files, OctoPrint will detect this when switched to LESS mode and include your @@ -897,8 +934,8 @@ the rest of your plugin or people will miss it when trying to run your plugin! as soon as you need it just switch over. The same thing works the other way around too btw. If your plugin only provides LESS files, OctoPrint will link to - those and add lessjs to the page as well. Please keep in mind though that also providing CSS files is the cleaner - way. + those, lessjs will take care of the compilation. Please keep in mind though that also providing CSS files is the + cleaner way. Where do we go from here? ------------------------- diff --git a/src/octoprint/plugin/types.py b/src/octoprint/plugin/types.py index e40ec44f..72ffcc5a 100644 --- a/src/octoprint/plugin/types.py +++ b/src/octoprint/plugin/types.py @@ -163,9 +163,12 @@ class AssetPlugin(OctoPrintPlugin, RestartNeedingPlugin): less=['less/my_styles.less'] ) - The assets will be made available by OctoPrint under the URL ``/plugin_assets//``, with + The assets will be made available by OctoPrint under the URL ``/plugin//static/``, with ``plugin identifier`` being the plugin's identifier and ``path`` being the path as defined in the asset dictionary. + Assets of the types ``js``, ``css`` and ``less`` will be automatically bundled by OctoPrint using + `Flask-Assets `_. + :return dict: a dictionary describing the static assets to publish for the plugin """ return dict() @@ -670,7 +673,8 @@ class BlueprintPlugin(OctoPrintPlugin, RestartNeedingPlugin): def is_blueprint_protected(self): """ - Whether a valid API key is needed to access the blueprint (the default) or not. + Whether a valid API key is needed to access the blueprint (the default) or not. Note that this only restricts + access to the blueprint's dynamic methods, static files are always accessible without API key. """ return True diff --git a/src/octoprint/server/__init__.py b/src/octoprint/server/__init__.py index fb79db2f..d29e20e5 100644 --- a/src/octoprint/server/__init__.py +++ b/src/octoprint/server/__init__.py @@ -748,8 +748,9 @@ class Server(): css_libs_bundle = Bundle(*css_libs, output="webassets/packed_libs.css") css_app_bundle = Bundle(*css_app, output="webassets/packed_app.css") + all_css_bundle = Bundle(css_libs_bundle, css_app_bundle, output="webassets/packed.css") - all_less_bundle = Bundle(*less_app, output="webassets/packed_app.less") + all_less_bundle = Bundle(*less_app, output="webassets/packed.less") assets.register("all_js", all_js_bundle) assets.register("all_css", all_css_bundle)