New Case Study:See how Anthropic automated 95% of dependency reviews with Socket.Learn More →

ctrling

Package Overview

Dependencies

Advanced tools

Install Socket

Detect and block malicious and high-risk dependencies

Install

ctrling

An appealing prototypical GUI for controlling your Web-App, JSON or JavaScript Object Values

0.8.2
Source
npm

Version published: 2 years ago

Weekly downloads: 11; decreased by-47.62%

Maintainers: 1

Weekly downloads

Created: 2 years ago

Source

`ctrling`

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:

tiny footprint 18.7/11.3 kB un/compressed.
dependency free.
easy prototypical generation with low effort.
no programming required.
getting a pleasing GUI.

Fig. 1: Controlling an Animation.

The interactive menu for this example 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 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 <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> element's shadow DOM 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. Getting Started

Let's start with a minimal example resulting in this controlling menu.

Fig. 2: Minimal <ctrl-ing> Example.

Here is the complete HTML code.

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

Listing 2: Minimalistic example using <ctrl-ing> element.

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 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 this example is quite clear.

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

`<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 the HTML page. This might be fine-adjusted via top and right attributes.

We can use multiple <ctrl-ing>s per page. In this case the elements should be encapsulated via

<div style="position:relative;">
    <ctrl-ing>...</ctrl-ing>
</div>

If the <ctrl-ing> element should be positioned side-by-side with another element – which is frequently the case, the following markup might be used

<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 sections.
`tickspersecond`	`4`	How often updating monitoring sections per second.
`callback`	-	If present, will be called with each value change of input sections. The attribute value must obey the JSONPath syntax rules and might be a global function or an object method.

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

Changelog

[0.8.1] on December 20, 2022

First published.

License

ctrling is licensed under the MIT License

Keywords

FAQs

What is ctrling?

Is ctrling popular?

Is ctrling well maintained?

Package last updated on 20 Dec 2022

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install