ctrling

0.8.25 • Public • Published

<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 ?
  • 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

Versions

Current Tags

  • Version
    Downloads (Last 7 Days)
    • Tag
  • 0.8.25
    0
    • latest

Version History

Package Sidebar

Install

npm i ctrling

Weekly Downloads

0

Version

0.8.25

License

MIT

Unpacked Size

4.65 MB

Total Files

31

Last publish

Collaborators

  • goessner