diff --git a/CHANGELOG.md b/CHANGELOG.md index 7e917257..ed7348e9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,23 +6,204 @@ typora-root-url: docs/images Please see the documentation for archived changelogs - a new archive is produced for each major version. Check the [roadmap](./docs/roadmap.md) for future developments. +## Issues + +None. + +### "Outdated" dependencies + +Unfortunately, for various reasons, some of the package dependencies that UIBUILDER relies on cannot be updated to their latest versions. These are documented, with the reason, here. + +* `execa` - restricted to v5. Author sindresorhus decided that everyone HAS to use ESM even though his packages are widely used and he must know that it is often impossible to move from CommonJS without a complete rewrite. Node-RED is so complex, when would that be possible? Very annoying. +* `jsdom` - restricted to v21. Later versions require node.js >v14 but Node-RED is still baselined at v14. Requires update to Node-RED to release this. +* `nanoid` - restricted to v3. Another annoying sindresorhus node. + +These are only used for developing UIBUILDER so somwhat less critical. + +* `@types/node` - restricted to v14 to match Node-RED's current baseline. +* ~~`gulp-debug` - restricted to v4. Another annoying sindresorhus node.~~ Removed in v6.8 + +I will be trying to eliminate packages that have enforced structural changes. The author's arrogance is palpable. + ------------ -## [Unreleased](https://github.com/TotallyInformation/node-red-contrib-uibuilder/compare/v6.7.0...main) +## [Unreleased](https://github.com/TotallyInformation/node-red-contrib-uibuilder/compare/v6.8.0...main) Nothing currently. +## [v6.8.0](https://github.com/TotallyInformation/node-red-contrib-uibuilder/compare/v6.7.0...v6.8.0) + +### 📌 Highlights + +* The `` 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. `[...]`. 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 `` 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](https://discourse.nodered.org/t/uibuilder-new-release-v6-7-new-front-end-router-improvements-to-uib-html-uib-save-and-more/83106/4) + +### `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](client-docs/functions#navigate) 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](client-docs/functions#scrollTo) 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 `` 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](https://github.com/TotallyInformation/node-red-contrib-uibuilder/issues/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 ``. [`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. + ## [v6.7.0](https://github.com/TotallyInformation/node-red-contrib-uibuilder/compare/v6.6.0...v6.7.0) ### Highlights * The new front-end routing library is available. Easy to use, robust and reasonably comprehensive. It is not dependent on uibuilder but offered with it to enable Single-Page Apps (SPA's) to be easily created with uibuilder. * The `uib-html` node now allows an HTML string wrapper. This defaults to uibuilder's default "Blank" template HTML or can be overridden using `msg.template`. This lets you create a fully working page from no-code and low-code configurations that can be fed direct to `uib-save` or used in Dashboard or with http-in/-out nodes. Or indeed with external web server tools. +* A new method of easily getting dynamic updates onto the web page has been added, the `` tag. ### New client library - uibrouter - front-end routing library A complete, standalone library for doing front-end routing with both internal and external templates. Lightweight and simple to use. See the [documentation](docs/client-docs/fe-router.md) for details. +### New client custom web component `` + +The `` tag provides an easy way to get dynamically updated content into your web page. See the examples library and the documentation for more details. In this release, allows the specifying of a managed uibuilder variable which will be inserted into the page and automatically updated whenever the variable updates. This is similar to mustache tags in many front-end frameworks (`{{myvar}}`) but, unlike those frameworks, is totally vanilla, standards-based. Expect further improvements in future releases. + ### `uib-html` improvements * The `uib-html` node now accepts a `msg.template` property which, if provided, MUST contain a valid HTML page template. diff --git a/docs/_404.md b/docs/.config/404.md similarity index 100% rename from docs/_404.md rename to docs/.config/404.md diff --git a/docs/_coverpage.md b/docs/.config/coverpage.md similarity index 100% rename from docs/_coverpage.md rename to docs/.config/coverpage.md diff --git a/docs/-sidebar.md b/docs/.config/sidebar.md similarity index 99% rename from docs/-sidebar.md rename to docs/.config/sidebar.md index 39acc38b..e0252221 100644 --- a/docs/-sidebar.md +++ b/docs/.config/sidebar.md @@ -1,14 +1,14 @@ * [Home](/) * Using uibuilder * [A first-timers walkthough](walkthrough1.md "Let's get started!") - * [Did you know?](did-you-know.md "Things you might not know about UIBUILDER") - * [Creating data-driven web apps](web-app-workflow.md "Different styles and workflows you can use") + * [Browser auto-refresh](browser-refresh.md "Automatically reload your page after a change") * [Configuring uibuilder](uib-configuration.md "Configure the UIBUILDER platform. Affects all uibuilder nodes") - * [Standard messages](pre-defined-msgs.md "Catalogue of messages and properties") + * [Creating data-driven web apps](web-app-workflow.md "Different styles and workflows you can use") * [Creating Templates](creating-templates "Pre-defined and reusable front-end code, dependencies, and optional build steps") - * [Browser auto-refresh](browser-refresh.md "Automatically reload your page after a change") - * [Zero-code UI creation](using/zero-code-ui.md "Dynamically creating web UI's") + * [Did you know?](did-you-know.md "Things you might not know about UIBUILDER") + * [Standard messages](pre-defined-msgs.md "Catalogue of messages and properties") * [Why uibuilder?](using/why-uibuilder.md "Why would I want to use UIBUILDER?") + * [Zero-code UI creation](using/zero-code-ui.md "Dynamically creating web UI's") * [The nodes](nodes/README.md) * [`uib-cache`](nodes/uib-cache.md "Cache data so that (re)loaded pages get the latest") * [`uib-element`](nodes/uib-element.md "no-code creation of page elements") @@ -19,51 +19,51 @@ * [`uib-update`](nodes/uib-update.md "no-code update of any existing HTML page element") * [`uibuilder`](nodes/uibuilder.md "The main node") * The front-end client - * [Introduction](client-docs/readme.md) - * [Features](client-docs/features.md) * [Controlling from Node-RED](client-docs/control-from-node-red.md) + * [Custom Components](client-docs/custom-components.md "The built-in uib-var component, using external components") + * [Custom Events](client-docs/custom-events.md) * [Dynamic, config-driven UI's](client-docs/config-driven-ui.md) + * [Features](client-docs/features.md) * [Functions](client-docs/functions.md) - * [Variables](client-docs/variables.md) - * [Custom Components](client-docs/custom-components.md "The built-in uib-var component, using external components") + * [Introduction](client-docs/readme.md) * [Routing Library](client-docs/fe-router.md "A full-featured front-end router for Single Page Apps and other use") - * [Custom Events](client-docs/custom-events.md) - * [uib-brand Style Sheet](client-docs/uib-brand-css.md "How to use the UIBUILDER standard style sheet uib-brand.css") * [Troubleshooting](client-docs/troubleshooting.md) + * [uib-brand Style Sheet](client-docs/uib-brand-css.md "How to use the UIBUILDER standard style sheet uib-brand.css") + * [Variables](client-docs/variables.md) * [Old uibuilderfe client library](front-end-library.md) * Zero-code element types - * [Tables](elements/tables.md) * [Forms](elements/forms.md) - * [Lists](elements/lists.md) + * [Headings, text boxes, etc.](elements/other.md) * [HTML](elements/html.md) + * [Lists](elements/lists.md) * [Markdown](elements/Markdown.md) - * [Headings, text boxes, etc.](elements/other.md) + * [Tables](elements/tables.md) * UI frameworks & builds - * [VueJS complexities](vue-complexities.md) - * [VueJS components](vue-component-handling.md) - * [Svelte](svelte.md) * [Avoiding a build step](front-end-no-build.md) * [Optimise & transpile (build)](front-end-builds.md) * [Snowpack as build tool](front-end-build-snowpack.md) + * [Svelte](svelte.md) + * [VueJS complexities](vue-complexities.md) + * [VueJS components](vue-component-handling.md) * How to - * [Use Fn nodes to change msg._ui](how-to/function-node.md) - * [How & why to use the list node](how-to/list-node.md) - * [Use the cache node](how-to/cache-node.md) - * [CSS Selectors](how-to/css-selectors.md) * [Change the root folder (uibRoot)](how-to/changing-uibroot.md) * [Create instance-specific API's](how-to/instance-apis.md) + * [CSS Selectors](how-to/css-selectors.md) + * [How & why to use the list node](how-to/list-node.md) * [How & why to use the sender node](how-to/sender-node.md) * [How to use low-code in the browser](how-to/use-low-code-in-fe.md "Define and update elements in the browser using low-code") * [Other How-To's](how-to/README.md) + * [Use Fn nodes to change msg._ui](how-to/function-node.md) + * [Use the cache node](how-to/cache-node.md) * Security - * [Securing uib web apps](security/security.md "Overview of general web app security with some specifics for Node-RED and UIBUILDER") - * [Securing Data](security/securing-data.md "How to use flows and uibiulder middleware to secure your data") * [Securing apps using NGINX](security/uib-security-nginx.md "How to use NGINX as a reverse proxy with TLS and identity authentication") + * [Securing Data](security/securing-data.md "How to use flows and uibiulder middleware to secure your data") + * [Securing uib web apps](security/security.md "Overview of general web app security with some specifics for Node-RED and UIBUILDER") * [Developer documentation](dev/README.md) * [REST API's](apis/) * [Glossary of terms](glossary.md) * [Changelog 🔗](changelog) -* [Roadmap](roadmap) +* [Roadmap](roadmap/) * [Main readme 🔗](uibhome) * Archives * [v5 Changelog](archived/CHANGELOG-v5) diff --git a/docs/README.md b/docs/README.md index 1b25b39d..68a673db 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,9 +1,10 @@ --- title: UIBUILDER Documentation -description: > +description: | UIBUILDER provides a stand-alone web server that allows for interfacing with Node-RED, while giving you help and complete freedom to create custom web interfaces. created: 2019-06-16 16:16:00 lastUpdated: 2023-09-30 13:06:56 +updated: 2023-12-30 20:02:01 --- It includes many helper features that can reduce or eliminate the need to write code for building data-driven web applications and user interfaces for Node-RED. @@ -47,7 +48,7 @@ WIKI, code (PR's), documentation, and examples are all welcome contributions and ## Content Index -[index](-sidebar.md ':include') +[index](.config/sidebar.md ':include') ## Additional Links diff --git a/docs/UPDATES/2302131 README.md.md b/docs/UPDATES/2302131 README.md.md index 9f800b99..f4bfce82 100644 --- a/docs/UPDATES/2302131 README.md.md +++ b/docs/UPDATES/2302131 README.md.md @@ -1,9 +1,10 @@ --- title: uibuilder Documentation -description: > +description: | uibuilder provides a stand-alone web server that allows for interfacing with Node-RED, while giving you help and complete freedom to create custom web interfaces. created: 2019-06-16 16:16:00 lastUpdated: 2023-02-08 10:17:10 +updated: 2023-12-30 17:01:42 --- It includes many helper features that can reduce or eliminate the need to write code for building data-driven web applications and user interfaces for Node-RED. [ Here is a diagram(Link to diagram)]** that gives an overview of how the various uibuilder components work together. diff --git a/docs/UPDATES/2302141 walkthrough1.md b/docs/UPDATES/2302141 walkthrough1.md index d3268691..6bad5871 100644 --- a/docs/UPDATES/2302141 walkthrough1.md +++ b/docs/UPDATES/2302141 walkthrough1.md @@ -1,10 +1,10 @@ --- title: A first-timers walkthrough of using uibuilder -description: > - If you haven't used uibuilder before, it can be a little confusing as it brings together concepts from - several different worlds. This walkthrough takes you from nothing to a basic data-driven web page. +description: | + If you haven't used uibuilder before, it can be a little confusing as it brings together concepts from several different worlds. This walkthrough takes you from nothing to a basic data-driven web page. created: 2021-09-24 11:02:56 lastUpdated: 2023-02-12 02:25:49 +updated: 2023-12-30 17:01:42 --- Like uibuilder itself, this walkthrough may look complex. But you should bear in mind that if you follow the 7 (or is it 4?) steps in the [How to get started](#how-to-get-started-4-steps-to-a-data-driven-web-app) section, that is basically it. diff --git a/docs/UPDATES/2302151msg.md b/docs/UPDATES/2302151msg.md index 5077d35d..fc1e94e6 100644 --- a/docs/UPDATES/2302151msg.md +++ b/docs/UPDATES/2302151msg.md @@ -1,3 +1,7 @@ +--- +created: 2023-03-06 10:59:23 +updated: 2023-12-30 17:01:42 +--- Hi Julian, I have gone through Readme and Walkthrough1, the results are attached. diff --git a/docs/UPDATES/2302201 uibuilder.md b/docs/UPDATES/2302201 uibuilder.md index c2e50e9b..1f9e9ca6 100644 --- a/docs/UPDATES/2302201 uibuilder.md +++ b/docs/UPDATES/2302201 uibuilder.md @@ -1,9 +1,10 @@ --- title: The main uibuilder node -description: > - Usage and configuration. +description: | + Usage and configuration. created: 2023-02-05 16:31:39 lastUpdated: 2023-02-05 16:31:46 +updated: 2023-12-30 17:01:42 --- > [!note] diff --git a/docs/apis/readme.md b/docs/apis/readme.md index 1a13307b..cf559a9a 100644 --- a/docs/apis/readme.md +++ b/docs/apis/readme.md @@ -1,9 +1,10 @@ --- title: UIBUILDER REST API's -description: > +description: | UIBUILDER exposes a number of REST API's. This is an index of them. created: 2023-09-14 19:39:52 lastUpdated: 2023-09-16 12:36:36 +updated: 2023-12-30 17:01:41 --- Most of UIBUILDER's standard REST API's are common across all instances of `uibuilder` nodes added to your Node-RED flows. However, see below for the instance API's features. diff --git a/docs/archived/CHANGELOG-v1.md b/docs/archived/CHANGELOG-v1.md index 9b6c9085..a47688b8 100644 --- a/docs/archived/CHANGELOG-v1.md +++ b/docs/archived/CHANGELOG-v1.md @@ -1,3 +1,7 @@ +--- +created: 2022-04-02 19:09:31 +updated: 2023-12-30 17:01:41 +--- ## Changelog Archive for v1 Current major version changelog can be found in the root of this package: `../CHANGELOG.md`. diff --git a/docs/archived/CHANGELOG-v2.md b/docs/archived/CHANGELOG-v2.md index 90a60399..2c8b52f4 100644 --- a/docs/archived/CHANGELOG-v2.md +++ b/docs/archived/CHANGELOG-v2.md @@ -1,3 +1,7 @@ +--- +created: 2022-04-02 19:09:31 +updated: 2023-12-30 17:01:41 +--- ## Changelog Archive for v2 Current major version changelog can be found in the root of this package: `../CHANGELOG.md`. diff --git a/docs/archived/CHANGELOG-v3-v4.md b/docs/archived/CHANGELOG-v3-v4.md index ec5a2ff5..259f5e43 100644 --- a/docs/archived/CHANGELOG-v3-v4.md +++ b/docs/archived/CHANGELOG-v3-v4.md @@ -1,3 +1,7 @@ +--- +created: 2022-04-02 19:09:31 +updated: 2023-12-30 17:01:41 +--- # Changelog Archive for v3 and v4 Current major version changelog can be found in the root of this package: `../CHANGELOG.md`. diff --git a/docs/archived/CHANGELOG-v5.md b/docs/archived/CHANGELOG-v5.md index 73fb1399..87dc4586 100644 --- a/docs/archived/CHANGELOG-v5.md +++ b/docs/archived/CHANGELOG-v5.md @@ -1,5 +1,7 @@ --- typora-root-url: docs/images +created: 2023-03-06 10:59:23 +updated: 2023-12-30 17:01:41 --- # Changelog archive for uibuilder v5 diff --git a/docs/archived/README-v1.md b/docs/archived/README-v1.md index 0d24fd05..bae621ff 100644 --- a/docs/archived/README-v1.md +++ b/docs/archived/README-v1.md @@ -1,3 +1,7 @@ +--- +created: 2022-04-02 19:09:31 +updated: 2023-12-30 17:01:41 +--- [![NPM Version](https://img.shields.io/npm/v/node-red-contrib-uibuilder.svg)](https://www.npmjs.com/package/node-red-contrib-uibuilder) [![NPM Total Downloads](https://img.shields.io/npm/dt/node-red-contrib-uibuilder.svg)](https://www.npmjs.com/package/node-red-contrib-uibuilder) [![NPM Downloads per month](https://img.shields.io/npm/dm/node-red-contrib-uibuilder.svg)](https://www.npmjs.com/package/node-red-contrib-uibuilder) diff --git a/docs/archived/V2-PROGRESS.md b/docs/archived/V2-PROGRESS.md index 3c8befb7..f701c984 100644 --- a/docs/archived/V2-PROGRESS.md +++ b/docs/archived/V2-PROGRESS.md @@ -1,3 +1,7 @@ +--- +created: 2022-04-02 19:09:31 +updated: 2023-12-30 17:01:41 +--- This is the design note for part 2 of enabling source file editing from the Node-RED admin ui. The [main To Do list is now in the WIKI](https://github.com/TotallyInformation/node-red-contrib-uibuilder/wiki/To-Do). diff --git a/docs/archived/sec-process.md b/docs/archived/sec-process.md index 57bb986e..40769e78 100644 --- a/docs/archived/sec-process.md +++ b/docs/archived/sec-process.md @@ -1,3 +1,7 @@ +--- +created: 2022-04-02 19:09:31 +updated: 2023-12-30 17:01:41 +--- Changes diff --git a/docs/archived/security.md b/docs/archived/security.md index b176467c..7bd9a9b2 100644 --- a/docs/archived/security.md +++ b/docs/archived/security.md @@ -1,9 +1,10 @@ --- title: uibuilder Security Documentation -description: > - Some thoughts on how to correctly and safely secure a uibuilder app. +description: | + Some thoughts on how to correctly and safely secure a uibuilder app. created: 2020-01-05 20:45:00 lastUpdated: 2021-06-27 18:19:13 +updated: 2023-12-30 17:01:41 --- uibuilder provides its own security process based on simple standards. diff --git a/docs/archived/securityjs.md b/docs/archived/securityjs.md index 2990122d..7d2ee6bd 100644 --- a/docs/archived/securityjs.md +++ b/docs/archived/securityjs.md @@ -1,3 +1,7 @@ +--- +created: 2022-04-02 19:09:31 +updated: 2023-12-30 17:01:41 +--- # security.js Technical Documentation The `security.js` file is the custom part of uibuilder's security architecture. diff --git a/docs/archived/v2-breaking-changes.md b/docs/archived/v2-breaking-changes.md index 9bdf49ce..1fa64561 100644 --- a/docs/archived/v2-breaking-changes.md +++ b/docs/archived/v2-breaking-changes.md @@ -1,3 +1,7 @@ +--- +created: 2022-04-02 19:09:31 +updated: 2023-12-30 17:01:41 +--- This page aims to document all of the breaking and potentially breaking changes in v2.0.0 since v1.2.6. While this may seem like a lot of breaking changes. In reality it breaks down to just a few and you only need to do them on existing installations that you have altered from the defaults. diff --git a/docs/browser-refresh.md b/docs/browser-refresh.md index 1f3fc189..fc38bb32 100644 --- a/docs/browser-refresh.md +++ b/docs/browser-refresh.md @@ -1,9 +1,10 @@ --- title: Auto-refresh the browser when developing -description: > - Describes how to make your page refresh automatically when developing front-end code. +description: | + Describes how to make your page refresh automatically when developing front-end code. created: 2022-02-15 20:56:20 lastUpdated: 2023-09-30 13:03:51 +updated: 2023-12-30 17:01:41 --- ## Reload message diff --git a/docs/client-docs/config-driven-ui.md b/docs/client-docs/config-driven-ui.md index faba1d15..95adf97f 100644 --- a/docs/client-docs/config-driven-ui.md +++ b/docs/client-docs/config-driven-ui.md @@ -1,10 +1,10 @@ --- title: Dynamic, configuration-driven UI's (low-code) -description: > - This version of the uibuilder front-end library supports the dynamic manipulation of your web pages. This is achieved either by loading a JSON file describing the layout and/or by sending messages from Node-RED via a `uibuilder` node where the messages contain a `msg._ui` property. - This is known as "configuration-driven" design since you send the configuration information and not the actual HTML. It is considered a low-code approach. +description: | + This version of the uibuilder front-end library supports the dynamic manipulation of your web pages. This is achieved either by loading a JSON file describing the layout and/or by sending messages from Node-RED via a `uibuilder` node where the messages contain a `msg._ui` property. This is known as "configuration-driven" design since you send the configuration information and not the actual HTML. It is considered a low-code approach. created: 2022-06-11 14:15:26 lastUpdated: 2023-09-30 13:02:29 +updated: 2023-12-30 17:01:41 --- - [Restricting actions to specific pages, users, tabs](#restricting-actions-to-specific-pages-users-tabs) @@ -491,8 +491,9 @@ This is the method used by the `uib-update` node. Dump output from that node to // List of component instances to update on the page - results in 1 or more HTML custom elements being selected and updated "components": [ { - // Only 1 of these four properties will be used to search. - // In the order of preference id > selector > name > type + /** Only 1 of these four properties will be used to search. + * In the order of preference id > selector > name > type + */ // The most direct way to select a single element "id": "...", @@ -503,6 +504,10 @@ This is the method used by the `uib-update` node. Dump output from that node to // A generic CSS selector can be specified here as well. e.g. "div" or "p#classname", etc. "type": "...", + /** You can use as many or as few of the following as you like in an update. + * For example, only updating a single attribute. + */ + // Optional. Text or HTML to add to slot - if not present, the contents of msg.payload will be used. // This allows multi-components to have their own slot content. // However, the payload is not passed on to sub-components @@ -518,6 +523,23 @@ This is the method used by the `uib-update` node. Dump output from that node to // ... not recommended to include `onClick or similar event handlers, specify those in the events property below ... }, + // Optional. Update the elements classes - USE ONLY ONE STYLE (object or array) + "classes": { + // Optional. Add a set of classes - processed in order with remove + "add": [ + "myclass1", "myclass2", + ], + // Optional. Remove a set of classes - processed in order with add + "remove": [ + "myclass2", "myclass3", + ], + } + // OR - use an array to replace all existing classes + // a convenient alternative to setting a class attribute string + // "classes": [ + // "myclass1", "myclass3", + // ], + // Optional. properties to be added to/replaced on the element. Unlike attributes, these can contain any data. // Take care to avoid name clashes with internal properties or bad things are likely to happen! // Most useful when working with ECMA Components though will work with custom front-end code as well. @@ -557,9 +579,13 @@ Same as sending `msg._uib.reload`. But this method is preferred. Overlay a pop-over notification. -Old-style `msg._uib.componentRef = 'globalNotification'` also works. But this method is preferred. +Old-style `msg._uib.componentRef = 'globalNotification'` also works. But this method is preferred. Note that this is different to the `notification` command which shows an OS toast notification, this shows an on-page notification. Also note that you can use `uibuilder.showDialog(type, ui, msg)` in front-end code for the same effect. + +Defaults to auto-timeout after a 10 seconds. -Defaults to auto-timeout. +For accessibility, the wrapper element for all notifications is given `role="dialog"` and `aria-label="Toast message`. The wrapper element for each individual notification is given `role="alertdialog"` and `aria-modal="true"`. + +Note that the "alert" method (see next section) is similar but does not autohide and has an additional warning icon. ### HTML Tags @@ -569,16 +595,38 @@ A new `
` element is added to `toaster`. #### Schema -variant, title/topic, payload/content, autohide, noAutoHide/autohide, autoHideDelay/delay, appendToast, modal +```jsonc +{ + "_ui": { + // REQUIRED + "method": "notify", + + // Colour variant: error, warn, info, success, etc - can be ANY class name + "variant": "warn", + + // Overrides msg.topic which is used if this isn't specified + "title": "My Title", + // msg.payload is used as message content, this is appended + "content": "Some content to show", + // Defaults to true, set to false to require user to cancel + "autohide": true, + // Delay time in milliseconds for autohide, default is 10s + // If present, automatically turns on `autohide` + "autoHideDelay": 10000, + } +} +``` ## Method: alert -Overlay an alert notification +Overlay an alert notification. Alerts can be stacked. Click anywhere on-page to dismiss all alerts, on an individual alert to dismiss only it. Old-style `msg._uib.componentRef = 'globalAlert'` also works. But this method is preferred. Uses the same schema and styles as the `notify` method. Except that autohide is set to false, modal is set to true and the content is prefixed by an alert symbol. +For accessibility, the wrapper element for all notifications is given `role="dialog"` and `aria-label="Toast message`. The wrapper element for each individual notification is given `role="alertdialog"` and `aria-modal="true"`. + --- ## Manipulating `msg._ui` diff --git a/docs/client-docs/control-from-node-red.md b/docs/client-docs/control-from-node-red.md index d6612f51..12109e8b 100644 --- a/docs/client-docs/control-from-node-red.md +++ b/docs/client-docs/control-from-node-red.md @@ -1,21 +1,27 @@ --- title: Controlling UIBUILDER's client from Node-RED -description: > - How to send specially formatted messages from Node-RED to the uibuilder node that - get information from the client and control how it works. +description: | + How to send specially formatted messages from Node-RED to the uibuilder node that get information from the client and control how it works. created: 2023-02-23 11:59:44 lastUpdated: 2023-10-14 17:00:54 +updated: 2023-12-30 17:01:41 --- The UIBUILDER client library can be controlled in various ways from Node-RED to save you the bother of having to write front-end code. These ways are all summarised here. They all use a pre-formatted message sent to the appropriate `uibuilder` node in Node-RED. -> [!INFO] -> This feature was introduced in uibuilder v6.1 with only the get/set commands. Other commands are introduced in later versions. - Please load the "remote-commands" example from the library to test all of these out. +> [!NOTE] +> Most of these commands will return a message to Node-RED on execution. +> +> If you want to surpress that, you can use the `quiet` property set to `true`, e.g. +> +> ```json +> {"_uib": {"command": "scrollTo", "prop": "top", "quiet": true}} +> ``` + ### A summary of the commands available Possible `msg._uib.command` values. @@ -26,6 +32,8 @@ Possible `msg._uib.command` values. * `getWatchedVars` - gets the list of uibuilder client managed variables that are currently being watched for changes. * `htmlSend` - gets the current full HTML as text. * `include` - Include HTML fragment, img, video, text, json, form data, pdf or anything else from an external file or API. +* [`navigate`](#navigation-control) - Triggers a page change or a route change. +* [`scrollTo`](#scrolling) - Scroll visible page to an element based on a CSS Selector. * `set` - set a uibuilder client managed variable. * `showMsg` - Turn on/off the display of the latest msg from Node-RED. * `showStatus` - Turn on/off the display of the uibuilder client library settings. @@ -52,6 +60,14 @@ A message containing a `msg._ui` property will be processed internally by the li Please see the [Dynamic, data-driven HTML content](config-driven-ui.md) content for details. +### Scrolling + +The page can be scrolled dynamically by Node-RED using the `scrollTo` command. Send a message like `{"_uib": {"command": "scrollTo", "prop": "cssSelector"}}` Where `cssSelector` is a selector that will select a specific element on the page (e.g. `body` or `#myid` or `.myclass`). If found, the top of that element will be scrolled to the top of the browser window. + +`cssSelector` can also be `top`/`start` or `bottom`/`end` which will scroll to the top or bottom of the page. + +An optional 2nd object can be passed in the optional `value` property which gives more control. e.g. `{"_uib": {"command": "scrollTo", "prop": "#mydivid", "value": {"block": "bottom"}}}`. See [Client Functions (scrollTo) in the docs](client-docs/functions#scrollTo) for details. See the definition of the [`scrollIntoView`](https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollIntoView) DOM API for details of the options. + ## Navigation & routing ### `watchUrlHash` Watch for URL Hash changes @@ -73,7 +89,21 @@ Set `msg._ui` to: ### Navigation control -Currently, only a page reload control is available. Set `msg._ui` to `{"method": "reload"}`. +Trigger a page change with a message like: + +```json +{"_uib": {"command":"navigate","prop":"./page2.html"}} +``` + +Or, if using a front-end router such as the [`uibrouter` library](client-docs/fe-router): + +```json +{"_uib": {"command":"navigate","prop":"#newroute"}} +``` + +See [Client Functions (navigate)](client-docs/functions#navigate) for details. + +A page reload can also be done using low-code. Set `msg._ui` to `{"method": "reload"}`. ## Getting UI information diff --git a/docs/client-docs/custom-components.md b/docs/client-docs/custom-components.md index 26dbb462..6559e75a 100644 --- a/docs/client-docs/custom-components.md +++ b/docs/client-docs/custom-components.md @@ -1,9 +1,10 @@ --- title: Custom web components -description: > - Web components built into the UIBUILDER client and information about external web components. +description: | + Web components built into the UIBUILDER client and information about external web components. created: 2023-10-08 13:44:56 -lastUpdated: 2023-10-08 14:59:10 +lastUpdated: 2023-12-29 17:25:31 +updated: 2023-12-30 17:01:41 --- UIBUILDER can work with front-end frameworks such as REACT, VueJS, etc. However, it does not need them. But one thing that these frameworks often have are collections of components that you can add to your HTML. Each component will produce something useful in your web page such as an information card, tabbed interface, navigation menu, etc. @@ -19,28 +20,106 @@ However, some components may also be built so that they can be loaded as a linke > [!NOTE] > UIBUILDER's no-code `uib-element` node currently sends out low-code JSON data that describes each element. While this is reasonably efficient since no actual HTML/JavaScript code is sent, it could be even more efficient by having a corresponding web component for each element. This is something that is likely to happen in a future release. -## Built-in components +## Built-in components: `uib-var` - include easily updated output in the page :id=uib-var -### uib-var - include a managed variable in the page +This component provides another way to make it easy to include dynamic data in your web UI and to update it. It is roughly equivalent to the "mustache" style brackets found in many front-end frameworks ({{myvariable}}). However, unlike those, it is 100% standard HTML. The component reference is replaced in the web page by a uibuilder managed variable value, msg topic payload, or the returned value of a filter function - depending on the attributes provided. -A built-in web component ``, used in your HTML as ``. +Included in your page using the ``, see the examples below on how to include this in your HTML. You can also use the no-code `uib-tag` node to add it to your HTML. + +There is no need to separately load the component, that is done automatically by the uibuilder client library. + + +### Attributes + +These attributes can be added to the `` tag. Noting that attributes must always have _string_ values, e.g. `topic="my/topic/#1"`. + +#### `topic` :id=topic + +Adds a background "listener" for messages from Node-RED via UIBUILDER that have the `topic` property matching this attribute. For example, the HTML `` will be automatically updated to show `42` when the corresponding uibuilder node is sent a message containing `{topic: 'my/topic/#1', payload: 42}`. + +This is the easiest way to use the `uib-var` component with UIBUILDER. + +This approach is especially useful to be able to display MQTT topic values in your UI + +> Cannot be used in conjunction with the `variable` attribute. + +#### `variable` :id=variable Displays the *value* of the given variable name in your web page and *dynamically updates* as long as the variable is changed using `uibuilder.set()`; or from Node-RED using the appropriate uib set command, e.g. `msg = {"command":"set","prop":"myVar","value":"42"}`. By default, the tag inserts the variable value inline with other text. Class and Style attributes can be added as for any other HTML. -Other attributes are available on the component tag: +> Cannot be used in conjunction with the `topic` attribute. -- `undefined`: If present or set to `on`, or `true`, the component will show even if the variable is undefined. +#### `filter` :id=filter + +Takes a string representation of a function to run before display. It can be used on its own or in conjunction with either the `variable` or `topic` attributes. + +When used with the `variable` or `topic` attributes, the function will be passed the corresponding value as its first parameter. Any additional parameters provided on this attribute will be merged _after_ the value. + +The function must be accessible from the global `window` environment and return valid text or HTML which will be used as the displayed content. + +The attribute string may include simple arguments only (e.g. strings, booleans and numbers - `filter="myfunc('text', 42, true)"`). + +Dotted notation for the function name is allowed (e.g. `uibuilder.get('version')`) but the array style (e.g. `uibuilder['get']('version')`) is not permitted. + +If the function name is not found in the global window context, the `uibuilder` context is searched so `get('version')` will call `uibuilder.get('version')` so long as `get` is not defined as `window.get` which would take preference. + +Generally, it will be best to define your own function. Further standard filters may be added in future releases of UIBUILDER. Until then, a list of standard filters included in the uibuilder is provided [lower-down](#useful-filter-functions). + +> [!NOTE] +> If having problems getting your filter functions recognised, try adding them earlier in the HTML, for example, defining the `lang` filter: +> ```html + + + + + +> ``` + +#### `undefined` :id=undefined + +If present or set to `on`, or `true`, the component will show even if the variable is undefined. - If not present or set to anything else, an undefined variable will show the _slot content_ (anything put between the open and close tag). This lets you have an initial value showing that is replaced as soon as the variable is actually set. +If not present or set to anything else, an undefined variable will show the _slot content_ (anything put between the open and close tag). This lets you have an initial value showing that is replaced as soon as the variable is actually set. + +#### `report` :id=report + +If present or set to `on`, or `true`, the component will return a standard message back to Node-RED when the variable changes value. + +#### `type` :id=type + +Must be one of 'plain', 'html', 'markdown', or 'object'. `plain` and `html` simply insert the variable as-is. `markdown` allows the insertion of Markdown as long as the Markdown-IT library is loaded (it will also sanitise the resulting HTML if the DOMPurify library is loaded). `object` does some basic formatting to allow object or array variables to be more easily read. -- `report`: If present or set to `on`, or `true`, the component will return a standard message back to Node-RED when the variable changes value. -- `type`: Must be one of 'plain', 'html', 'markdown', or 'object'. `plain` and `html` simply insert the variable as-is. `markdown` allows the insertion of Markdown as long as the Markdown-IT library is loaded (it will also sanitise the resulting HTML if the DOMPurify library is loaded). `object` does some basic formatting to allow object or array variables to be more easily read. This works with Markdown via the `uib-element` node as well and even works if DOMPurify is loaded as overrides to its filters are provided. -There is no need to load the component, that is done automatically in the uibuilder client library. -Examples: +### Styling + +The component tries to load `./index.css` as a stylesheet so that your own styling can be used in any output. + +Simply ensure that the file is served from the same URL location as your main page. + +This is the standard method for UIBUILDER instances but this feature is not dependent on UIBUILDER. + +### Useful filter functions + +#### `uibuilder.formatNumber` :id=format-number + +Formats a number to a given locale and optionally, a set number of decimal places. + +Example, formatting to 2dp using the Japanese locale: ``. + +Note that the value is passed automatically so the first provided argument is the number of decimal places. + +Parameters: `formatNumber(value, decimalPlaces, intl, opts)`. Where `opts` is an INTL formatting object. + +See details in the [client functions doc](client-docs/functions#formatNumber). + +### Examples ```html

@@ -65,10 +144,20 @@ The version of the uibuilder client library currently loaded is ``. ``` +#### Adding a tag to your page using no-code from Node-RED + +Use a `uib-tag` node: + +![example uib-tag node](image.png) + ## External components Web components can be challenging to build but are often fairly simple. There are plenty of web resources to get you started with development of them. However, there are also a lot of existing components that you can easily make use of with Node-RED and UIBUILDER. +Such components can be manually added to your `index.html` file OR they can be dynamically added using UIBUILDER's no-code `uib-tag` node. + +Some potentially useful components are shown below. + ### Totally Information experimental web components Totally Information has a (so far experimental) set of web components that work with or without UIBUILDER though they will generally have extra features when used with. See the [TotallyInformation/web-components GitHub repo](https://github.com/TotallyInformation/web-components) for details. diff --git a/docs/client-docs/custom-events.md b/docs/client-docs/custom-events.md index 23ebea9a..f77efa89 100644 --- a/docs/client-docs/custom-events.md +++ b/docs/client-docs/custom-events.md @@ -1,9 +1,10 @@ --- title: Custom document events used in the modern client -description: > - Details about the custom `document` events used in the uibuilder modern front-end client library. +description: | + Details about the custom `document` events used in the uibuilder modern front-end client library. created: 2023-01-28 15:56:57 lastUpdated: 2023-09-30 13:02:53 +updated: 2023-12-30 17:01:41 --- diff --git a/docs/client-docs/fe-router.md b/docs/client-docs/fe-router.md index cc9143c6..fbc3fcf0 100644 --- a/docs/client-docs/fe-router.md +++ b/docs/client-docs/fe-router.md @@ -1,9 +1,10 @@ --- title: UIBUILDER Front-End Router Library -description: > +description: | Details on the configuration and use of UIBUILDER's front-end router. created: 2022-02-01 11:15:27 -lastUpdated: 2023-11-19 17:21:15 +lastUpdated: 2023-12-29 17:25:14 +updated: 2023-12-30 17:01:41 --- The `uibrouter` front-end library defines a `UibRouter` class. This allows both internal and external content to be dynamically shown, allowing the creation of "Single-Page Apps" (SPA's) or simply keeping parts of the UI hidden from the users until they need them. @@ -27,6 +28,20 @@ The easiest way to include the router is to use the `../uibuilder/utils/uibroute ## Triggering a route change +### From Node-RED + +Route changes can be triggered from Node-RED flows by sending a message to the uibuilder node with msg content such as: + +```json +{"_uib": {"command":"navigate","prop":"#newroute"}} +``` + +See [Client Functions (navigate)](client-docs/functions#navigate) for details. + +Don't forget that there is also a `watchUrlHash` function, also callable as a command. That will send a message to Node-RED on every route change. + +### In the browser + There are three ways to trigger a route change: * Manually changing the URL, adding `#routeid` @@ -75,22 +90,81 @@ Which mode you use will be dependent on what you want to achieve. TBC - See the example below for configuration settings. +### Configuration Schema + +```js +/** Type definitions + * + * routeDefinition - configuration for each route + * @typedef {object} routeDefinition Single route configuration + * @property {string} id REQUIRED. Route ID + * @property {string} src REQUIRED. CSS Selector for template tag routes, url for external routes + * @property {"url"|undefined} [type] OPTIONAL. "url" for external routes + * @property {string} [title] OPTIONAL. Text to use as a short title for the route + * @property {string} [description] OPTIONAL. Text to use as a long description for the route + * + * UibRouterConfig - main configuration + * @typedef {object} UibRouterConfig Configuration for the UiBRouter class instances + * @property {routeDefinition[]} routes REQUIRED. Array of route definitions + * @property {string} [defaultRoute] OPTIONAL. If set to a route id, that route will be automatically shown on load + * @property {string} [routeContainer] OPTIONAL. CSS Selector for an HTML Element containing routes + * @property {boolean} [hide] OPTIONAL. If TRUE, routes will be hidden/shown on change instead of removed/added + * @property {boolean} [unload] OPTIONAL. If TRUE, route templates will be unloaded from DOM after access. Only useful with the `hide` option + * + */ +``` + ## Defining route templates Internal route templates are simply valid HTML wrapped in a `