OVMS3/OVMS.V3/components/ovms_webserver/dev/README.md

OVMS Web Framework Documentation

TL;DR: Examples

Usage

• Metric Displays – how to display metrics
• Command Buttons & Monitors – how to create simple manual & automatic command calls
• Notifications – how to subscribe to and process notifications
• Hook Plugins – how to extend existing pages
• Solid Gauges – two solid gauge metrics displays
• Dashboard – multiple gauge charts with responsive rules

API

• Command Streaming – the loadcmd() utility

UI

• Longtouch Buttons – protect touchscreen buttons against unintended trigger
• Basic Dialogs – custom, confirm and prompt dialogs
• File Dialogs – file selection dialogs
• File Browser Widget – file browser for page/dialog integrations
• Slider Widget – combined number & range control

Plugins

• Twizy: Dashboard Tuning Plugin – add recuperation control to the dashboard
• Twizy: Tuning Profile Editor – lots of sliders and a custom dialog
• Twizy: Drivemode Button Editor – dynamic UI creation

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'
• curl 'http://192.168.4.1/api/execute?apikey=password&type=js&command=print(Duktape.version)'

User 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.

Web UI Development Framework

To simplify and speed up UI and plugin development, you can simply run a local web server from the dev directory of the ovms_webserver component source.

Preparation: create your local git clone if you don't have one already:

> cd ~
> git clone https://github.com/openvehicles/Open-Vehicle-Monitoring-System-3.git

Local web server options: List of static web servers

Example:

> cd ~/Open-Vehicle-Monitoring-System-3/vehicle/OVMS.V3/components/ovms_webserver/dev
> python3 -m http.server 8000
Serving HTTP on 0.0.0.0 port 8000 (http://0.0.0.0:8000/) ...

Now open the development framework in your browser at URI http://localhost:8000. If that doesn't work, check your firewall settings for port 8000 on localhost.

You should see the examples home. Edit index.htm to add custom menus, edit home.htm to add custom home buttons.

Hint: to test your plugin for mobile devices, use the mobile emulation mode of your browser's development toolkit. Mobile mode allows to test small screen resolutions, rotation and touch events.

A static local HTTP server allows to use all frontend features, but cannot emulate the backend API (command/script execution). If using a CGI capable HTTP server, you can also add a proxy handler for /api/execute that forwards the requests to your module by HTTP or SSH.

If you want to add your results to a C++ module, use the tools mksrc and mksrcf to convert your HTML files into C++ compatible strings. mksrc is meant for static strings, mksrcf for strings with printf style placeholders.