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

Fig.: Controlling an Animation.

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>

Listing: Structure of custom HTML element 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

Table: Examples for using <ctrl-ing>.

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