--- "lang": "en-US", "title": "<ctrl-ing> - A Smart GUI Controller", "subtitle": "An appealing GUI for controlling your Web-App, JSON, DOM or JavaScript Object Values", "authors": ["Stefan Gössner1", ""], "adresses": ["1Dortmund University of Applied Sciences. Department of Mechanical Engineering"], "date": "January 2023", "description": "A tiny HTML custom element for interactively controlling your Web-App parameters", "tags": ["prototypical","GUI","controlling","JSON","javascript","object","JSONPath","HTML","custom element"] --- ### Abstract Many webapplications are of small to medium size. Equipping these with a pleasing user control menu usually is comparatively costly. For this purpose, presented is a simple solution concept to rapidly prototype a pleasing GUI even without programming. ## Content - [1. What is It ?](#1-what-is-it) - [2. Getting Started](#2-getting-started) - [3. `` Element](#3-ctrl-ing-element) - [3.1 `` Attributes](#31-ctrl-ing-attributes) - [3.2 Automatical Menu Generation](#32-automatical-menu-generation) - [3.3 Examples](#33-examples) - [4. Sections Reference](#4-sections-reference) - [4.1 Button](#41-button) - [4.2 Checkbox](#42-checkbox) - [4.3 Color](#43-color) - [4.4 Header](#44-header) - [4.5 Meter](#45-meter) - [4.6 Number](#46-number) - [4.7 Output](#47-output) - [4.8 Range](#48-range) - [4.9 Selection](#49-selection) - [4.10 Separator](#410-separator) - [4.11 Text](#411-text) - [4.12 Vector](#412-vector) - [5. API](#5-api) - [5.1 Self-Control](#51-self-control) - [6. Other Controller Libraries](#6-other-controller-libraries) - [7. Conclusion](#7-conclusion) - [References](#references) ## 1. 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. * given an object, a menu template can even be created automatically. * no programming required. * getting a pleasing GUI.
Fig. 1: Controlling an Animation.

Here is the [live version](https://goessner.github.io/ctrling/examples/ctrl-lissajous.html) of the Lissajous example. Its interactive menu was created via: ```html [ {"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']"} ] ```
Listing 1: 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 `` 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 `` 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) [[2]](#2). That markup is hidden and separated from other code on the page — thus avoiding code collisions. A short version of this is published as a paper on [[1]](#1) [ResearchGate](https://www.researchgate.net/publication/367045965_ctrl-ing_-_A_Smart_GUI_Controller). ## 2. Getting Started You might want to start with a minimal example. Let's say, we want to create this controlling menu.
Fig. 2: Minimal <ctrl-ing> Example.

Here is the complete HTML code ([Live version](https://goessner.github.io/ctrling/ctrl-lissajous.html)) ```html Getting Started [ {"sec":"hdr","text":"Getting Started"}, {"sec":"chk","label":"Toggle","path":"$['toggle']"}, {"sec":"out","label":"obj=","path":"$"} ] ```
Listing 2: Minimalistic example using <ctrl-ing> element.

With this example please take note of following points: * By its `ref="obj"` attribute the `` instance references a global object `obj`. * The `chk` section in the JSON content accesses the `toggle` member of the reference object `obj` via its `path` property using standard [JSONPath](https://ietf-wg-jsonpath.github.io/draft-ietf-jsonpath-base/draft-ietf-jsonpath-base.html#name-normalized-paths) syntax, where the root identifier `"$"` corresponds to the `ref` attribute content above. * The `out` section is monitoring the reference object in JSON text format. * The `autoupdate` attribute of the `` instance enables monitoring sections to be updated automatically. * `ctrling.js` is inserted via CDN to the page. The generated encapsulated shadow DOM structure for the `` element in this example is quite clear. ```html
Getting Started
obj={ "toggle":false }
```
Listing 3: Internal DOM structure of the ctrl-ing element.

## 3. `` Element The default width of the `` menu is `200px`, which can be modified by the element's `width` attribute. Its default position is the top right corner of its parent element's area. This might be fine-adjusted via `top` and `right` attributes. We can use multiple ``s per page – always right aligned each. In this case the elements should be encapsulated via ```html
...
``` If the `` element should be positioned side-by-side with another (to be controlled) element – which is frequently the case, the following markup might be used ```html
...
...
``` The connection from the `` element and its content to application parameter values is established via element attributes and section members representing paths pointing into an application object. These path strings MUST start with one of * `globalThis` or `window` * the root identifier `$`, referencing an application object name indicated by the `` element's `ref` attribute. Thus the reference object MUST be an object (JavaScript arrays are objects). The rest of the path string MUST obey the syntax of *Normalized Paths* according to [Internet standard *JSONPath*](https://ietf-wg-jsonpath.github.io/draft-ietf-jsonpath-base/draft-ietf-jsonpath-base.html#name-normalized-paths) (IETF), i.e. * using the bracket syntax `[...]` exclusively. * enclosing member names in single quotation marks. ### 3.1 `` Attributes For an `` element following optional attributes are supported: | Attribute | Default | Meaning | |:--:|:--:|:--| |`ref` | `window` | Referencing a global object variable of the name indicated by this attribute. | |`width` | `200px` | Width of the GUI menu (CSS units). | |`top` | `0` | Distance relative to top edge of parent element (CSS units). | |`right` | `0` | Distance relative to right edge of parent element (CSS units). | |`darkmode` | - | Display GUI menu in dark mode (default: light). | |`autoupdate` | - | Automatically update monitoring and input sections. | |`autogenerate` | - | Automatically generate a prototype menu from the object given by `ref` attribute. | |`tickspersecond` | `4` | How often to update sections per second (on external value change). | |`callback` | - | If present, will be called with each user value change by input sections. The attribute value must obey the [JSONPath](https://ietf-wg-jsonpath.github.io/draft-ietf-jsonpath-base/draft-ietf-jsonpath-base.html#name-normalized-paths) syntax rules and might be a global function or an object method. |
Table 1: Supported ctrl-ing attributes.

The `callback` function or method will be handed over an argument object with the structure: ```js args = { ctrl, // current `` element object. obj, // parent object holding the member, whose value is to be set. member, // the member name, whose value is to be set. value, // the new member value. section, // the current section object. elem // the current html
element. } ``` Please note, that a first initial call of the `callback` function – when exists – is automatically done during initialization time. A reduced object `args = {ctrl}` will be passed as an argument then. ### 3.2 Automatical Menu Generation It is possible to let a `` element automatically generate a GUI menu from a given JavaScript object. ```html ``` 






Automatical menu generation with `` works according to following rules.

* its `ref` attribute must point to a valid object.
* its `autogenerate` attribute must be present.
* the object's properties delivered by [`Object.getOwnPropertyNames()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/getOwnPropertyNames) are taken to build the menu.
  * the member value types `boolean`, `number` and `string` create sections of type `chk`, `num` and `txt`.
  * a member value type of `string` whose value starts with `"#"` is assumed to represent a rgb color value and generates a section of type `col`.
  * members with type of `object` are not taken into account.
  * getters/setters are treated as normal properties.
  * property names starting with underline `"_"` are considered private and skipped.
* an `autogenerate="source"` attribute generates an additional final section of type `out` containing the JSON text of the generated sections as a template for further use.

### 3.3 Examples

| Run | Source | Example |
|:--|:--|:--|
|[API](https://goessner.github.io/ctrling/examples/ctrl-api.html) | [source](https://github.com/goessner/ctrling/blob/master/docs/examples/ctrl-api.html) | Using the API |
|[array](https://goessner.github.io/ctrling/examples/ctrl-array.html) | [source](https://github.com/goessner/ctrling/blob/master/docs/examples/ctrl-array.html) | Controlling an array object |
|[autogenerate](https://goessner.github.io/ctrling/examples/ctrl-autogenerate.html) | [source](https://github.com/goessner/ctrling/blob/master/docs/examples/ctrl-autogenerate.html) | Automatically generating a menu |
|[color](https://goessner.github.io/ctrling/examples/ctrl-color.html) | [source](https://github.com/goessner/ctrling/blob/master/docs/examples/ctrl-color.html) | Controlling an RGB color |
|[demo](https://goessner.github.io/ctrling/examples/ctrl-demo.html) | [source](https://github.com/goessner/ctrling/blob/master/docs/examples/ctrl-demo.html) | Showing all features |
|[lissajous](https://goessner.github.io/ctrling/examples/ctrl-lissajous.html) | [source](https://github.com/goessner/ctrling/blob/master/docs/examples/ctrl-lissajous.html) | Lissajous App |
|[minimal](https://goessner.github.io/ctrling/examples/ctrl-minimal.html) | [source](https://github.com/goessner/ctrling/blob/master/docs/examples/ctrl-minimal.html) | Minimal menu generation |
|[parse-error](https://goessner.github.io/ctrling/examples/ctrl-parse-error.html) | [source](https://github.com/goessner/ctrling/blob/master/docs/examples/ctrl-parse-error.html) | Treating JSON parse error |
|[paths](https://goessner.github.io/ctrling/examples/ctrl-paths.html) | [source](https://github.com/goessner/ctrling/blob/master/docs/examples/ctrl-paths.html) | Using paths as JSONPath strings |
|[self](https://goessner.github.io/ctrling/examples/ctrl-self.html) | [source](https://github.com/goessner/ctrling/blob/master/docs/examples/ctrl-self.html) | Controlling the menu itself |
|[svg](https://goessner.github.io/ctrling/examples/ctrl-svg.html) | [source](https://github.com/goessner/ctrling/blob/master/docs/examples/ctrl-svg.html) | Controlling SVG graphics |
|[todeg](https://goessner.github.io/ctrling/examples/ctrl-todeg.html) | [source](https://github.com/goessner/ctrling/blob/master/docs/examples/ctrl-todeg.html) | Transform property with user setting |
|[variable](https://goessner.github.io/ctrling/examples/ctrl-variable.html) | [source](https://github.com/goessner/ctrling/blob/master/docs/examples/ctrl-variable.html) | Controlling a single variable value |
|[vector](https://goessner.github.io/ctrling/examples/ctrl-vector.html) | [source](https://github.com/goessner/ctrling/blob/master/docs/examples/ctrl-vector.html) | Controlling multiple values as vector |

Table: Examples for using <ctrl-ing>.




## 4. Sections Reference

For each section in the JSON content of the `` element there is a HTML `
` element containing either plain visually structuring, data monitoring or interactive form elements. Here is an overview of the twelve different section types. 

| Type | HTML (shadow) | Task |
|:--:|:--|:--|
|[`btn`](#41-button)  | `


```

**Properties**
| `btn` | Default | Comment |
|:--|:--:|:--|
|`[label]` | '' | Label text.  |
|`text`  | - | Button text.  |
|`path`  | - | Location of method within reference object or global function.  |
|`[disabled]`  | - | Disable button.  |

### 4.2 Checkbox

The `chk` section is usually assigned to a boolean object property to be controlled.
```json

  [ {"sec":"hdr","text":"Checkbox"},
    {"sec":"chk","label":"Checkbox","path":"$['toggle']"}
  ]

```






  [ {"sec":"hdr","text":"Checkbox"},
    {"sec":"chk","label":"Checkbox","path":"$['toggle']"}
  ]



 

**Properties**
| `chk` | Default | Comment |
|:--|:--:|:--|
|`[label]` | '' | Label text.  |
|`path`  | - | Location of reference value within reference object.  |
|`[value]`  | reference value | Only used as value, if reference value is not available. |
|`[disabled]`  | - | Disable input element.  |

**HTML in Shadow DOM**
```html


  


```

### 4.3 Color

The `col` section provides a user interface to assign a RGB color in HEX-notation to an object property.
```json

  [ {"sec":"hdr","text":"Color"},
    {"sec":"col","label":"Color","path":"$['color']"}
  ]

```






  [ {"sec":"hdr","text":"Color"},
    {"sec":"col","label":"Color","path":"$['color']"}
  ]



 

**Properties**
| `col` | Default | Comment |
|:--|:--:|:--|
|`[label]` | '' | Label text.  |
|`path`  | - | Location of reference value within reference object.  |
|`[value]`  | `#000000` | Used as value, if reference value is not available. |
|`[disabled]`  | - | Disable input element.  |

**HTML in Shadow DOM**
```html


  Color
  
    
    #456789
  


```

### 4.4 Header

The `hdr` section is used for menu structuring. We can use multiple headers for visually subdivide sections.

```json

  [ {"sec":"hdr","text":"Header Only"} ]

```




  [ {"sec":"hdr","text":"Header Only"} ]




**HTML in Shadow DOM**
```html


  Header Only


```

**Properties**
| `hdr` | Default | Comment |
|:--|:--:|:--|
|`text` | - | Header text.  |


### 4.5 Meter

The monitoring `mtr` section provides a graphic view of a scalar object property value within a known range. It displays the value in its initial state and is not aware of value changes, unless either the
* ``'s `autoupdate` property is set.
* API method `update()` is called.

```json

  [ {"sec":"hdr","text":"Meter"},
    {"sec":"mtr","label":"Volumn","path":"$['volumn']","min":20,"max":80,
                 "low":45,"high":70,"optimum":40,"value":50,"unit":"m³"}
  ]

```




const mtr = {
  volumn:40
}



  [ {"sec":"hdr","text":"Meter"},
    {"sec":"mtr","label":"Volumn","path":"$['volumn']","min":20,"max":80,
                 "low":45,"high":70,"optimum":40,"value":50,"unit":"m³"}
  ]



 

**HTML in Shadow DOM**
```html


    Volumn
    
        
        40
        m³
    


```

**Properties**
| `mtr` | Default | Comment |
|:--|:--:|:--|
|`[label]` | '' | Label text.  |
|`path`  | - | Location of scalar reference value within reference object.  |
|`[value]`  | `min` \| 0 | Used as value, if reference value is not available. |
|`[min]`  | 0 | Minimum value. |
|`[max]`  | 1 | Maximum value. |
|`[low]`  | `min` | Lower limit value (`low` ≥ `min`). Meter may change color when below. |
|`[high]`  | `max` | Upper limit value (`high` ≤ `max`). Meter may change color when above. |
|`[optimum]`  | - | Optimal numeric value  (`min` ≤ `optimum` ≤ `max`); e.g., if it lies between `min` and `low`, that region is colored as the preferrable one. |
|`[unit]`  | - | Append unit string. |

### 4.6 Number

The `num` section provides a user interface to enter a numerical value and assign it to an object property. It uses the HTML `` element and supports its `min`, `max` and `step` attributes.

**Example**

```json

  [ {"sec":"hdr","text":"Number"},
    {"sec":"num","label":"Number","min":1,"max":2,"step":0.2,
                 "path":"$['number']","unit":"[s]"}
  ]

```






  [ {"sec":"hdr","text":"Number"},
    {"sec":"num","label":"Number","min":1,"max":2,"step":0.2,
                 "path":"$['number']","unit":"[s]"}
  ]





**HTML in Shadow DOM**
```html


    


```

**Properties**
| `num` | Default | Comment |
|:--|:--:|:--|
|`[label]`  | '' | Label text.  |
|`[min]`  | - | Minimum value. |
|`[max]`  | - | Maximum value. |
|`[step]`  | `1` | Step size. |
|`[fractions]`  | - | Number of decimal digits. |
|`[value]`  | reference value | Only used as value, if reference value is not available. |
|`path`  |  | Location of reference value within reference object.  |
|`[unit]`  | - | Unit symbol of value.  |
|`[disabled]`  | - | Disabled input.  |

### 4.7 Output

The `out` section displays an object property value in its initial state. It is not aware of object value changes, unless either the
* ``'s `autoupdate` property is set.
* API method `update()` is called.

The property value is mutated to JSON text for display. So only primitive object properties and getters are shown in case of structured property values.

```json

  [ {"sec":"hdr","text":"Output"},
    {"sec":"out","label":"Point","path":"$['pnt']","unit":"[mm]"}
  ]

```




const out = {
  pnt: {x:5, y:7}
}



  [ {"sec":"hdr","text":"Output"},
    {"sec":"out","label":"Point","path":"$['pnt']","unit":"[mm]"}
  ]



 

**HTML in Shadow DOM**
```html


    Point
    
        {
          "x":5,
          "y":7
        }
        [mm]
    


```

**Properties**
| `out` | Default | Comment |
|:--|:--:|:--|
|`[label]` | '' | Label text.  |
|`path`  | - | Location of reference value. |
|`[value]`  | reference value | Only used as value, if reference value is not available. |
|`[unit]`  | - | Append unit string. |
|`[precision]`  | - | present a numerical value with the given precision (number of relevant fractions after the first non-zero digit). |

### 4.8 Range

The `rng` section provides a user interface to enter a numerical value in a range by a slider. It uses the HTML `` element and supports its `min`, `max` and `step` attributes.

**Example**

```json

  [ {"sec":"hdr","text":"Range"},
    {"sec":"rng","label":"Weight","min":10,"max":100,"step":5,
                 "path":"$['value']","unit":"kg"}
  ]

```






  [ {"sec":"hdr","text":"Range"},
    {"sec":"rng","label":"Weight","min":10,"max":100,"step":5,
                 "path":"$['value']","unit":"kg"}
  ]





**HTML in Shadow DOM**
```html


    Weight
    
        
        40
        kg
    


```

**Properties**
| `num` | Default | Comment |
|:--|:--:|:--|
|`[label]`  | '' | Label text.  |
|`[min]`  | - | Minimum value. |
|`[max]`  | - | Maximum value. |
|`[step]`  | `1` | Step size. |
|`[value]`  | reference value | Only used as value, if reference value is not available. |
|`path`  |  | Location of reference value within reference object.  |
|`[unit]`  | - | Unit string.  |
|`[disabled]`  | - | Disabled input.  |

### 4.9 Selection

The `sel` section provides a drop down menu of options. It uses the HTML ``'s `multiple` attribute and `` elements are not supported.

```json

  [ {"sec":"hdr","text":"Select"},
    {"sec":"sel","label":"Linestyle","path":"$['lineStyle']",
     "options":["solid","dashed","dotted"]},
    {"sec":"sel","label":"Thickness","path":"$['thickness']",
     "options":{"thin":1,"medium":2,"thick":3}}
  ]

```






  [ {"sec":"hdr","text":"Output"},
    {"sec":"sel","label":"Linestyle","options":["solid","dashed","dotted"],"path":"$['lineStyle']"},
    {"sec":"sel","label":"Thickness","options":{"thin":1,"medium":2,"thick":3},"path":"$['thickness']"}
  ]





**HTML in Shadow DOM**
```html


  Linestyle
  




  Thickness
  


```

**Properties**
| `sel` | Default | Comment |
|:--|:--:|:--|
|`[label]` | '' | Label text.  |
|`options`  | - | Object as member name/value pairs or array elements. |
|`[value]`  | reference value | Only used as value, if reference value is not available. |
|`path`  | - | Location of reference value. |
|`[disabled]`  | - | Disabled selection.  |

### 4.10 Separator

The `sep` section displays a separation line using the HTML `
` element. It has no properties.

```json

  [ {"sec":"hdr","text":"Separator"},
    {"sec":"sep"}
  ]

```



  
    [ {"sec":"hdr","text":"Separator"},
      {"sec":"sep"}
    ]
  



**HTML in Shadow DOM**
```html


    



```

### 4.11 Text

The `txt` section provides a user interface to enter a text string and assign it to an object property. It uses the HTML `` element.

Please note that multiline text is not supported.

**Example**

```json

  [ {"sec":"hdr","text":"Text"},
    {"sec":"txt","label":"Text","path":"$['text']"}
  ]

```






  [ {"sec":"hdr","text":"Text"},
    {"sec":"txt","label":"Text","path":"$['text']"}
  ]





**HTML in Shadow DOM**
```html


    


```

**Properties**
| `txt` | Default | Comment |
|:--|:--:|:--|
|`[label]`  |  | Label text.  |
|`path`  |  | Location of reference value within reference object.  |
|`[value]`  | reference value | Only used as value, if reference value is not available. |
|`[disabled]`  | - | Disabled input.  |

### 4.12 Vector

The `vec` section provides a user interface for object/array structures. It offers for each member/element an individual input field using HTML `` elements in a grid-like structure. The `path` member in this section is an array holding multiple pathes, rather than a singular path.

Size of the input fields might be controlled by `width` member accepting CSS units. Input elements on the grid lines are wrapped onto a new line in case of overflow. They are always right aligned.

**Example**

```json

  [ {"sec":"hdr","text":"Vector"},
    {"sec":"vec","label":"Array",
                 "path":["$['arr'][0]","$['arr'][1]","$['arr'][2]","$['arr'][3]"]},
    {"sec":"vec","label":"Object (x,y,z)",
                 "path":["$['vec']['x']","$['vec']['y']","$['vec']['z']"],
                 "unit":"mm","width":"1em"}
  ]

```



  

  
    [ {"sec":"hdr","text":"Vector"},
      {"sec":"vec","label":"Array",
      "path":["$['arr'][0]","$['arr'][1]","$['arr'][2]","$['arr'][3]"]},
      {"sec":"vec","label":"Object (x,y,z)",
      "path":["$['vec']['x']","$['vec']['y']","$['vec']['z']"],
      "unit":"mm","width":"1em"}
    ]
  




**HTML in Shadow DOM**
```html


    Array
    
        
        
        
        
    




    Object (x,y,z)
    
        
        
        
    
    mm


```

**Properties**
| `vec` | Default | Comment |
|:--|:--:|:--|
|`label`  |  | Label text.  |
|`path`  | - | Location of reference value within reference object.  |
|`[width]`  | 24% | Input fields width in CSS units.  |
|`[unit]`  | - | Unit string.  |
|`[disabled]`  | - | Disabled input fields.  |



## 5. API

The `` menu internals are hidden behind the shadow DOM. For offering programmatical access to these internals, an API is provided. Here is an example how to use it.

```html


```

Listing 4: Control menu generation and modification via API calls.



Comments to the line numbers:

1. Ensure to start with API calls when the `` element is completely initialized.
2. The `setAttr` method is merely syntactic sugar for the native `setAttribute` method. It additionally supports chaining of method calls only.
3. `addSection` methods are used to sequentially build the control menu. They get a single object literal argument representing a section.
4. Note the intentional typo with the `path` value. That will be corrected in (6).
5. `insertSection` method inserts a new section before section with current index `3`, i.e. `{"sec":"out",...}`.
6. `updateSection` method corrects the typo in line (4) and updates section with current index `1`, i.e. `{"sec":"chk",...}`.
7. `removeSection` method removes the section with current index `2`, i.e. `{"sec":"num",...}`.

The API works properly at the earliest after the `` element is completely initialized. In order to ensure this, we want to encapsulate the API method calls in a callback function oninit((ctrl) => { ... }). The callback function receives the `` element object as a single argument.

| Method | Returns | Comment |
|:--|:--|:--|
|`addSection(sec)` | `this` | Append a new section object `sec` to the sections array.  |
|`findSectionIndex(fn)` | index | Locate the first section in the sections array, that fulfills the condition given by function `fn`. Returns the array index found or `-1` on failure. The condition function receives the current section during iteration as argument. |
|`insertSection(idx,sec)` | `this` | Insert a new section object `sec` to the sections array before the section at index `idx`.  |
|`oninit(fn)` | - | Invoking a callback function `fn`, while ensuring that the control menu object is completely initialized. The callback function receives the `` element object as a single argument. |
|`removeAttr(attr)` | `this` | Remove ``'s attribute `attr`.  |
|`removeSection(idx)` | `this` | Remove the section at index `idx`. |
|`setAttr(attr,value)` | `this` | Set ``'s attribute `attr` to value `value`.  |
|`section(idx)` | section | Select a section from the sections array by index `idx`.  |
|`updateControlValues()` | `this` | When the `autoupdate` attribute is not set, this method might be used programmatically to update current values in the control elements instead. |
|`updateSection(idx,sec)` | `this` | If `sec` is present, current section at index `idx` will be replaced by `sec`, otherwise current section is assumed to be modified and stays in place. The shadow DOM is getting updated hereafter. |


Table 3: API Methods.



### 5.1 Self-Control

API methods may be used to modify the `` menu itself. Here is an example, how to disable the section with index `2`.


```json

  [ {"sec":"hdr","text":"Self-Control"},
    {"sec":"chk","label":"Disable str","path":"$['disable']"},
    {"sec":"txt","label":"str","path":"$['str']"}
  ]

```




```js
const objslf = {
    disable: false,
    str: "Hello",
    callbk({ctrl, obj, member, value, section, elem}) {
        if (member === 'disable') {
            ctrl.section(2).disabled = value;
            ctrl.updateSection(2);
        }
    }
}
```
  
    [ {"sec":"hdr","text":"Self-Control"},
      {"sec":"chk","label":"Disable str","path":"$['disable']"},
      {"sec":"txt","label":"str","path":"$['str']"}
    ]
  




## 6. Other Controller Libraries

There are a couple of JavaScript controller libraries. Here are two overview pages [[3, 4]](#3). From the controller libraries listed there `dat.gui` is the most mature and most popular one. Many of the other libraries are kind of `dat.gui` clones providing an identical or very similar API. Some of them have very powerful features added like enhanced color pickers and/or charting capabilities. If you want a `dat.gui` like JavaScript solution, it is recommended to take one of these controller libraries.

`` has a different, more minimalistic approach with quickly prototyping a GUI menu by using markup/JSON alone. It deliberately uses plain standard HTML form elements for user interaction despite some of their known deficiencies. Hence the advantage of its light weight, which is considerable smaller (25 kB uncompressed) than the libraries above.


## 7. Conclusion

`` is a lightweight HTML custom element. It helps to rapidly prototype a pleasing GUI without programming. Web-App parameters or JavaScript/JSON/DOM object values can be monitored or interactively modified.

A `` menu can be built with few HTML/JSON text alone. Accessing its HTML element via JavaScript can be done via well known DOM methods. Accessing the hidden shadow DOM sections is not possible though. For enabling programmatical access to the internal menu structure, a small API is provided.

`` does not depend on other libraries and is meant as a helper for webapplications of small to medium size.




## References 

[1] <ctrl-ing> on ResearchGate, [https://tinyurl.com/7824v27u](https://tinyurl.com/7824v27u )    
[2] HTML input types,
      [https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Input#input_types](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Input#input_types)    

[3] List of JavaScript GUI Control libraries, [https://xosh.org/javascript-control-ui/](https://xosh.org/javascript-control-ui/)    
[4] JavaScript GUI libraries,
     
[https://gist.github.com/SMUsamaShah/71d5ac6849cdc0bffff4c19329e9d0bb](https://gist.github.com/SMUsamaShah/71d5ac6849cdc0bffff4c19329e9d0bb)