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. # Developers may specify less here too.
stylesheet: css 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 # Settings for the virtual printer
virtualPrinter: virtualPrinter:

75
docs/plugins/gettingstarted.rst
View file

@ -754,8 +754,21 @@ a reference to our CSS file:
__plugin_name__ = "Hello World" __plugin_name__ = "Hello World"
__plugin_implementation__ = HelloWorldPlugin() __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 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! 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 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: and enable LESS mode by adjusting one of OctoPrint's ``devel`` flags via the ``config.yaml`` file:
.. code-block:: yaml .. code-block:: yaml
:emphasize-lines: 2-3 :emphasize-lines: 3
# [...] # [...]
devel: devel:
stylesheet: less 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 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 .. code-block:: html
:linenos: :linenos:
:emphasize-lines: 7 :emphasize-lines: 5
<head> <head>
<!-- [...] --> <!-- [...] -->
<link href="/static/less/octoprint.less" rel="stylesheet/less" type="text/css" media="screen"> <link href="/static/less/octoprint.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">
<!-- [...] --> <!-- [...] -->
<link href="/plugin_assets/helloworld/less/helloworld.less" rel="stylesheet/less" type="text/css" media="screen">
<!-- [...] -->
<!-- /Plugin files -->
<script src="/static/js/lib/less.min.js" type="text/javascript"></script> <script src="/static/js/lib/less.min.js" type="text/javascript"></script>
<!-- [...] --> <!-- [...] -->
</head> </head>
@ -866,23 +877,23 @@ setting it to ``css``, e.g.
# [...] # [...]
devel: devel:
stylesheet: css stylesheet: css
webassets:
bundle: false
# [...] # [...]
Restart and shift-reload and take another look at the ``head``: Restart and shift-reload and take another look at the ``head``:
.. code-block:: html .. code-block:: html
:linenos: :linenos:
:emphasize-lines: 7 :emphasize-lines: 5
<head> <head>
<!-- [...] --> <!-- [...] -->
<link href="/static/css/octoprint.css" rel="stylesheet" type="text/css" media="screen"> <link href="/static/css/octoprint.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">
<!-- [...] --> <!-- [...] -->
<link href="/plugin_assets/helloworld/css/helloworld.css" rel="stylesheet" type="text/css" media="screen"> <script src="/static/js/lib/less.min.js" type="text/javascript"></script>
<!-- [...] -->
<!-- /Plugin files -->
<!-- [...] --> <!-- [...] -->
</head> </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 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! 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:: .. note::
If your plugin only provides CSS files, OctoPrint will detect this when switched to LESS mode and include your 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. 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 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 those, lessjs will take care of the compilation. Please keep in mind though that also providing CSS files is the
way. cleaner way.
Where do we go from here? 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'] 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. ``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: a dictionary describing the static assets to publish for the plugin
""" """
return dict() return dict()
@ -670,7 +673,8 @@ class BlueprintPlugin(OctoPrintPlugin, RestartNeedingPlugin):
def is_blueprint_protected(self): 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 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_libs_bundle = Bundle(*css_libs, output="webassets/packed_libs.css")
css_app_bundle = Bundle(*css_app, output="webassets/packed_app.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_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_js", all_js_bundle)
assets.register("all_css", all_css_bundle) assets.register("all_css", all_css_bundle)