Updates

CHANGELOG.md

@@ -37,6 +37,7 @@ Please see the documentation for archived changelogs - a new archive is produced
 
 ### Ideas
 
+* Consider adding 2nd parameter to `$` and `$$` to allow returning something other than the found element. [Ref](https://www.npmjs.com/package/x-ray#xrayurl-selectorfn) - e.g. `text`, `html`, `attributes`
 * Change runtime parameter passes of `uib` to `globalThis['ti-uibuilder'].uib`
 * Consider moving all handling of uib's package.json into a single lib. Only allow a single function to read/write/update
 * Add Vue-style dynamic attributes: [ref1](https://claude.ai/chat/0c494f54-758c-4f14-a8c7-90dbe6b2c5d7), [ref2](https://chatgpt.com/c/7b797547-4e7e-455d-927b-926de42171aa).
@@ -45,6 +46,9 @@ Please see the documentation for archived changelogs - a new archive is produced
   * enableOnEdit (optional) If set to true, this tab will be accessible whilst the edit dialog is open. Default: false.
 * Consider adding a uibuilder custom library - [ref](https://github.com/node-red/node-red-library-file-store).
 
+### `uib-router` library
+
+
 ### `uibuilder` node
 
 * [ ] ?? Filter `clientId` and `pageName` using socket.io rooms?
@@ -55,10 +59,7 @@ Please see the documentation for archived changelogs - a new archive is produced
 
 * [ ] Amend to use same processors as the uib-topic?
 * [ ] Add ability to directly amend the tag's attributes.
-* [x] Add TABLE renderer
-* [x] Add LIST renderer
-* [x] Add Markdown rendered
-* [ ] New Example: Easy Updates
+* [x] New Example: Easy Updates
   * [ ] Add uib-topic attrib examples
 * [ ] Update docs: 
   * [ ] custom-components
@@ -82,6 +83,23 @@ I will attempt to also trap a new project create to run the install if I can. Ot
 
 * Extend SVG example to download and save the svg from the gist
 * [ ] Check ui.js fns that are direct referenced in the fe lib for use of `this`. Change to use static vars if possible.
+* [ ] Use of `msg._client`
+  * [ ] Msgs from FE client
+    * [x] Check headers for:
+      * [x] FlowFuse auth
+      * [x] CloudFlare auth
+      * [x] Authelia auth
+    * [x] Create `msg._client` and populate with std props, add to output msg - for both std and ctrl msgs
+  * [ ] Msgs from node-red flows
+    * [ ] ??
+  * [ ] Msgs to FE client
+    * [ ] ??
+  * [ ] Example?
+  * [ ] Documentation
+    * [ ] Describe what headers are understood, where they come from.
+    * [ ] Describe `msg._client` properties
+    * [ ] How to block in/out client msgs based on `msg._client` - e.g. use of the new hooks.
+    * [ ] How to redirect un-auth web requests to login page
 * Update examples:
   * [ ] [started] Update text update example to include new `uib-topic` html attributes
   * [ ] Template Examples - remove old library example.
@@ -102,6 +120,9 @@ I will attempt to also trap a new project create to run the install if I can. Ot
 
 ### `uibrouter` FE library
 
+* breaking change - load external routes into `<template>` tags, default to load all external routes immediately (with flag to change)
+* Add optional attribute to `<script>` tags in routes. `runonce` or `data-runonce` will only ever be run once for a page load. Consider if `runload` and/or `runall` might also be useful.
+
 * [ ] ? Option to load route config from a file ?
 * [ ] Add md rendering to `loadOther`
 * [ ] Allow config updates from Node-RED
@@ -267,7 +288,7 @@ Most of these changes will *not* impact most people but you should check through
   At least 1 person hit a race condition. [ref](https://discourse.nodered.org/t/uib-brand-css-sometimes-injected/78876). So this is best removed.
 
 * `jsdom` (using in the `uib-html` node) now tracks the latest releases again
- 
+
   Shouldn't be breaking at all but you might still want to review things since the new versions of `jsdom` are likely to have better available features. We were restricted to jsdom v21 previously as newer versions required node.js v18+.
 
 * `ejs` package removed
@@ -431,6 +452,8 @@ The `URL Output?` setting will change the output from a folder/file list to a re
 
 * **NEW Web Component** - `<apply-template>` Takes the content of a `<template>` HTML tag and appends that content as children of itself. Allowing you to re-use standard, repeatable HTML without the need for JavaScript coding and without the need of sending potentially lengthy HTML from Node-RED every time it is needed.
 
+* **UPDATED Web Component** - `<uib-var>` now "table" and "list" output types to go with the existing "text", "html" and "markdown" types.
+
 * **NEW FUNCTIONS**
 
   * `Element.prototype.query(cssSelector)` and `Element.prototype.queryAll(cssSelector)` Similar to `$(cssSelector)` and `$$(cssSelector)` respectively. However, instead of searching the whole document, they search a sub-set of the document within the given element.
@@ -543,7 +566,7 @@ The `old-blank-client` template and all associated documentation has also been r
 ### Example Flows
 
 * `no-code-examples` - Updated to include dynamic script and css in the HTML passthrough example.
- 
+
 ### `uibuilder` node
 
 * **NEW** Previously, a link and button to edit front-end code using VScode would be shown if running on localhost. This has now been changed. There is a field on the Advanced tab that lets you set any URL for any IDE or Code Editor that supports them. In addition, as well as for localhost, uibuilder will try to give a reasonable guess for a remote VSCode edit session. Though there is a good chance you will need to set this up in VScode and adjust the link accordingly.

docs/roadmap/readme.md

@@ -3,7 +3,7 @@ title: uibuilder Roadmap
 description: |
   This page outlines the future direction of uibuilder. Including specific things that will almost certainly happen as well as more speculative ideas.
 created: 2022-02-01 11:15:27
-updated: 2024-07-21 15:44:10
+updated: 2024-07-29 15:55:53
 ---
 
 Is there something in this list you would like to see prioritised? Is there something you could help with? Please get in touch via the [Node-RED forum](https://discourse.nodered.org/). Alternatively, you can start a [discussion on GitHub](https://github.com/TotallyInformation/node-red-contrib-uibuilder/discussions) or [raise a GitHub issue](https://github.com/TotallyInformation/node-red-contrib-uibuilder/issues). Please note that I no longer have the time to monitor the #uibuilder channel in the Node-RED slack.
@@ -120,6 +120,7 @@ Vars moved to ti-common (replace): node.urlPrefix, node.nodeRoot, paletteCategor
 * `uib-file-change` - Watches for changes to files for a specific uibuilder instance. Allow folder choice, filtering (via fast-glob). Triggers an output on-change. Output can be a folder/file list OR a URL list (or maybe both). Could then be used to simply reload any connected clients automatically, trigger backups or something else entirely.
 * `uib-ctrl` - route different types of control msgs to different output ports: `cache` ("client connect"), `network` ("client connect", "client disconnect"), `visibilty`, `routing` ("route change").
 * `uib-event` - Outputs uibuilder standard messages (or maybe both std and control) but is separate from the uibuilder instance node and can be filtered by user, client, page as well as the instance. May be helpful to some people to simplify flows without using lots of link nodes.
+* `uib-fe-event` - captures actual front-end events (e.g. custom events) and forwards them to Node-RED either as std or ctrl (?messages.
 * `uib-file-read` - Reads a file for a specific uibuilder instance. Allows, for example, the file to be passed to the FE for editing.
 
 #### Maybe

docs/using/compare-d2.md

@@ -4,7 +4,7 @@ description: |
   UIBUILDER has a significantly different design philosophy to Node-RED's Dashboard 2.
   This page examines some of the key differences, their potential impacts and different workflows.
 created: 2024-06-21 10:14:56
-updated: 2024-07-17 18:05:43
+updated: 2024-07-29 20:06:32
 ---
 
 Please do not use this comparison table to criticize one approach or the other, both approaches are deliberately different. Giving greater choice and flexibility for Node-RED users. Also note that I am much more familiar with UIBUIDER as its main author than I am of Dashboard 2.0, updates and corrections are always most welcome.
@@ -21,12 +21,15 @@ The following table is not in any specific order of importance.
 | Custom web elements                                          | Allows for any level of custom web page. The base page is set using a template but can be fully edited as needed.<br />Additionally, widgets and/or HTML and/or Markdown can easily be sent to or loaded into any page. | Custom web code requires the `ui_template` node. This can load custom code to the head and body but the structure of the page cannot be altered. |
 | **User management**. Note that socketId is not stable and will change if the browser tab or client device enters sleep. | Has *socketId, ClientID, tab id, IP Address, and page name* data available to all responses. Can optionally include rich client data in Node-RED output messages.<br />ExpressJS & Socket.IO middleware available for additional user and session interactions. | By default, only has *socketId and socketIp*. Requires additional plugins for richer data. |
 | User/client specific information                             | Data sent to a uibuilder node will be *automatically filtered* by *socketId, clientID and page name* if provided. Otherwise is broadcast to all clients connected to that uibuilder node.<br />Some limited provision for dedicated Socket.IO "rooms" also available - this also allows user-to-user comms. | Data is sent to individual ui widget nodes. It is automatically filtered by `msg._client` if provided.<br />No known provision for using rooms. None for client-to-client comms (without using a manual flow). |
+| Handling externally authenticated clients                    | Integrated recognition of authenticated client HTTP headers from most proxy integrations including Authelia & others. Also for FlowFuse and CloudFlare access authentications. Automatically adds `msg._client` to messages from the authenticated client.<br />Also provides `socketIoHeaders`, `clientDetails`, `msgReceived`, and `msgSending` "hook" functions to allow fine-grained control & monitoring. | Plugin modules available for FlowFuse, Cloudflare Access, and Authelia. Adds `msg._client` to messages for authenticated client connections. |
 | Sending data from Node-RED to clients                        | All messages go via the `uibuilder` node. Segmented of flows should use core link nodes or the uib-sender node.<br />Messages are filtered by *socketId, clientID and page name* if that data is provided.<br />There are 4 options, see [Easy UI updates](http://127.0.0.1:1880/red/uibuilder/docs/#/using/easy-ui-updates) for details:<br />1. *The custom `uib-topic` attribute on any HTML tag* will auto-process incoming data.<br />2. *The custom `<uib-var>` component* also auto-processes data and has some additional rendering options such as json, table and list.<br />3. *Front-end JavaScript code* can listen for incoming data manually using the `uibuilder.onChange('msg', (msg)=>{...})` or `uibuilder.onTopic('topicname', (msg)=>{...})` functions.<br />4. No-code and low-code nodes can directly update identifiable on-page elements. | Messages are sent to individual ui widget nodes.<br />Messages can be manually processed using a `ui-template` node utilising the `this.$socket.on()` function.<br />Custom nodes may require use of a `watch` handler. [Ref](https://discourse.nodered.org/t/dashboard-2-radio-group/89495) |
 | Receiving data from clients to Node-RED                      | Front end code can use either the `uibuilder.send({...})` or `uibuilder.eventSend(event)` nodes to return data to Node-RED. `eventSend` is specifically designed to be attached to any HTML event but notably input tags, it gathers detailed information about any input and coordinates surrounding HTML Form data if the event happens within a form.<br />Some built-in uibuilder functions also automatically send data to Node-RED.<br />No-code elements will automatically return data to Node-RED where that makes sense.<br />Received messages are output from the top port of the uibuilder node (except for a `uib-sender` node configured for automatic return). | Dashboard widgets that accept input will automatically return data to the widget node. |
+| **Client events**. Background events triggered by a client such as changing pages. | Client events are received at port #2 of a uibuilder node as control messages. *Socket.IO connect/disconnect*, *cache replay/clear*, *page visibility change*, and *router page* change are the main built-in events. Custom events allowed by allowing control messages to be sent. Front end `uibuilder.eventSend(event)` function allows HTML events with standard content to be returned as standard messages. | `ui-events` node is required. `$pageView`/`$pageLeave`  are fired when a route page changes. |
 | Web page layouts                                             | No pre-defined layouts. An optional, provided CSS file contains a base configuration for HTML5 style general layouts along with some helper classes for grid, flex and other more granular layouts.<br />Because uibuilder uses standard HTML, 3rd-party layout editors can be used to create custom layouts. | Has [3 layout types](https://dashboard.flowfuse.com/layouts/): grid, fixed and notebook. Layout configuration follows Dashboard 1 controls in the Node-RED Editor. |
 | Markdown content                                             | Allows the use of the Markdown-IT library as an external (optional) resource allowing library updates separate to uibuilder. Also allows for any Markdown-IT *plugins*. Could easily be extended in the future to use alternative libraries.<br />Lots of ways to support static (file-based) and dynamic (msg or code-based) Markdown content. Message and other dynamic content can be included in Markdown text by using the the `<uib-var>` web component.<br />The Markdown-IT library can be loaded via a message from Node-RED or included in low-code output.<br />The optional front-end router library (for creating single-page apps) also fully supports Markdown in the same way. Allowing UIBUILDER to be used as a content management system. | Embeds the Marked library. Updates require a new version to be released. Mermaid chart plugin included but no direct provision for others.<br />Markdown content limited to the `ui-markdown` node. Message content can be included in Markdown content using Mustache style `{{ ... }}` markup. |
 | **Front-end frameworks**. Typically, large collections of code that support the dynamic management of front-end UI's. | Allows any or no framework. No framework is required to work but any can be used if desired. Note that some frameworks require pre-definition of pages (or lots of dynamic processing as in the case of Dashboard) and so some uibuilder features may not be compatible. | Fixed at using VueJS v3 with VueX and Vuetify.               |
-| **Front-end libraries**. Additional features that run in the browser and linked to the current page. | Built-in library manager enables installation, update and removal of libraries from npm (to allow runtime use without Internet), GitHub or local (server) code. Uses standard npm tooling under the skin. Resulting URL's are all catalogued and shown.<br />Managed libraries are automatically made into Node-RED web endpoints for easy loading onto web pages. Information is provided on the most likely link URL required to use each library.<br />Library links are manually added to `.html` files or can be dynamcially added using no-/low-code features. | No management of libraries available. Any libraries must be manually included onto pages using a `ui-template` node or pre-built into core or contributed nodes.<br />For use without the Internet at runtime, libraries must be manually installed somewhere that Node-RED can serve them and the appropriate URL worked out. |
+| **Front-end libraries**. Additional features that run in the browser and linked to the current page. | Built-in library manager enables installation, update and removal of libraries from npm (to allow runtime use without Internet), GitHub or local (server) code. Uses standard npm tooling under the skin. Resulting URL's are all catalogued and shown.<br />Managed libraries are automatically made into Node-RED web endpoints for easy loading onto web pages. Information is provided on the most likely link URL required to use each library.<br />Library links are manually added to `.html` files or can be dynamically added using no-/low-code features.<br />Socket.IO client library is integrated into the uibuilder client library. | No management of libraries available. Any libraries must be manually included onto pages using a `ui-template` node or pre-built into core or contributed nodes.<br />For use without the Internet at runtime, libraries must be manually installed somewhere that Node-RED can serve them and the appropriate URL worked out. |
+| **Application Style** (Single- vs Multi-Page)                | *Multi-page by default*. Each `uibuilder` node defines a new front-end app that contains a minimum of a default page. Any number of static sub-folders and pages can be defined. Custom API's can also be defined for dynamic endpoints.<br />*Single-page apps also possible* by using the built-in `uib-router` JavaScript library. Allows pseudo-pages to be defined from static files or `<template>` sections in the html file. Router pages can be un/-re-loaded or hidden/shown as desired on route changes.<!-- what about data retention --> | *Single-page app* (SPA) only. (Multi-page is planned for the future). Each defined "page" is a route in the SPA. Router pages unload all page widgets on route change. |
 | **SPA Routing**. Creating single-page web UI's that simulate multi-page through the use of a front-end *router*. | Optional. Uses the provided `uib-router` JavaScript library. Updates require a new version of uibuilder.<br />Routes and other settings are indepentent of uibuilder. The router can actually be used without uibuilder.<br />uibuilder is a *multi-site, multi-page* creator by default that also allows SPA creation via the optional router. | Built-in. Uses the pre-integrated 3rd-party `vue-router` package. Updates require a new version of Dashboard.<br />Configuration of routes is tied to the Dashboard configuration.<br />Dashboard 2 is *an SPA* creator but allows you to create multiple Dashboards. |
 | Server page routing                                          | Multiple folders & pages part of inherent design and defined as static resources in the filing system.<br />Dynamic routes are available via the routing API, defined as Node.JS module files.<br />Server-side rendering is also available.<br />The uibuilder node's `url` setting is always used as the base url. It may be altered which will rename the server folders as well as the url on re-deployment. | New static routes will eventually be definable (not yet available) by defining a new `ui-base` config node.<br />URL is currently _fixed_ as `./dashboard`. |
 | **Dynamic code** (as opposed to dynamic data). HTML, CSS or JS code sent to clients | Should rarely be needed since static code files are preferred, generally more performant and more secure. However, uibuilder allows HTML, Markdown, CSS and JS code to be sent when needed. It can also update static files from within Node-RED flows. |                                                              |