node-red-contrib-uibuilder 6.8.0

<uib-var> and router improvements and more

on Node.js NPM

📌 Highlights

• The <uib-var> HTML component gets

  • This is BIG! - A topic attribute (use instead of the variable attribute) that automatically watches for messages from Node-RED matching the topic and outputs the payload onto the page. This becomes the easiest way to automatically update the page! It is similar to mustache tags ({{varname}}) in frameworks but has the advantage that it is 100% vanilla standard HTML.

  • A filter attribute that can be used along-side variable or topic or on its own. The attribute receives the name of a function to run whenever the source data changes. Use for formatting output. A new function uibuilder.formatNumber has been added that is compatible, it outputs a formatted version of an input number according to the locale and number of decimal places specified. <uib-var topic="mytopic" filter="uibuilder.formatNumber(2, 'de-DE')">[...]</uib-var>. You can, of course, create your own filter functions.

  • Access to your ./index.css style sheet file. This lets output be styled like the rest of your page.

• The uibrouter library gets some serious updates in this version. Including:

  • Automatic menu updates (to highlight the current route). Just make sure to use list items (li) for menu items and give them a data-route="routerid" attribute (where routeid is the actual route id). The currentRoute class & aria-current="page" attribute are both added to entries matching the current route.
  • Route definitions now support title & description properties.
  • New uibuilder variables to use with <uib-var> to show titles and descriptions that update automatically.
  • A fix for a missing default route - the first defined route is used in this case.
  • Other small bug fixes and improvements to the logic.

• The client library gets

  • Connected to a new "global" socket.io "room" allowing uibuilder connected pages to talk to each other. Note that this is still very basic, only the receiver is in place as yet. There is no function to do a global send.
  • New functions joinRoom(room), leaveRoom(room), sendRoom(room, msg) - to interact with arbitrary communication "rooms". Not fully working yet but will eventually allow any uibuilder connect node or client to communicate with 1 or many other connected nodes/clients.
  • A new navigate function and command. Triggers a page change or a route change either from front-end JavaScript or via a command message in Node-RED. Put a client into Kiosk mode and rotate pages or route displays all from Node-RED!
  • A new scrollTo function and command. Scrolls the visible page to a specific location either from front-end JavaScript or via a command message in Node-RED.
  • New UI functions addClass(classNames, el) and removeClass(classNames, el) to make class handling easier.
  • New connect() and disconnect() functions to manually connect/disconnect the Socket.IO connections.

• The importable example flows have been re-organised for easier access. Some new examples added: "Text Update - Different Methods", "FE Router Test"

• No-code and low-code features now all allow more flexible class handling (add, remove, and replace using lists). HTML element data outputs also now return an array of class names, not just a combined string.

• Front-end commands issued from Node-RED can now take a quiet option set to true to prevent the return message. e.g. {"_uib": {"command":"navigate","prop":"#newroute","quiet":true}}

• Front-end developers now have full access to the ui.js library via the $ui global.

uibuilder node

• FIXED Previously, if an editor deployed a uibuilder node with an invalid URL, the node configuration & setup still happened which lead to odd results. Now a missing or invalid URL results in a logged error and the node is not configured. ref

uib-cache node

• FIXED - bug introduced by last version's correction of connections count meant that "Only replay cache when client is really new" option resulted in the cache never being sent.
• Re-worked node's html into latest format with JS in separate resources file.

uib-html node

• Downgrade jsdom version to 21.* as that is the last version that supports Node.js v14.

uib-save node

• FIXED - usePageName logic.
• FIXED - import - initial deployment does not connect to node - need to clear the entry & mark as invalid. Also, no url = invalid
• URL (uibuilder instance) drop-down list is now sorted
• On copy/paste or import, link to uibuilder node is now cleared.

uib-tag node

• FIXED - Allow blanks in some typed input fields.

uib-update node

• FIXED - Allow blanks in some typed input fields.

Client library

• FIXES

  • Some reported client data was incorrect. Notably the connections, and lastNavType properties. The connections property has now been corrected. The lastNavType, I now realise will never be correctly updated by the client and therefore it has been removed. Fixing these has also resulted in some simplification of the client code.

• NEW - $ui is a new global created by the library which gives full access to the ui.js library, that library presents an instance of the Ui class. So typing $ui.version in the browser dev console will return the current version of the ui library. Also available as uibuilder.$ui just in case $ui was already taken when the uibuilder library is loaded.

• NEW managed variable globalMsg - contains the last message received over the global socket. The global socket allows uibuilder connected pages to talk to each other.

• NEW Functions that have Node-RED remote commands

  • navigate(url) - Load a new web page or change routes. Can be triggered from Node-RED with msg {"_uib": {"command":"navigate","prop":"#newroute"}}. See Client Functions (navigate) in the docs for details. URL's can be full, relative (to the current page) or routing (hashes). Obviously, can be called in front-end JavaScript as well as uibuilder.navigate('./page2.html') etc.

  • scrollTo(cssSelector) - Scroll visible page to an element based on a CSS Selector. See Client Functions (scrollTo) in the docs for details. top, start, bottom, end can be used as shortcuts for the top/bottom of the page. An optional 2nd parameter gives more control.

• NEW Functions (without Node-RED remote commands)

  • connect(), disconnect() - These manually connect and disconnect the Socket.IO communications between the browser and Node-RED.

  • formatNumber(value, decimalPlaces, intl, opts) - Compatible with the <uib-var> component's filter attribute. Uses the JavaScript standard INTL library to allow locale-based formatting.

  • keepHashFromUrl() - Returns the route id from the URL.

  • joinRoom(room), leaveRoom(room), sendRoom(room, msg) - allows clients to join/leave/message any arbitrary room

• NEW ui functions - addClass(classNames, el), removeClass(classNames, el) - see ui.js below for details.

• NEW - the client has some early code for dealing with Socket.IO "rooms". These are really a SIO server function but some methods updated to take them into account.

• NEW - the client now subscribes to a new "global" socket.io channel. This allows clients to talk to each other

• Added quiet property to remote command processing. Set msg._uib.quiet to true to stop the library returning a message to Node-RED on completion of the command.

• When using uiGet or nodeGet functions/commands, if class attribute is present, an additional classes property is returned which is an array of the class names.

• Moved $ and $$ functions to ui.js library. This library references them. So no change to usage.

• DEPRECATED Function - elementIsVisible - Was not working correctly and a fix is complex. Will revisit in the future. Let me know if you need this function. This would normally be a breaking change but the function is still there - it returns a console msg and a node-red msg still - and as it wasn't working, I doubt anyone has used it.

uibrouter library

• FIXED Issue #232 - Ensure origin script is removed after re-applying to ensure only 1 instance shows instead of 2.
• FIXED - If no routerConfig.defaultRoute set, now uses the first (zeroth) defined route.
• Version bumped to v1.0.1
• NEW - Route definitions now support title & description properties.
• NEW uibuilder managed variables added to make it easier to use with <uib-var>. [uibrouter_CurrentRoute, uibrouter_CurrentTitle, uibrouter_CurrentDescription, uibrouter_CurrentDetails]. These are automatically updated whenever a route change occurs.
• NEW - routeIds variable is a JavaScript Set containing the list of unique route IDs.
• NEW Functions - routeTitle, routeDescription - return the current route's title and description properties if set or the ID if not.
• NEW Function - currentRoute - returns the current routes configuration object.
• NEW Function - setCurrentMenuItems - Updates any on-page elements matching the selector li[data-route] such that any having a data-route attribute matching the current route id have the currentRoute class & aria-current="page" attribute added. It is removed from all other matches. This makes it very easy to highlight the current route in any on-page menu's.

uib-var custom web component

• NEW: Added topic attribute - auto-monitors for messages from Node-RED with the given topic. msg.payload contains the value to show. Applies filter if present. Just send a msg from Node-RED with the appropriate topic and the display will automatically update! (requires UIBUILDER)
• NEW: Added filter attribute. A filter is a JavaScript function accessible from window global or uibuilder contexts. The filter is applied to the variable value before display. Can now supply ONLY the filter attribute (without variable or topic). This allows arbitrarily complex processing.
• Auto load ./index.css instead of ../uibuilder/uib-brand.min.css - enables your own custom styling to be used. Not dependent on UIBUILDER, simply serve index.css from the same location as your main page.
• When using UIBUILDER, the resulting HTML output is sanitised if you have the DOMPurify library loaded. If the output is a JavaScript object, it will be highlighted using uibuilder's standard JSON highlighter.
• Improved error handling, especially for the filter attribute and its processing.

ui.js low-code->HTML hydration library

• NEW functions - addClass(classNames, el), removeClass(classNames, el) - Add/remove classes individually. classNames can be a single class name, or an array of class names. For removeClass, an empty string, null or undefined can be used to remove all classes (removes the class attribute).

• When using uiGet or nodeGet functions/commands, if class attribute is present, an additional classes property is returned which is an array of the class names.

• Improved separation between payload and content in "alert" and "notify" methods.

• Allowed low-code attributes property to be an array when specifying classes to apply. All classes in the array will be applied.

• Moved $ and $$ functions to this library from uibuilder.

uib-brand.css

• body left/right margins are now set by a CSS var --base-margin so they can be adjusted more easily.
• Added new variable --emoji-fonts. Use as font-family: var(--emoji-fonts); for better emoji's. Used by custom bullets below.
• Added li.check (AKA li.completed), li.uncheck (AKA li.unstarted), and li.started classes which change list bullets to ✅, ❌, and ✔️ respectively.
• Added ui.checklist with --base-margin left/right margins and a little more space for the check bullets.
• Added basic nav menu formatting using nav tag. Including basic horizontal menu (nav.horizontal class) formatting. Assumes list embedded in a nav tag and that the list has correct aria roles set.

Examples (import flows from Node-RED library)

• Re-organised & renamed examples now there are more of them.
• NEW - "Text Update - Different Methods" example
• NEW - "FE Router Test" example

Documentation

• Heading levels 3+ have been made lighter to better differentiate them visually.
• The front-end client functions page now has an alphabetical list of functions.
• Improved low-code documentation for the notify and alert methods.
• Restructured config files for better future updates. Fixed some niggles.

Other

• FIXED uibuilder's instance debug page was not working. Now fixed.
• The list of all uibuilder apps available at /uibuilder/apps is now sorted by URL. Don't forget that it also uses the description fields of each uibuilder node.
• More work done to move all filing system access into the single libs/fs.js library.
• Usual ongoing work to tidy, clarify and simplify code & eliminate any small issues.
• All nodes now have an Editor property addType which is set to 1 of 'load', 'new', or 'paste/import'. Allowing processing to differentiate between different circumstances that add nodes to the flow.