<ctrl-ing> - A Smart GUI Controller

What is it ... ?

<ctrl-ing> is a tiny HTML custom element used to interactively control your Web-App parameters or JavaScript/JSON/DOM object values in a comfortable way with the following characteristics:

• tiny footprint 25.3/14.2 kB un/compressed.
• dependency free.
• easy prototypical generation with low effort. No programming required.
• an object given, a menu template can be created automatically.
• getting a pleasing GUI.

The interactive menu on the right side of Figure 1 was created via:

<ctrl-ing ref="app" darkmode>
  [ {"sec":"hdr","text":"Parameters"},
    {"sec":"num","label":"a","min":0,"max":10,"step":1,"path":"$['a']","unit":"[-]"},
    {"sec":"num","label":"b","min":0,"max":10,"step":1,"path":"$['b']","unit":"[-]"},
    {"sec":"hdr","text":"Animation"},
    {"sec":"chk","label":"run","path":"$['run']"},
    {"sec":"rng","label":"vel","min":1,"max":10,"step":1,"path":"$['vel']"},
    {"sec":"hdr","text":"Style"},
    {"sec":"col","label":"Stroke","path":"$['ls']"},
    {"sec":"col","label":"Fill","path":"$['fs']"}
  ]
</ctrl-ing>

Beside implementing your web application, all you need to do for prototyping an appealing GUI, is inserting a <ctrl-ing> element to your HTML document (see Listing 1). Its content is compact JSON text, representing an array of section objects. Each section corresponds to a single line in the grid-like view structure of the <ctrl-ing> menu and is associated to either

• input controlling application parameters.
• output monitoring values.
• structuring elements.

All section objects are generating plain native HTML (form) elements in the background (shadow DOM). That markup is hidden and separated from other code on the page — thus avoiding code collisions.

Help for getting started and a complete documentation containing an interactive reference is available.

Examples

| Run | Source | Example | |:--|:--|:--| |API | source | Using the API | |array | source | Controlling an array object | |autogenerate | source | Automatically generating a menu | |color | source | Controlling an RGB color | |demo | source | Showing all features | |lissajous | source | Lissajous App | |minimal | source | Minimal menu generation | |parse-error | source | Treating JSON parse error | |paths | source | Using paths as JSONPath strings | |self | source | Controlling the menu itself | |svg | source | Controlling SVG graphics | |todeg | source | Transform property with user setting | |variable | source | Controlling a single variable value | |vector | source | Controlling multiple values as vector |

CDN

Use a local instance or one of the following CDN links for ctrling.js.

• https://cdn.jsdelivr.net/npm/ctrling/ctrling.js
• https://cdn.jsdelivr.net/npm/ctrling/ctrling.min.js

FAQ

• Can I control a single global variable ?
  • In short ... yes.
  • You only need to declare it using var, since let and const variables aren't accessible using globalThis or window object, which is used here for global variables. No restriction for objects or arrays though.
  • See ctrl-variable.html for an example.
• Can I control an array ?
  • Yes, see ctrl-array.html for an example.
• Can I convert values while setting ?
  • Yes.
  • Either use getter/setter pair for get/set value ...
  • ... or use callback function for setting value only.
  • See ctrl-todeg.html for an example.
• Can you implement feature X and possibly feature Y ?
  • ctrling serves my personal needs very well as it is.
  • So ... no, I won't.
  • Please go ahead and implement it by yourself.
  • If you think, your enhancement is of common interest, you are very welcome, to send me a pull request.

Changelog

[0.8.25] on February 01, 2023

• Rounding bug with num section removed.

[0.8.23] on January 11, 2023

• Feature complete.

[0.8.1] on December 20, 2022

• First published.

License

ctrling is licensed under the MIT License

© Stefan Gössner