pingu_98/MrDraw
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Adjusted docs to describe new web asset handling

Browse source
This commit is contained in:
Gina Häußge 2015-06-03 20:21:12 +02:00
parent 261f6709a3
commit 3dc0452a45
4 changed files with 75 additions and 22 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

11
docs/configuration/config_yaml.rst
View file

@ -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:

75
docs/plugins/gettingstarted.rst
View file

@ -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
<head>
<!-- [...] -->
<link href="/static/less/octoprint.less" rel="stylesheet/less" type="text/css" media="screen">
<!-- Plugin files -->
<!-- [...] -->
<link href="/plugin_assets/helloworld/less/helloworld.less" rel="stylesheet/less" type="text/css" media="screen">
<!-- [...] -->
<!-- /Plugin files -->
<!-- [...] -->
<link href="/plugin/helloworld/static/less/helloworld.less" rel="stylesheet/less" type="text/css" media="screen">
<!-- [...] -->
<script src="/static/js/lib/less.min.js" type="text/javascript"></script>
<!-- [...] -->
</head>
@ -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
<head>
<!-- [...] -->
<link href="/static/css/octoprint.css" rel="stylesheet" type="text/css" media="screen">
<!-- Plugin files -->
<!-- [...] -->
<link href="/plugin_assets/helloworld/css/helloworld.css" rel="stylesheet" type="text/css" media="screen">
<!-- [...] -->
<!-- /Plugin files -->
<!-- [...] -->
<link href="/plugin/helloworld/static/css/helloworld.css" rel="stylesheet" type="text/css" media="screen">
<!-- [...] -->
<script src="/static/js/lib/less.min.js" type="text/javascript"></script>
<!-- [...] -->
</head>
@ -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
<head>
<!-- [...] -->
<link href="/static/webassets/packed.css?85a134" rel="stylesheet" type="text/css" media="screen">
<link href="/static/webassets/packed.less?85a134" rel="stylesheet/less" type="text/css" media="screen">
<script src="/static/js/lib/less.min.js" type="text/javascript"></script>
<!-- [...] -->
</head>
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?
-------------------------

8
src/octoprint/plugin/types.py
View file

@ -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/<plugin identifier>/<path>``, with
The assets will be made available by OctoPrint under the URL ``/plugin/<plugin identifier>/static/<path>``, 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 <http://flask-assets.readthedocs.org/en/latest/>`_.
: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

3
src/octoprint/server/__init__.py
View file

@ -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)