Docs: added web framework & plugin docs

docs/source/index.rst

@@ -14,6 +14,7 @@ Open Vehicles Monitoring System
    :caption: Developer Guides:
 
    crtd/index
+   components/ovms_webserver/docs/index
 
 .. toctree::
    :maxdepth: 1

vehicle/OVMS.V3/components/ovms_webserver/docs/btn-longtouch.rst

@@ -0,0 +1,8 @@
+Longtouch Buttons
+=================
+
+:download:`btn-longtouch.htm <../dev/btn-longtouch.htm>` (hint: right click, save as)
+
+.. literalinclude:: ../dev/btn-longtouch.htm
+   :language: html
+   :linenos:

vehicle/OVMS.V3/components/ovms_webserver/docs/commands.rst

@@ -0,0 +1,8 @@
+Command Buttons & Monitors
+==========================
+
+:download:`commands.htm <../dev/commands.htm>` (hint: right click, save as)
+
+.. literalinclude:: ../dev/commands.htm
+   :language: html
+   :linenos:

vehicle/OVMS.V3/components/ovms_webserver/docs/dashboard.rst

@@ -0,0 +1,8 @@
+Dashboard
+=========
+
+:download:`dashboard.htm <../dev/dashboard.htm>` (hint: right click, save as)
+
+.. literalinclude:: ../dev/dashboard.htm
+   :language: html
+   :linenos:

vehicle/OVMS.V3/components/ovms_webserver/docs/dialogtest.rst

@@ -0,0 +1,8 @@
+Basic Dialogs
+=============
+
+:download:`dialogtest.htm <../dev/dialogtest.htm>` (hint: right click, save as)
+
+.. literalinclude:: ../dev/dialogtest.htm
+   :language: html
+   :linenos:

vehicle/OVMS.V3/components/ovms_webserver/docs/filebrowser.rst

@@ -0,0 +1,8 @@
+File Browser Widget
+===================
+
+:download:`filebrowser.htm <../dev/filebrowser.htm>` (hint: right click, save as)
+
+.. literalinclude:: ../dev/filebrowser.htm
+   :language: html
+   :linenos:

vehicle/OVMS.V3/components/ovms_webserver/docs/filedialog.rst

@@ -0,0 +1,8 @@
+File Dialogs
+============
+
+:download:`filedialog.htm <../dev/filedialog.htm>` (hint: right click, save as)
+
+.. literalinclude:: ../dev/filedialog.htm
+   :language: html
+   :linenos:

vehicle/OVMS.V3/components/ovms_webserver/docs/hooks.rst

@@ -0,0 +1,8 @@
+Hook Plugins
+============
+
+:download:`hooks.htm <../dev/hooks.htm>` (hint: right click, save as)
+
+.. literalinclude:: ../dev/hooks.htm
+   :language: html
+   :linenos:

vehicle/OVMS.V3/components/ovms_webserver/docs/index.rst

@@ -0,0 +1,146 @@
+Web Framework & Plugins
+=======================
+
+TL;DR: Examples
+---------------
+
+The following examples include their documentation in the HTML page and source.
+Read the source and install them as plugins (see below) to see how they work.
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Basic usage
+
+   metrics
+   commands
+   notifications
+   hooks
+   solidgauge
+   dashboard
+
+.. toctree::
+   :maxdepth: 1
+   :caption: API usage
+
+   loadcmd
+
+.. toctree::
+   :maxdepth: 1
+   :caption: UI elements
+
+   btn-longtouch
+   dialogtest
+   filedialog
+   filebrowser
+   input-slider
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Plugin examples
+
+   regenmon
+   plugin-twizy/dashboard-tuneslider
+   plugin-twizy/profile-editor
+   plugin-twizy/drivemode-config
+
+
+Installing Plugins
+------------------
+
+The framework supports installing user content as pages or extensions to
+pages. To install an example:
+
+1. Menu Config → Web Plugins
+2. Add plugin: type "Page", name e.g. "dev.metrics" (used as the file
+   name in ``/store/plugin``)
+3. Save → Edit
+4. Set page to e.g. "/usr/dev/metrics", label to e.g. "Dev: Metrics"
+5. Set the menu to e.g. "Tools" and auth to e.g. "None"
+6. Paste the page source into the content area
+7. Save → the page is now accessible in the "Tools" menu.
+
+Hint: use the standard editor (tools menu) in a second session to edit a
+plugin repeatedly during test / development.
+
+
+Basics
+------
+
+The OVMS web framework is based on HTML 5, Bootstrap 3 and jQuery 3.
+Plenty documentation and guides on these basic web technologies is
+available on the web, a very good resource is `w3schools.com`_.
+
+For charts the framework includes Highcharts 6. Info and documentation
+on this is available on `Highcharts.com`_.
+
+The framework is "AJAX" based. The index page ``/`` loads the framework
+assets and defines a default container structure including a ``#menu``
+and a ``#main`` container. Content pages are loaded into the ``#main``
+container. The window URL includes the page URL after the hash mark
+``#``:
+
+-  ``http://ovms.local/#/status`` – this loads page ``/status`` into
+   ``#main``
+-  ``http://ovms.local/#/dashboard?nm=1`` – this loads the dashboard and
+   activates night mode
+
+Links and forms having id targets ``#…`` are automatically converted to
+AJAX by the framework:
+
+-  ``<a href="/edit?path=/sd/index.txt" target="#main">Edit index.txt</a>``
+   – load the editor
+
+Pages can be loaded outside the framework as well (e.g.
+``http://ovms.local/status``). See index source on framework scripts and
+styles to include if you'd like to design standalone pages using the
+framework methods.
+
+If file system access is enabled, all URLs not handled by the system or
+a user plugin (see below) are mapped onto the file system under the
+configured web root. Of course, files can be loaded into the framework
+as well. For example, if the web root is ``/sd`` (default):
+
+-  ``http://ovms.local/#/mypage.htm`` – load file ``/sd/mypage.htm``
+   into ``#main``
+-  ``http://test1.local/#/logs`` – load directory listing ``/sd/logs``
+   into ``#main``
+
+**Important Note**: the framework has a global shared context (i.e. the
+``window`` object). To avoid polluting the global context with local
+variables, good practice is to wrap your local scripts into closures.
+Pattern:
+
+::
+
+   <script>
+   (function(){
+     … insert your code here …
+   })();
+   </script>
+
+
+Authorization
+-------------
+
+Page access can be restricted to authorized users either session based
+or per access. File access can be restricted using digest
+authentication.
+
+The module password is used for all authorizations. A user account or
+API key administration is not yet included, the main username is
+``admin``.
+
+To create a session, call the ``/login`` page and store the resulting
+cookie:
+
+1. ``curl -c auth -b auth 'http://192.168.4.1/login' -d username=admin -d password=…``
+2. ``curl -c auth -b auth 'http://192.168.4.1/api/execute?command=xrt+cfg+info'``
+
+To issue a single call, e.g. to execute a command from a Wifi button,
+supply the password as ``apikey``:
+
+-  ``curl 'http://192.168.4.1/api/execute?apikey=password&command=xrt+cfg+info'``
+
+
+.. _w3schools.com: https://www.w3schools.com/
+.. _Highcharts.com: https://www.highcharts.com/

vehicle/OVMS.V3/components/ovms_webserver/docs/input-slider.rst

@@ -0,0 +1,8 @@
+Slider Widget
+=============
+
+:download:`input-slider.htm <../dev/input-slider.htm>` (hint: right click, save as)
+
+.. literalinclude:: ../dev/input-slider.htm
+   :language: html
+   :linenos:

vehicle/OVMS.V3/components/ovms_webserver/docs/loadcmd.rst

@@ -0,0 +1,8 @@
+Command Streaming
+=================
+
+:download:`loadcmd.htm <../dev/loadcmd.htm>` (hint: right click, save as)
+
+.. literalinclude:: ../dev/loadcmd.htm
+   :language: html
+   :linenos:

vehicle/OVMS.V3/components/ovms_webserver/docs/metrics.rst

@@ -0,0 +1,8 @@
+Metric Displays
+===============
+
+:download:`metrics.htm <../dev/metrics.htm>` (hint: right click, save as)
+
+.. literalinclude:: ../dev/metrics.htm
+   :language: html
+   :linenos:

vehicle/OVMS.V3/components/ovms_webserver/docs/notifications.rst

@@ -0,0 +1,8 @@
+Notifications
+=============
+
+:download:`notifications.htm <../dev/notifications.htm>` (hint: right click, save as)
+
+.. literalinclude:: ../dev/notifications.htm
+   :language: html
+   :linenos:

vehicle/OVMS.V3/components/ovms_webserver/docs/plugin-twizy/dashboard-tuneslider.rst

@@ -0,0 +1,8 @@
+Twizy: Dashboard Tuning Plugin
+==============================
+
+:download:`dashboard-tuneslider.htm <../../dev/plugin-twizy/dashboard-tuneslider.htm>` (hint: right click, save as)
+
+.. literalinclude:: ../../dev/plugin-twizy/dashboard-tuneslider.htm
+   :language: html
+   :linenos:

vehicle/OVMS.V3/components/ovms_webserver/docs/plugin-twizy/drivemode-config.rst

@@ -0,0 +1,8 @@
+Twizy: Drivemode Button Editor
+==============================
+
+:download:`drivemode-config.htm <../../dev/plugin-twizy/drivemode-config.htm>` (hint: right click, save as)
+
+.. literalinclude:: ../../dev/plugin-twizy/drivemode-config.htm
+   :language: html
+   :linenos:

vehicle/OVMS.V3/components/ovms_webserver/docs/plugin-twizy/profile-editor.rst

@@ -0,0 +1,8 @@
+Twizy: Tuning Profile Editor
+============================
+
+:download:`profile-editor.htm <../../dev/plugin-twizy/profile-editor.htm>` (hint: right click, save as)
+
+.. literalinclude:: ../../dev/plugin-twizy/profile-editor.htm
+   :language: html
+   :linenos:

vehicle/OVMS.V3/components/ovms_webserver/docs/regenmon.rst

@@ -0,0 +1,8 @@
+Regen Brake Monitor
+===================
+
+:download:`regenmon.htm <../dev/regenmon.htm>` (hint: right click, save as)
+
+.. literalinclude:: ../dev/regenmon.htm
+   :language: html
+   :linenos:

vehicle/OVMS.V3/components/ovms_webserver/docs/solidgauge.rst

@@ -0,0 +1,8 @@
+Solid Gauges
+============
+
+:download:`solidgauge.htm <../dev/solidgauge.htm>` (hint: right click, save as)
+
+.. literalinclude:: ../dev/solidgauge.htm
+   :language: html
+   :linenos: