@@ -393,6 +406,7 @@ Now adjust your ``templates/helloworld_navbar.jinja2`` file to use a ``data-bind
settings view model into the ``href`` attribute of the link tag:
.. code-block:: html
+ :linenos:
Hello World!
@@ -415,6 +429,7 @@ again since we don't use that anymore:
.. code-block:: python
:emphasize-lines: 15-19
+ :linenos:
# coding=utf-8
from __future__ import absolute_import
@@ -458,4 +473,434 @@ Nice! Edit the value, then click "Save". Your link in the navigation bar should
not storing a copy of the settings data while it is being edited, which might be changed in the future to
prevent this unexpected behaviour from occurring.
-Congratulations, you've just made your Plugin configurable :)
\ No newline at end of file
+Congratulations, you've just made your Plugin configurable :)
+
+More frontend fun: Adding custom javascript to your frontend components
+-----------------------------------------------------------------------
+
+In the previous section we set that ``custom_bindings`` parameter to ``False`` since we wanted OctoPrint to bind the
+``SettingsViewModel`` to our settings dialog and the ``NavigationViewModel`` to our entry in the nav bar.
+
+But what if we want to define our own, with more functionality that is already available? Let's take a look. We'll now
+add an additional UI component to our OctoPrint interface, a custom tab. It will act as a little internal web browser,
+showing the website behind the URL from the settings in an IFrame but also allowing the user to load a different URL
+without having to change the settings.
+
+First let us create the Jinja2 template for our tab. In your plugin's ``templates`` folder create a new file
+``helloworld_tab.jinja2`` like so:
+
+.. code-block:: html
+ :linenos:
+
+
+ {{ _('Go') }}
+
+
+
+
+
+Then we create a new folder in your plugin's root called ``static`` and within that folder another folder by the name of
+``js``. Finally, within that folder create a file ``helloworld.js``. Our plugin's folder structure should now
+look like this::
+
+ octoprint_helloworld/
+ static/
+ js/
+ helloworld.js
+ templates/
+ helloworld_navbar.jinja2
+ helloworld_settings.jinja2
+ helloworld_tab.jinja2
+ __init__.py
+ README.md
+ requirements.txt
+ setup.py
+
+We need to tell OctoPrint about this new static asset so that it will properly inject it into the page. For this we
+just need to subclass :class:`~octoprint.plugin.AssetPlugin` and override its method :func:`~octoprint.plugin.AssetPlugin.get_assets`
+like so:
+
+.. code-block:: python
+ :emphasize-lines: 9,22-25
+ :linenos:
+
+ # coding=utf-8
+ from __future__ import absolute_import
+
+ import octoprint.plugin
+
+ class HelloWorldPlugin(octoprint.plugin.StartupPlugin,
+ octoprint.plugin.TemplatePlugin,
+ octoprint.plugin.SettingsPlugin,
+ octoprint.plugin.AssetPlugin):
+ def on_after_startup(self):
+ self._logger.info("Hello World! (more: %s)" % self._settings.get(["url"]))
+
+ def get_settings_defaults(self):
+ return dict(url="https://en.wikipedia.org/wiki/Hello_world")
+
+ def get_template_configs(self):
+ return [
+ dict(type="navbar", custom_bindings=False),
+ dict(type="settings", custom_bindings=False)
+ ]
+
+ def get_assets(self):
+ return dict(
+ js=["js/helloworld.js"]
+ )
+
+ __plugin_name__ = "Hello World"
+ __plugin_implementations__ = [HelloWorldPlugin()]
+
+Note how we did not add another entry to the return value of :func:`~octoprint.plugin.TemplatePlugin.get_template_configs`.
+Remember how we only added those since we wanted OctoPrint to use existing bindings on our navigation bar and settings
+menu entries? We don't want this this time, and we named our tab template such that OctoPrint will pick it up automatically
+so we don't have to do anything here.
+
+Then we'll create our custom `Knockout
`_ view model in ``helloworld.js``
+like so:
+
+.. code-block:: javascript
+ :linenos:
+
+ $(function() {
+ function HelloWorldViewModel(parameters) {
+ var self = this;
+
+ self.settings = parameters[0];
+
+ // this will hold the URL currently displayed by the iframe
+ self.currentUrl = ko.observable();
+
+ // this will hold the URL entered in the text field
+ self.newUrl = ko.observable();
+
+ // this will be called when the user clicks the "Go" button and set the iframe's URL to
+ // the entered URL
+ self.goToUrl = function() {
+ self.currentUrl(self.newUrl());
+ };
+
+ // This will get called before the HelloWorldViewModel gets bound to the DOM, but after its
+ // dependencies have already been initialized. It is especially guaranteed that this method
+ // gets called _after_ the settings have been retrieved from the OctoPrint backend and thus
+ // the SettingsViewModel been properly populated.
+ self.onBeforeBinding = function() {
+ self.newUrl(self.settings.settings.plugins.helloworld.url());
+ self.goToUrl();
+ }
+ }
+
+ // This is how our plugin registers itself with the application, by adding some configuration
+ // information to the global variable ADDITIONAL_VIEWMODELS
+ ADDITIONAL_VIEWMODELS.push([
+ // This is the constructor to call for instantiating the plugin
+ HelloWorldViewModel,
+
+ // This is a list of dependencies to inject into the plugin, the order which you request
+ // here is the order in which the dependencies will be injected into your view model upon
+ // instantiation via the parameters argument
+ ["settingsViewModel"],
+
+ // Finally, this is the list of all elements we want this view model to be bound to.
+ [document.getElementById("tab_plugin_helloworld")]
+ ]);
+ });
+
+Take a close look at lines 29 to 40. This is how our plugin tells OctoPrint about our new view model, how to
+instantiate it, which dependencies to inject and to which elements in the final page to bind. Since we want to access
+the URL from the settings of our plugin, we'll have OctoPrint inject the ``SettingsViewModel`` into our own view model,
+which is registered within OctoPrint under the name ``settingsViewModel``. We'll only bind to our custom tab
+for now, which OctoPrint will make available in a container with the id ``tab_plugin_helloworld`` (unless otherwise
+configured).
+
+Our view model defines two observables: ``newUrl``, which we bound to the input field in our template, and ``currentUrl``
+which we bound to the ``src`` attribute of the "browser iframe" in our template. There's also a function ``goToUrl``
+which we bound to the click event of the "Go" button in our template.
+
+Restart OctoPrint and shift-reload the browser. You should see a shiny new "Hello World" tab right at the end of the
+tab bar. Click on it!
+
+.. _fig-plugins-gettingstarted-helloworld_tab:
+.. figure:: ../images/plugins_gettingstarted_helloworld_tab.png
+ :align: center
+ :alt: Our "Hello World" tab in action
+
+The desktop version of that article looks a bit squished in there, so let's enter ``https://de.m.wikipedia.org/wiki/Hallo-Welt-Programm``
+into the input field and click the "Go" button. The page inside the iframe should be replaced with the mobile version
+of the same article.
+
+Style matters: Injecting custom CSS into the page
+-------------------------------------------------
+
+So it appears that this stuff is working great already. Only one thing is a bit ugly, let's take another look at
+our ``helloworld_tab.jinja2``:
+
+.. code-block:: html
+ :linenos:
+ :emphasize-lines: 6
+
+
+ {{ _('Go') }}
+
+
+
+
+We hardcoded some ``style`` on our ``iframe`` in line 6, to make it look a bit better. It would be nicer if that was actually
+located inside a stylesheet instead of directly inside our HTML template. Of course that's no problem, we'll just
+add a CSS file to our plugin's provided static assets.
+
+First we'll create a new folder within our plugin's ``static`` folder called ``css`` and within that folders a file
+``helloworld.css``. Our plugin's file structure should now look like this::
+
+ octoprint_helloworld/
+ static/
+ css/
+ helloworld.css
+ js/
+ helloworld.js
+ templates/
+ helloworld_navbar.jinja2
+ helloworld_settings.jinja2
+ helloworld_tab.jinja2
+ __init__.py
+ README.md
+ requirements.txt
+ setup.py
+
+
+Put something like the following into ``helloworld.css``:
+
+.. code-block:: css
+ :linenos:
+
+ #tab_plugin_helloworld {
+ iframe {
+ width: 100%;
+ height: 600px;
+ border: 1px solid #808080;
+ }
+ }
+
+Don't forget to remove the ``style`` attribute from the ``iframe`` tag in ``helloworld_tab.jinja2``:
+
+.. code-block:: html
+ :linenos:
+ :emphasize-lines: 6
+
+
+ {{ _('Go') }}
+
+
+
+
+Then adjust our plugin's ``__init__.py`` so that the :func:`~octoprint.plugin.AssetPlugin.get_assets` method returns
+a reference to our CSS file:
+
+.. code-block:: python
+ :emphasize-lines: 26
+ :linenos:
+
+ # coding=utf-8
+ from __future__ import absolute_import
+
+ import octoprint.plugin
+
+ class HelloWorldPlugin(octoprint.plugin.StartupPlugin,
+ octoprint.plugin.TemplatePlugin,
+ octoprint.plugin.SettingsPlugin,
+ octoprint.plugin.AssetPlugin):
+
+ def on_after_startup(self):
+ self._logger.info("Hello World! (more: %s)" % self._settings.get(["url"]))
+
+ def get_settings_defaults(self):
+ return dict(url="https://en.wikipedia.org/wiki/Hello_world")
+
+ def get_template_configs(self):
+ return [
+ dict(type="navbar", custom_bindings=False),
+ dict(type="settings", custom_bindings=False)
+ ]
+
+ def get_assets(self):
+ return dict(
+ js=["js/helloworld.js"],
+ css=["css/helloworld.css"]
+ )
+
+ __plugin_name__ = "Hello World"
+ __plugin_implementations__ = [HelloWorldPlugin()]
+
+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
+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
+something like LESS for generating your CSS from. If you use `LESS `_),
+which makes development so much easier. Let's try that, so you know how it works for future bigger projects.
+
+Add another folder to our ``static`` folder called ``less`` and within that create a file ``helloworld.less``. Put
+into that the same content as into our CSS file. Compile that LESS file to CSS [#f1]_, overwriting our old ``helloworld.css``
+in the process. The folder structure of our plugin should now look like this::
+
+ octoprint_helloworld/
+ static/
+ css/
+ helloworld.css
+ js/
+ helloworld.js
+ less/
+ helloworld.less
+ templates/
+ helloworld_navbar.jinja2
+ helloworld_settings.jinja2
+ helloworld_tab.jinja2
+ __init__.py
+ README.md
+ requirements.txt
+ setup.py
+
+
+Then adjust our returned assets to include our LESS file as well:
+
+.. code-block:: python
+ :emphasize-lines: 27
+ :linenos:
+
+ # coding=utf-8
+ from __future__ import absolute_import
+
+ import octoprint.plugin
+
+ class HelloWorldPlugin(octoprint.plugin.StartupPlugin,
+ octoprint.plugin.TemplatePlugin,
+ octoprint.plugin.SettingsPlugin,
+ octoprint.plugin.AssetPlugin):
+
+ def on_after_startup(self):
+ self._logger.info("Hello World! (more: %s)" % self._settings.get(["url"]))
+
+ def get_settings_defaults(self):
+ return dict(url="https://en.wikipedia.org/wiki/Hello_world")
+
+ def get_template_configs(self):
+ return [
+ dict(type="navbar", custom_bindings=False),
+ dict(type="settings", custom_bindings=False)
+ ]
+
+ def get_assets(self):
+ return dict(
+ js=["js/helloworld.js"],
+ css=["css/helloworld.css"],
+ less=["less/helloworld.less"]
+ )
+
+ __plugin_name__ = "Hello World"
+ __plugin_implementations__ = [HelloWorldPlugin()]
+
+
+and enable LESS mode by adjusting one of OctoPrint's ``devel`` flags via the ``config.yaml`` file:
+
+.. code-block:: yaml
+ :emphasize-lines: 2-3
+
+ # [...]
+ devel:
+ stylesheet: less
+ # [...]
+
+Restart OctoPrint and shift-reload. Your "Hello World" tab should still look like before. Take a look at the site's
+source code. In the ``head`` section of the page you'll see that instead of your ``helloworld.css`` OctoPrint now
+embedded the ``helloworld.less`` file instead:
+
+.. code-block:: html
+ :linenos:
+ :emphasize-lines: 7
+
+
+
+ `.
+
+But I want to invite you to dive deeper into OctoPrint's plugin system. To get an idea of all the other various plugin types
+you haven't seen yet, :ref:`take a look at the available plugin mixins `.
+
+For some insight on how to create plugins that react to various events within OctoPrint,
+`the Growl Plugin `_ might be a good example to learn from. For how to
+add support for a slicer, OctoPrint's own bundled `CuraEngine plugin `_
+might give some hints. For extending OctoPrint's interface, the `NavbarTemp plugin `_
+might show what's possible with a few lines of code already. Finally, just take a look at the
+`list of available plugins `_ on the OctoPrint wiki if you are
+looking for examples.
+
+.. rubric:: Footnotes
+
+.. [#f1] Refer to the `LESS documentation `_ on how to do that. If you are developing
+ your plugin under Windows you might also want to give `WinLESS