Skip to content

Commit

Permalink
Correct/improve
Browse files Browse the repository at this point in the history
  • Loading branch information
@TotallyInformation
TotallyInformation committed Mar 5, 2023
1 parent 7982aac commit 948bbc1
Show file tree
Hide file tree
Showing 5 changed files with 175 additions and 119 deletions.
29 changes: 14 additions & 15 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,15 +8,13 @@ Please see the documentation for archived changelogs - a new archive is produced

## Notes for the current version

v6.1.0 makes the new client libraries (`uibuilder.esm.min.js` and `uibuilder.iife.min.js`) current and the old client library (`uibuilderfe.js`) is now no longer recommended and is not being updated, it is on the road to being deprecated.
v6.1.0 makes the new client libraries (`uibuilder.esm.min.js` and `uibuilder.iife.min.js`) current and the old client library (`uibuilderfe.js`) is now no longer recommended and is not being updated, it is on the road to being deprecated (it will remain until at least v7, mahbe v8 but probably not longer unless someone calls for it).

The experimental `uib-list` node will now be deprecated, the features are moved to the new `uib-element` node.
The experimental `uib-list` node is now deprecated, the features are moved to the new `uib-element` node. It will be removed certainly by v7.

The new `uib-brand.css` style library is not yet feature complete - if you find something missing or wrong, please raise an issue.
The new `uib-brand.css` style library is not yet feature complete - if you find something missing or wrong, please raise an issue. It does, however, continue to develop.

Dynamic content does not currently work with VueJS (and probably not other frameworks that rely on pre-building components). Such frameworks _require_ both the components and the structure to be pre-defined _before_ the DOM is fully loaded. They have their own methods to provide dynamic includes, lazy loading, etc that are very different (and generally much more complex) than uibuilder's simple to use feature. **However**, dynamic content _DOES_ work with HTML components. The component definitions have to be loaded before you use them (that can be dynamic too!) and you _must_ use the ESM build of the uibuilder client library since HTML Components are ES Module only. And of course, it is possible - but probably less useful - to combine the vanilla HTML from the low-/no-code features with front-end frameworks such as Vue.

Context store handling currently does not cope with stores that require asynchronous setters/getters. [ref](https://discourse.nodered.org/t/context-stores-maybe-async-but-how-can-we-tell/75190/2?u=totallyinformation).
Dynamic content does not currently work fully with VueJS (and probably not other frameworks that rely on pre-building components). It is possible though to combine the vanilla HTML from the low-/no-code features with front-end frameworks. Such frameworks _require_ both the components and the structure to be pre-defined _before_ the DOM is fully loaded. They have their own methods to provide dynamic includes, lazy loading, etc that are very different (and generally much more complex) than uibuilder's simple to use feature. **However**, dynamic content _DOES_ work with HTML components and any frameworks that are compatible with them such as _Svelte_. The component definitions have to be loaded before you use them (that can be dynamic too!) and you _must_ use the ESM build of the uibuilder client library since HTML Components are ES Module only.

## To do/In-progress

Expand Down Expand Up @@ -180,20 +178,27 @@ Check the [roadmap](./docs/roadmap.md) for future developments.

* Added a default `msg.topic` option. `uibuilder.set('topic', '....')` Will be used in msgs sent back to node-red if no topic specified. Note that if the default topic is not set, messages will inherit the topic from the _previous inbound message_ if that had a topic. Reset by setting to an empty string.

* Added **new functions**
* The following client functions can now be called direct from Node-RED via a msg like: `{_uib: {command:"showMsg", value:true}}`. get, set, showMsg, showStatus. More will follow in the next release.

* `uibuilder.syntaxHighlight(json)` - Converts JSON/JavaScript object into highlighted HTML. Useful for debugging messages sent from/to Node-RED. This used to be in each template so you don't need it there any more.
* Added **new functions**

* `uibuilder.showMsg(true, selector=body)` - Adds a visual display of incoming messages from Node-RED to the web page. Use `uibuilder.showMsg(false)` to remove it. `selector` is a CSS selector to use as the parent position. Will always show the last incoming standard msg from Node-RED.

* `uibuilder.showStatus(true, selector=body)` - Adds a visual display of the current status of the client library. Use `uibuilder.showMsg(false)` to remove it.`selector` is a CSS selector to use as the parent position. May be helpful when trying to debug pages and connectivity, especially from mobile devices.

* `uibuilder.uiGet(cssSelector, propName=null)` - Get most useful information, or specific property from a DOM element
* `uibuilder.syntaxHighlight(json)` - Converts JSON/JavaScript object into highlighted HTML. Useful for debugging messages sent from/to Node-RED. This used to be in each template so you don't need it there any more.

* `uibuilder.uiGet(cssSelector, propName=null)` - Get data from the DOM. Returns selection of useful properties unless a specific property requested.

Data can be sent straight back to Node-RED: `uibuilder.send( uibuilder.uiGet('input') )` (gets all useful properties from all `input` fields on the page).

* `uibuilder.watchDom(true)` - Starts watching the content of the page and saves it to browser localStorage so that it can be recovered at any time. Use `uibuilder.restoreHtmlFromCache()` to recover the stored HTML (e.g. on page load). Use `uibuilder.watchDom(false)` to turn off and `uibuilder.clearHtmlCache()` to remove the saved HTML. If desired, you can also manually save the HTML at any point using `uibuilder.saveHtmlCache()`.

* `uibuilder.beaconLog(txtToSend, logLevel)` which allows sending a simple, short log message back to Node-RED even if socket.io is not connected. In Node-RED, outputs to the Node-RED log and sends a uibuilder control message where `msg.uibuilderCtrl` = "client beacon log". _Still somewhat experimental and may not always work reliably_.

* `uibuilder.logToServer()` which will take any number and type of arguments and send them all back to Node-RED in the msg.payload of a _control_ message (out of port #2) where `msg.uibuilderCtrl` = "client log message". Client details are added to the message. _Still somewhat experimental and may not always work reliably_.


* Added a unique tab identifier `uibuilder.tabId` that remains while the tab does. Is include in std outputs. Based on [this](https://stackoverflow.com/questions/11896160/any-way-to-identify-browser-tab-in-javascript). NOTE however, that duplicating the browser tab will result in a duplicate tab id.

* Added `uibuilder.isVisible` property. Is true when the browser tab containing the page is actually visible. On visibility change, sends a new control msg `msg.uibuilderCtrl` = "visibility" with the property `isVisible` true or false. Does not send this when the page loads but does set the property. Uses the document `visibilitychange` event.
Expand All @@ -208,14 +213,8 @@ Check the [roadmap](./docs/roadmap.md) for future developments.

* Added a `position` property to the `add` _ui mode. "first"/"last": Adds start/end of parent's children respectively. An integer will add the element after the nth child.

* Added **new function** `uibuilder.uiGet(cssSelector [, propName])` - Get data from the DOM. Returns selection of useful properties unless a specific property requested.

Data can be sent straight back to Node-RED: `uibuilder.send( uibuilder.uiGet('input') )` (gets all useful properties from all `input` fields on the page).

* Added a **new ui handler** `removeAll` and updated the handler function with an optional 2nd parameter to remove all (rather than the 1st) matching elements.

* Added **new function** `uibuilder.watchDom(true)` - Starts watching the content of the page and saves it to browser localStorage so that it can be recovered at any time. Use `uibuilder.restoreHtmlFromCache()` to recover the stored HTML (e.g. on page load). Use `uibuilder.watchDom(false)` to turn off and `uibuilder.clearHtmlCache()` to remove the saved HTML. If desired, you can also manually save the HTML at any point using `uibuilder.saveHtmlCache()`.

* Added 2 new events: `uibuilder:constructorComplete` and `uibuilder:startComplete`. Mostly for potential internal use.


Expand Down
43 changes: 25 additions & 18 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -87,15 +87,35 @@ There is a library of "official" [video tutorials on YouTube](https://www.youtub
The purpose of uibuilder is to:

* Support easy methods for creating and delivering data-driven web apps and web pages (also known as web User-Interfaces).
* Be a conduit between Node-RED and a front-end (browser) UI web app.
* Be UI framework agnostic. While VueJS is often used with uibuilder, it isn't a necessary dependency. Indeed no framework is needed to use uibuilder.
* Be a conduit between Node-RED and front-end (browser) UI web apps.
* Be UI framework agnostic. No framework is needed to use uibuilder but it will work with them where desired. uibuilder aims to reduce the requirement for a framework by making it easier to work with vanilla HTML/CSS.
* Provide interface/data standards for exchanging data and controls between Node-RED and the web pages.
* Enable the creation and management of multiple web apps from a single Node-RED instance.
* Reduce the amount of front-end code (HTML/JavaScript) needed to create and manage a web app.
* Reduce the knowledge required for creating reliable, accessible web apps by providing low-code and no-code features.
* Make it easy to install and serve front-end libraries to support the development of more complex web apps.

## Features

The core features of uibuilder:

* Provides nodes to enable zero-code translation of input data to usable and accessible web elements.
* Provides capability for low-code, configuration-driven (data-driven) UI's. Creating a framework for describing a UI and translating to actual code without having to write code.
* Provides a 2-way communications channel between the Node-RED server (back-end) and front-end UI.
* Provides a Node-RED node to act as the focus for communications with other nodes for additional ease of use.
* Provides a front-end library to: do the complex parts of the communications in the client browser; make manipulation of the UI easier and more consistent; make it easy to get data back to Node-RED as needed (both automatically and manually).
* Provides easy to use templates and examples for front-end code to enable people to get a quick start on creating web apps.
* Provides management and serving of npm packages that provide front-end libraries consumable easily by front-end code.
* Allows editing of front-end code from the Node-RED Editor (designed for small changes, use web development tools generally).
* Enables the use of external authentication and authorisation methods and services to control multi-user access to web apps.
* Provides various server middleware and API options for additional custom capabilities.
* Allows as many uibuilder node instances as you like. Each instance allows the creation of many web pages and sub-folders for easy management.
* Each uibuilder node instance provides a private 2-way communications channel between the Node-RED server (back-end) and browser (front-end) UI code.
* Supports the use of standard web development workflows.
* Allows the creation of a dedicated web service to facilitate independent security.
* Provides a caching capability allowing newly joining clients to receive the latest data and configurations. Joining/leaving clients create notifications in Node-RED.


<details><summary>No-code UI's</summary>

uibuilder is still growing towards offering more no-code capabilities like Node-RED's Dashboard extension does. However, it is starting to offer these features via the "new" client available since v5. V6.1 introduced the new `uib-element` and `uib-update` nodes that offer the first usable no-code features.
Expand All @@ -114,27 +134,14 @@ The data that `uib-element` outputs is a format that you can use in your own flo
The schema and the UI creator functions built into the front-end client are specifically designed to work with current and future HTML standards in order to avoid the kinds of issues commonly encountered when using 3rd-party front-end frameworks (e.g. major version changes forcing rewrites of all of your tooling). So ES Modules, ECMA Components, and future ECMA versions should all be supported.
</details>

<details><summary>Core features</summary>

* Provides a Node-RED node to act as the focus for communications and installation of front-end packages for use in your code.
* Allows as many uibuilder node instances as you like. Each instance allows the creation of many web pages and sub-folders for easy management.
* Each uibuilder node instance provides a private 2-way communications channel between the Node-RED server (back-end) and browser (front-end) UI code.
* Provides a front-end library to do the complex parts of the communications and to help standardise interactions with the Node-RED server.
* Provides templates for front-end code to enable people to get a quick start on creating web apps.
* Allows management and serving of npm packages that provide front-end libraries, consumable easily by front-end code.
* Allows editing of front-end code (designed for small changes, use web development tools generally).
* Supports the use of standard web development workflows.
* Provides a capability to have low-code, configuration-driven (data-driven) UI's. Creating a framework for describing a UI and translating to actual code without you needing to write code.
* Provides nodes to enable zero-code translation of input data to usable and accessible web elements.
* Allows the creation of a dedicated web service to facilitate independent security.
* Provides a caching capability allowing newly joining clients to receive the latest data and configurations. Joining/leaving clients create notifications in Node-RED.
</details>

<details><summary>Future direction</summary>

The general direction of uibuilder (or associated modules) is likely to include:

* Provide more no-code and low-code UI creation and update capabilities. As of v6.1, these are now starting to be delivered.
* Provide more no-code and low-code UI creation and update capabilities. As of v6.1, these are now starting to be delivered, v6.2 will extend these.
* The ability to save updated HTML from the front-end via Node-RED so that UI building can be done once and loaded as efficient, static HTML.
* The ability to use the zero-code features to produce HTML for other tools to use.
* The ability within Node-RED to, for each uibuilder node, run npm scripts such as build processes and to manage instance-level npm packages.
* Be able to install/update/remove instance-level npm packages as can already be done for uibuilder-level packages.
* Provide a "development server" capability that auto-reloads connected clients when code changes are made.
Expand Down
Loading

0 comments on commit 948bbc1

Please sign in to comment.