ctrling - npm Package Compare versions

Comparing version 0.8.21 to 0.8.23

ctrling.js

 /**
  * ctrling.js (c) 2022/23 Stefan Goessner
- * ver. 0.8.21
+ * ver. 0.8.23
  * @license MIT License
@@ -106,3 +106,2 @@ */
         }
-        // console.log(name + ' changed')
     }
@@ -139,4 +138,2 @@
             this.#usrValueCallback({ctrl:this});  // call initially once with empty arguments object ...
-        console.log('initialized!');
-        this.initialized = true; // temorary globally accessible ... !
     }
@@ -415,3 +412,3 @@
                 const [obj, member] = this.#getRef(path);
-                return `<input type="text" ${obj ? ` value="${Ctrling.stringify(obj[member])}"` : ""}${!!args.disabled ? " disabled" : ""}${args.width ? ` style="width:${args.width}"` : ""}>`
+                return `<input type="text"${obj ? ` value='${Ctrling.stringify(obj[member],true)}'` : ""}${!!args.disabled ? " disabled" : ""}${args.width ? ` style="width:${args.width}"` : ""}>`
             }).join('')}</span>${args.unit ? `<span>${args.unit}</span>` : ''}`;
@@ -437,8 +434,9 @@ const inputs = elem.getElementsByTagName('input');
     // static methods ...
-    static stringify(value) {
+    static stringify(value,inner=false) {
         return Array.isArray(value) ? JSON.stringify(value)
-             : typeof value === 'object' ? JSON.stringify(value).replaceAll(/\[.*?\]/gm, ($0) => $0.replaceAll(',',';'))
+             : (typeof value === 'object' && inner) ? JSON.stringify(value)
+             : typeof value === 'object' ? JSON.stringify(value).replaceAll(/\[.*?\]/gm, ($0) => $0.replaceAll(',',';')) // nested arrays not treated properly !
                                                                 .replaceAll(/\:\{([^}]*?)\}/gm, ($0) => $0.replaceAll(',',';'))
-                                                                .replace(/^\{/gm,'{\n  ')
-                                                                .replace(/\}$/gm,'\n}')
+                                                                .replace(/^\{/g,'{\n  ')
+                                                                .replace(/\}$/g,'\n}')
                                                                 .replaceAll(',',',\n  ')
@@ -566,2 +564,3 @@ .replaceAll(/  ("_[^"]*":[^,\n]*,?\n)/gm,'') // skip private members
     width: 2em;
+    height: 2em;
 }
@@ -568,0 +567,0 @@ main > section.rng input {

docs/index.md

@@ -7,3 +7,3 @@ ---
 "adresses": ["<sup>1</sup>Dortmund University of Applied Sciences. Department of Mechanical Engineering"],
-"date": "December 2022",
+"date": "January 2023",
 "description": "A tiny HTML custom element for interactively controlling your Web-App parameters",
@@ -24,2 +24,3 @@ "tags": ["prototypical","GUI","controlling","JSON","javascript","object","JSONPath","HTML","custom element"]
     - [3.2 Automatical Menu Generation](#32-automatical-menu-generation)
+    - [3.3 Examples](#33-examples)
   - [4. Sections Reference](#4-sections-reference)
@@ -57,7 +58,7 @@ - [4.1 Button](#41-button)
 <figure style="text-align:center"> 
-   <img src="./lissajous.gif">
+   <img src="https://goessner.github.io/ctrling/img/lissajous.gif">
 </figure>  
 <figcaption style="font-size:0.95em;text-align:center">Fig. 1: Controlling an Animation.</figcaption><br>
 
-Here is the [live version](../examples/ctrl-lissajous.html) of the Lissajous example. Its interactive menu was created via:
+Here is the [live version](https://goessner.github.io/ctrling/examples/ctrl-lissajous.html) of the Lissajous example. Its interactive menu was created via:
 
@@ -93,7 +94,7 @@ ```html
 <figure style="text-align:center"> 
-   <img src="./gettingstarted.gif">
+   <img src="https://goessner.github.io/ctrling/img/gettingstarted.gif">
 </figure>  
 <figcaption style="font-size:0.95em;text-align:center">Fig. 2: Minimal <code>&lt;ctrl-ing&gt;</code> Example.</figcaption><br>
 
-Here is the complete HTML code ([Live version](./gettingstarted.html))
+Here is the complete HTML code ([Live version](https://goessner.github.io/ctrling/ctrl-lissajous.html))
 
@@ -190,5 +191,5 @@ ```html
 |`ref`  | `window` | Referencing a global object variable of the name indicated by this attribute.  |
-|`width`  | `200px` | Width of the GUI menu.  |
-|`top`  | `0` | Distance relative to top edge of parent element. |
-|`right`  | `0` | Distance relative to right edge of parent element. |
+|`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). |
@@ -253,3 +254,23 @@ |`autoupdate`  | - | Automatically update monitoring and input sections. |
 
+### 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 |
+<figcaption style="font-size:0.95em;text-align:center">Table: Examples for using &lt;ctrl-ing&gt;.</figcaption><br>
+
+
 ## 4. Sections Reference
@@ -256,0 +277,0 @@

package.json

 {
   "name": "ctrling",
-  "version": "0.8.21",
+  "version": "0.8.23",
   "description": "An appealing prototypical GUI for controlling your Web-App, JSON or JavaScript Object Values",
@@ -5,0 +5,0 @@ "keywords": [

readme.md

 [![](https://data.jsdelivr.com/v1/package/npm/ctrling/badge)](https://www.jsdelivr.com/package/npm/ctrling)
-# `ctrling`
+# <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 object values in a comfortable way with the following characteristics:
+`<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 `18.7/11.3 kB` un/compressed.
+* tiny footprint `25.3/14.2 kB` un/compressed.
 * dependency free.
-* easy prototypical generation with low effort.
-* no programming required.
+* easy prototypical generation with low effort. No programming required.
+* an object given, a menu template can be created automatically.
 * getting a pleasing GUI.
 
+<br>
+
 <figure style="text-align:center"> 
-   <img src="./docs/lissajous.gif">
+   <img src="./docs/img/lissajous.gif">
 </figure>  
-<figcaption style="font-size:0.95em;text-align:center">Fig. 1: Controlling an Animation.</figcaption><br><br>
+<figcaption style="font-size:0.95em;text-align:center">Fig.: Controlling an Animation.</figcaption><br>
 
-The interactive menu for this example was created via:
+The interactive menu on the right side of Figure 1 was created via:
 
-```html
+```json
 <ctrl-ing ref="app" darkmode>
@@ -35,3 +37,3 @@ [ {"sec":"hdr","text":"Parameters"},
 ```
-<figcaption>Listing 1: Structure of custom HTML element <code>ctrl-ing</code>.</figcaption><br><br>
+<figcaption>Listing: Structure of custom HTML element <code>ctrl-ing</code>.</figcaption><br><br>
 
@@ -46,126 +48,24 @@ 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
 
-## 2. Getting Started
+Help for getting started and a complete documentation containing an interactive reference [is available](https://goessner.github.io/ctrling/).
 
-Let's start with a minimal example resulting in this controlling menu.
+## Examples
 
-<figure style="text-align:center"> 
-   <img src="./docs/gettingstarted.gif">
-</figure>  
-<figcaption style="font-size:0.95em;text-align:center">Fig. 2: Minimal <code>&lt;ctrl-ing&gt;</code> Example.</figcaption><br><br>
+| 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 |
+<figcaption style="font-size:0.95em;text-align:center">Table: Examples for using &lt;ctrl-ing&gt;.</figcaption><br>
 
-Here is the complete HTML code.
-
-```html
-<!doctype html>
-<html>
-<head>
-    <meta charset='utf-8'>
-    <title>Getting Started</title>
-    <script src="https://cdn.jsdelivr.net/npm/ctrling/ctrling.min.js"></script>
-</head>
-<body>
-    <ctrl-ing ref="obj" autoupdate>
-        [ {"sec":"hdr","text":"Getting Started"},
-          {"sec":"chk","label":"Toggle","path":"$['toggle']"},
-          {"sec":"out","label":"obj=","path":"$"}
-        ]
-    </ctrl-ing>
-    <script>
-        const obj = {
-            toggle: false
-        }
-    </script>
-    </body>
-</html>
-```
-<figcaption>Listing 2: Minimalistic example using <code>&lt;ctrl-ing&gt;</code> element.</figcaption><br><br>
-
-With this example please take note of following points:
-
-* By its `ref="obj"` attribute the `<ctrl-ing>` 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 `<ctrl-ing>` 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 `<ctrl-ing>` element in this example is quite clear.
-
-```html
-<main>
-    <section class="hdr">Getting Started</section>
-    <section class="chk">
-        <label>Toggle<input type="checkbox"></label>
-    </section>
-    <section class="out">
-        obj=<span><output>{
-          "toggle":false
-        }</output></span>
-    </section>
-</main>
-```
-
-## 3. `<ctrl-ing>` Element
-
-The default width of the `<ctrl-ing>` 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 `<ctrl-ing>`s per page &ndash; always right aligned each. In this case the elements should be encapsulated via 
-
-```html
-<div style="position:relative;">
-    <ctrl-ing>...</ctrl-ing>
-</div>
-```
-
-If the `<ctrl-ing>` element should be positioned side-by-side with another (to be controlled) element &ndash; which is frequently the case, the following markup might be used
-
-```html
-<div style="display:flex; position:relative;">
-    <div>...</div>
-    <ctrl-ing>...</ctrl-ing>
-</div>
-```
-
-Following 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.  |
-|`top`  | `0` | Distance relative to top edge of parent element. |
-|`right`  | `0` | Distance relative to right edge of parent element. |
-|`darkmode`  | - | Display GUI menu in dark mode. |
-|`autoupdate`  | - | Automatically update monitoring and input sections. |
-|`tickspersecond`  | `4` | How often to update sections per second. |
-|`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 a static object method. |
-
-The `callback` function or method will be handed over an argument object with the structure
-
-```js
-args = {
-    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 <section> element.
-}
-```
-Please note, that during a single initial call of the `callback` function an empty `args` object will be passed as an argument.
-
-## 4. JSON Sections Overview
-
-| Type | HTML (shadow) | Task |
-|:--:|:--|:--|
-|`btn`  | `<button>` | Perform an action by calling a parameterless function or object method.  |
-|`chk`  | `<input type="checkbox">` | Display a checkbox for entering Boolean parameter values. |
-|`col`  | `<input type="color">` | Display a color menu for setting an RGB color parameter value. |
-|`hdr`  | text string | Header for menu structuring. |
-|`mtr`  | `<meter>` | Graphically monitoring a numerical value in a range. |
-|`num`  | `<input type="number">` | Display an input field for entering a numerical parameter value. |
-|`out`  | `<output>` | Monitoring any data. |
-|`rng`  | `<input type="range">` | Display a slider element for setting a numerical parameter value. |
-|`sel`  | `<select>` | Provides a drop down menu of options. |
-|`sep`  | `<hr>` | Display a separating line for menu structuring. |
-|`txt`  | `<input type="text">` | Display an input field for entering a textual parameter value. |
-|`vec`  | multiple<br>`<input type="text">` | Display a set of input fields for entering multiple related data values. |
-
 ## CDN
@@ -182,5 +82,5 @@
   * 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`](./examples/ctrl-variable.html) for an example.
+  * See [`ctrl-variable.html`](https://github.com/goessner/ctrling/blob/master/docs/examples/ctrl-variable.html) for an example.
 * __Can I control an array ?__
-  * Yes, see [`ctrl-array.html`](./examples/ctrl-array.html) for an example.
+  * Yes, see [`ctrl-array.html`](https://github.com/goessner/ctrling/blob/master/docs/examples/ctrl-array.html) for an example.
 * __Can I convert values while setting ?__
@@ -190,3 +90,3 @@ * Yes.
   * ... or use `callback` function for setting value only.
-  * See [`ctrl-todeg.html`](./examples/ctrl-todeg.html) for an example.
+  * See [`ctrl-todeg.html`](https://github.com/goessner/ctrling/blob/master/docs/examples/ctrl-todeg.html) for an example.
 * __Can you implement feature X and possibly feature Y ?__
@@ -202,2 +102,4 @@ * `ctrling` serves my personal needs very well as it is.
 * First published.
+###  [0.8.23] on January 11, 2023
+* Feature complete.
 
@@ -204,0 +106,0 @@ ## License

No alert changes

Improved metrics

Total package byte prevSize

4653549

increased by8.28%

Number of package files

31

increased by40.91%

Worsened metrics

Lines of code

564

decreased by-0.18%

Number of lines in readme file

106

decreased by-48.04%

No dependency changes