From 36b104d7d6b41e80630188a6e7ed22eba77f67a6 Mon Sep 17 00:00:00 2001
From: bartbutenaers <bart.butenaers@gmail.com>
Date: Sun, 17 Nov 2024 00:22:34 +0100
Subject: [PATCH 1/6] dynamic ui-template

---
 ui/src/widgets/ui-template/UITemplate.vue | 376 ++++++++++++----------
 1 file changed, 200 insertions(+), 176 deletions(-)

diff --git a/ui/src/widgets/ui-template/UITemplate.vue b/ui/src/widgets/ui-template/UITemplate.vue
index 4b479fdb4..ffb68147c 100644
--- a/ui/src/widgets/ui-template/UITemplate.vue
+++ b/ui/src/widgets/ui-template/UITemplate.vue
@@ -11,189 +11,25 @@ export default {
     inject: ['$socket', '$dataTracker'],
     props: {
         id: { type: String, required: true },
-        props: { type: Object, default: () => ({}) }
+        props: { type: Object, default: () => ({}) },
+        state: { type: Object, default: () => ({}) }
     },
-    setup (props) {
-        const parser = new DOMParser()
-        const htmlDoc = parser.parseFromString(props.props.format, 'text/html')
-
-        // check whether we have a fully defined Vue component, or _just_ HTML
-        const templates = htmlDoc.getElementsByTagName('template')
-        const template = templates.length ? templates[0] : props.props.format
-
-        let head
-
-        /* Check for any CSS <style> tags */
-        const styles = htmlDoc.getElementsByTagName('style')
-
-        if (styles.length) {
-            // parse the CSS and add to the head
-            for (let s = 0; s < styles.length; s++) {
-                const style = styles[s]
-                head = head || []
-                head.push({
-                    type: 'style',
-                    data: {
-                        innerHTML: style.innerHTML
-                    }
-                })
-            }
-        }
-
-        /* Check for any <script> elements */
-        const scripts = htmlDoc.getElementsByTagName('script')
-        let component
-
-        if (scripts.length) {
-            // parse the Vue component, which is mostly stringified
-            for (let s = 0; s < scripts.length; s++) {
-                const script = scripts[s]
-                // check we're loading of a script file or if it's raw JS/Vue, or a
-                if (script.getAttribute('src')) {
-                    head = head || []
-                    head.push({
-                        type: 'script',
-                        data: {
-                            src: script.getAttribute('src'),
-                            defer: script.getAttribute('defer'),
-                            async: script.getAttribute('async')
-                        }
-                    })
-                } else {
-                    const parsed = VueParser.parse(script.innerHTML)
-                    if (parsed.js) {
-                        component = {
-                            ...component,
-                            js: parsed.js
-                        }
-                    } else {
-                        component = {
-                            ...component,
-                            ...parsed
-                        }
-                    }
-                }
-            }
-        }
-
-        // here we inject the UI Template Vue Template code into our own, in order to extend base functionality
-        return () => h({
-            props: ['id', 'props'],
-            inject: ['$socket', '$dataTracker'],
-            errorCaptured: (err, vm, info) => {
-                console.error('errorCaptured', err, vm, info)
-                return false
-            },
-            head () {
-                let _props = this.props || props
-                if (_props.props) { _props = _props.props }
-
-                const setup = {}
-
-                if (!_props || ['local', 'widget:page', 'widget:ui'].includes(_props.templateScope)) {
-                    if (!head) {
-                        return {}
-                    } else if (Array.isArray(head) && head.length > 0) {
-                        // loop through the head items and add them to the setup config
-                        head.forEach((item) => {
-                            // check that we have a data object defining the properties of the tag
-                            if (item.data) {
-                                // types supported by @unhead/vue:
-                                //      script, link, meta, style
-                                setup[item.type] = setup[item.type] || []
-
-                                // add meta data for debugging and auditing
-                                item.data['data-template-name'] = _props.name
-                                item.data['data-template-scope'] = _props.templateScope
-                                item.data['data-template-id'] = this.id
-                                if (_props.innerHTML) {
-                                    item.data.innerHTML = _props.innerHTML
-                                }
-
-                                setup[item.type].push(item.data)
-                            }
-                        })
-                    }
-                }
-                if (_props.format && (_props.templateScope === 'page:style' || _props.templateScope === 'site:style')) {
-                    setup.style = [
-                        {
-                            innerHTML: _props.format,
-                            'data-template-name': _props.name,
-                            'data-template-scope': _props.templateScope,
-                            'data-template-id': this.id
-                        }
-                    ]
-                }
-                return setup
-            },
-            template: ['local', 'widget:page', 'widget:ui'].includes(props.props.templateScope) ? template : undefined,
-            watch: {
-                ...component?.watch
-            },
-            computed: {
-                ...mapState('data', ['messages']),
-                ...mapState('setup', ['setup']),
-                msg () {
-                    return this.messages[this.id] || {}
-                },
-                value: {
-                    get () {
-                        return this.messages[this.id]?.payload
-                    },
-                    set (val) {
-                        if (this.value === val) {
-                            return // no change
-                        }
-                        const msg = this.messages[this.id] || {}
-                        msg.payload = val
-                        this.messages[this.id] = msg
-                    }
-                },
-                ...component?.computed
-            },
-            methods: {
-                send (msg) {
-                    if (msg) {
-                        this.$parent.send(this, msg)
-                    }
-                },
-                submit ($evt) {
-                    this.$parent.submit(this, $evt)
-                },
-                ...component?.methods
-            },
-            created () {
-                this.$dataTracker(props.id)
-            },
-            mounted () {
-                if (component?.js) {
-                    // run any generic JS code user has defined outside of a VueJS component
-                    // eslint-disable-next-line no-eval
-                    eval(component.js)
-                }
-                if (component?.mounted) {
-                    component.mounted.call(this)
-                }
-            },
-            unmounted () {
-                // eslint-disable-next-line no-eval
-                this.$socket.off(`msg-input:${this.id}`)
-                if (component?.unmounted) {
-                    component.unmounted.call(this)
-                }
-            },
-            data: component ? component.data : null
-        }, {
-            id: props.id,
-            props: props.props
-        })
+    created () {
+        this.$dataTracker(this.id, null, null, this.onDynamicProperties)
     },
     errorCaptured: (err, vm, info) => {
         console.error('errorCaptured', err, vm, info)
         return false
     },
     methods: {
+        onDynamicProperties (msg) {
+            const updates = msg.ui_update
+            if (!updates) {
+                return
+            }
+            this.updateDynamicProperty('format', updates.format)
+            this.$forceUpdate()
+        },
         send (component, msg) {
             if (typeof (msg) !== 'object') {
                 msg = { payload: msg }
@@ -216,7 +52,195 @@ export default {
             msg._dashboard.sourceId = component.id
             msg._dashboard.templateId = this.id
             this.$socket.emit('widget-action', this.id, msg) // TODO: should we have a widget-send emitter to differentiate from action?
+        },
+        parseCustomTemplate () {
+            const parser = new DOMParser()
+            const htmlDoc = parser.parseFromString(this.getProperty('format'), 'text/html')
+
+            // Check whether the user has specified a fully defined Vue component, or _just_ raw HTML
+            const templates = htmlDoc.getElementsByTagName('template')
+            const template = templates.length ? templates[0] : this.getProperty('format')
+
+            const head = []
+
+            // Check whether the user has specifed any CSS <style> tags
+            const styles = htmlDoc.getElementsByTagName('style')
+
+            if (styles.length) {
+                // parse the CSS and add to the head
+                for (let s = 0; s < styles.length; s++) {
+                    const style = styles[s]
+                    head.push({
+                        type: 'style',
+                        data: {
+                            innerHTML: style.innerHTML
+                        }
+                    })
+                }
+            }
+
+            let component = {}
+
+            // Check whether the user has specifed any javascript <script> tags
+            const scripts = htmlDoc.getElementsByTagName('script')
+
+            if (scripts.length) {
+                // parse the Vue component, which is mostly stringified
+                for (let s = 0; s < scripts.length; s++) {
+                    const script = scripts[s]
+                    if (script.getAttribute('src')) {
+                        head.push({
+                            type: 'script',
+                            data: {
+                                src: script.getAttribute('src'),
+                                defer: script.getAttribute('defer'),
+                                async: script.getAttribute('async')
+                            }
+                        })
+                    } else {
+                        const parsed = VueParser.parse(script.innerHTML)
+                        if (parsed.js) {
+                            component = {
+                                ...component,
+                                js: parsed.js
+                            }
+                        } else {
+                            component = {
+                                ...component,
+                                ...parsed
+                            }
+                        }
+                    }
+                }
+            }
+
+            return { head, component, template }
+        },
+        createVNode (head, component, template, parent) {
+            // Return a (VueJs VNode directly to create a virtual DOM.
+            // A VueJs template will created here, even when the user specified raw HTML.
+            return h({
+                props: ['id', 'props'],
+                inject: ['$socket', '$dataTracker'],
+                errorCaptured: (err, vm, info) => {
+                    console.error('errorCaptured', err, vm, info)
+                    return false
+                },
+                head () {
+                    let _props = this.props || parent.props
+                    if (_props.props) { _props = _props.props }
+
+                    const setup = {}
+
+                    if (!_props || ['local', 'widget:page', 'widget:ui'].includes(_props.templateScope)) {
+                        if (!head) {
+                            return {}
+                        } else if (Array.isArray(head) && head.length > 0) {
+                            // loop through the head items and add them to the setup config
+                            head.forEach((item) => {
+                                // check that we have a data object defining the properties of the tag
+                                if (item.data) {
+                                    // types supported by @unhead/vue:
+                                    //      script, link, meta, style
+                                    setup[item.type] = setup[item.type] || []
+
+                                    // add meta data for debugging and auditing
+                                    item.data['data-template-name'] = _props.name
+                                    item.data['data-template-scope'] = _props.templateScope
+                                    item.data['data-template-id'] = this.id
+                                    if (_props.innerHTML) {
+                                        item.data.innerHTML = _props.innerHTML
+                                    }
+                                    setup[item.type].push(item.data)
+                                }
+                            })
+                        }
+                    }
+                    if (_props.format && (_props.templateScope === 'page:style' || _props.templateScope === 'site:style')) {
+                        setup.style = [
+                            {
+                                innerHTML: _props.format,
+                                'data-template-name': _props.name,
+                                'data-template-scope': _props.templateScope,
+                                'data-template-id': this.id
+                            }
+                        ]
+                    }
+                    return setup
+                },
+                template: ['local', 'widget:page', 'widget:ui'].includes(parent.props.templateScope) ? template : undefined,
+                watch: {
+                    ...component?.watch
+                },
+                computed: {
+                    ...mapState('data', ['messages']),
+                    ...mapState('setup', ['setup']),
+                    msg () {
+                        return this.messages[this.id] || {}
+                    },
+                    value: {
+                        get () {
+                            return this.messages[this.id]?.payload
+                        },
+                        set (val) {
+                            if (this.value === val) {
+                                return // no change
+                            }
+                            const msg = this.messages[this.id] || {}
+                            msg.payload = val
+                            this.messages[this.id] = msg
+                        }
+                    },
+                    ...component?.computed
+                },
+                methods: {
+                    send (msg) {
+                        if (msg) {
+                            this.$parent.send(this, msg)
+                        }
+                    },
+                    submit ($evt) {
+                        this.$parent.submit(this, $evt)
+                    },
+                    ...component?.methods
+                },
+                created () {
+                    this.$dataTracker(parent.id, null, null, parent.onDynamicProperties)
+                },
+                mounted () {
+                    if (component?.js) {
+                        // run any generic JS code user has defined outside of a VueJS component
+                        // eslint-disable-next-line no-eval
+                        eval(component.js)
+                    }
+                    if (component?.mounted) {
+                        component.mounted.call(this)
+                    }
+                },
+                unmounted () {
+                    // eslint-disable-next-line no-eval
+                    this.$socket.off(`msg-input:${this.id}`)
+                    if (component?.unmounted) {
+                        component.unmounted.call(this)
+                    }
+                },
+                data: component ? component.data : null
+            }, {
+                id: parent.id,
+                props: parent.props
+            })
         }
+    },
+    render () {
+        // Call the method to parse the input (template or raw HTML) specified by the user
+        const { head, component, template } = this.parseCustomTemplate()
+
+        // Create a virtual node which can be loaded by VueJs in the virtual DOM.
+        // VueJs will detect automatically all changes to the previous virtual DOM,
+        // and only do the necessary updates (avoiding a slow full refresh that way).
+        // The custom Vue template will be injected in the core ui-template, in
+        // in order to extend base functionality.
+        return this.createVNode(head, component, template, this)
     }
 }
 </script>

From e5ab020bfcc532d65623eb86a2134617785766e9 Mon Sep 17 00:00:00 2001
From: bartbutenaers <bart.butenaers@gmail.com>
Date: Sun, 17 Nov 2024 00:23:22 +0100
Subject: [PATCH 2/6] dynamic ui template

---
 nodes/widgets/ui_template.js | 43 +++++++++++++++++++++++++-----------
 1 file changed, 30 insertions(+), 13 deletions(-)

diff --git a/nodes/widgets/ui_template.js b/nodes/widgets/ui_template.js
index 3090fbdaf..e8dc0df69 100644
--- a/nodes/widgets/ui_template.js
+++ b/nodes/widgets/ui_template.js
@@ -1,3 +1,5 @@
+const statestore = require('../store/state.js')
+
 module.exports = function (RED) {
     function TemplateNode (config) {
         const node = this
@@ -5,10 +7,6 @@ module.exports = function (RED) {
         // create node in Node-RED
         RED.nodes.createNode(this, config)
 
-        const evts = {
-            onAction: true // TODO: think we need an onSend event for template nodes that matches up with a `widget-send` message
-        }
-
         if (config.templateScope === 'local') {
             config.page = ''
             config.ui = ''
@@ -31,18 +29,37 @@ module.exports = function (RED) {
             config.passthru = true
         }
 
-        // which group are we rendering this widget
+        // determine which group/page/ui are we rendering this widget
+        let group, page, ui
         if (config.group) {
-            const group = RED.nodes.getNode(config.group)
-            // inform the dashboard UI that we are adding this node
-            group.register(node, config, evts)
+            group = RED.nodes.getNode(config.group)
         } else if (config.page) {
-            const page = RED.nodes.getNode(config.page)
-            // inform the dashboard UI that we are adding this node
-            page.register(null, node, config, evts)
+            page = RED.nodes.getNode(config.page)
         } else if (config.ui) {
-            const ui = RED.nodes.getNode(config.ui)
-            // inform the dashboard UI that we are adding this node
+            ui = RED.nodes.getNode(config.ui)
+        }
+
+        const evts = {
+            onAction: true, // TODO: think we need an onSend event for template nodes that matches up with a `widget-send` message
+            beforeSend: function (msg) {
+                if (msg.ui_update) {
+                    const update = msg.ui_update
+                    if (typeof update.format !== 'undefined') {
+                        // dynamically set "format" property
+                        const parent = group || page || ui
+                        statestore.set(parent.getBase(), node, msg, 'format', update.format)
+                    }
+                }
+                return msg
+            }
+        }
+
+        // inform the dashboard group/page/ui that we are adding this node
+        if (group) {
+            group.register(node, config, evts)
+        } else if (page) {
+            page.register(null, node, config, evts)
+        } else if (ui) {
             ui.register(null, null, node, config, evts)
         }
     }

From 998851991736a54bcac3bb5e157b8cf90ea7e64a Mon Sep 17 00:00:00 2001
From: bartbutenaers <bart.butenaers@gmail.com>
Date: Sun, 17 Nov 2024 00:24:05 +0100
Subject: [PATCH 3/6] dynamic ui-template

---
 nodes/widgets/locales/en-US/ui_template.html | 508 +++++++++++++++----
 1 file changed, 421 insertions(+), 87 deletions(-)

diff --git a/nodes/widgets/locales/en-US/ui_template.html b/nodes/widgets/locales/en-US/ui_template.html
index 713e853ad..ac7c06f66 100644
--- a/nodes/widgets/locales/en-US/ui_template.html
+++ b/nodes/widgets/locales/en-US/ui_template.html
@@ -1,153 +1,487 @@
+---
+description: Harness the power of ui-template in Node-RED Dashboard 2.0 to design custom widgets and unique dashboard layouts.
+props:
+    Group: Defines which group of the UI Dashboard this widget will render in.
+    Scope: "Template nodes can be used  for 3 purposes/scopes: <ul><li><b>Widget (Group-Scoped):</b>A standard HTML/Vue widget rendered in a group in the Dashboard.</li><li><b>Widget (Page-Scoped):</b>A HTML/Vue widget that will render on a page, outside of any existing groups. Note that these widgets will render after any Groups. An example use case for this would be if you wanted to have a fixed footer on a given page.</li><li><b>Widget (UI-Scoped):</b>A HTML/Vue widget rendered on every page of the Dashboard. Most commonly used in conjunction with <a href=\"#teleports\">Teleports</a></li><li><b>CSS (All Pages):</b>Define custom CSS classes/styling that applies to the entire Dashboard.</li><li><b>CSS (Single Page):</b>Define custom CSS classes/styling that applies just a single page of your Dashboard.</li></ul>"
+    Class: Appends CSS classes to the widget
+    Template: The content of the widget or CSS &lt;style&gt;. If using this for CSS, you do not need to include any &lt;style&gt; tags, as these will be automatically added.
+dynamic:
+    Format:
+        payload: msg.ui_update.format
+        structure: ["String"]
+---
 
-<script type="text/markdown" data-help-name="ui-template">
-(see [full docs](https://dashboard.flowfuse.com/nodes/widgets/ui-template.html))
+<script setup>
+    import AddedIn from '../../components/AddedIn.vue';
+    import TryDemo from "./../../components/TryDemo.vue";
+</script>
 
-The content of `ui-template` is controlled by the "Type" property.
 
-Provides a means to render custom content or a set of node-styles depending on scope.
-- **Widget:** A Vue Component (including any <a href="https://vuetifyjs.com/en/components/all/" target="blank">
-  Vuetify component</a>) that is rendered in the Dashboard.
-- **CSS (All Pages):** Define custom CSS classes/styling that applies to the entire Dashboard.
-- **CSS (Single Page):** Define custom CSS classes/styling that applies just a single page of your Dashboard
+<TryDemo href="template">
 
-### Type: Widget
-When the scope is set to **Widget**, the template will be rendered in the Dashboard as HTML.
+# Template `ui-template` <AddedIn version="0.10.0"/>
 
-You can render dynamic content using any VueJS data-binding expressions, (e.g. `v-if`, `v-for`, `:class`)
-and access incoming data to the node via the `msg` object.
+</TryDemo>
+ 
+Provide custom JS and HTML (including any [Vuetify components](https://vuetifyjs.com/en/components/all/)) to render in the Dashboard.
 
-#### Working with Variables
+- Define your own Vue components
+- Load external JS dependencies
+- Write raw JavaScript
+- Use Vuetify components
+
+## Properties
+
+<PropsTable/>
+
+## Dynamic Properties
+
+<DynamicPropsTable/>
+
+## Writing Custom Widgets
+
+UI Template will parse different tags and render them into Dashboard. The available tags are:
+
+- `<template>` - Any HTML code in here will be rendered into the Dashboard.
+- `<script>` - Any JavaScript code in here will be executed when the widget is loaded. You can also [define a full VueJS component](#building-full-vue-components) here.
+- `<style>` - Any CSS code in here will be injected into the Dashboard.
+
+### Working with Variables
 
 Any variables that you want to render into your `<template />` are done so in one of two ways:
 
-- **Attribute Binding** - Use `:` to bind a variable to an attribute. Anything inside the double quotes `""` is treated as JavaScript, for example: 
+::: v-pre
+- **Attribute Binding** - Use `:` to bind a variable to an attribute. Anything inside the `""` here is treated as JavaScript, for example: 
 
 ```html
-&lt;p :class="msg.payload">Hello World&lt;/p>
+<p :class="msg.payload">Hello World</p>
 ````
 
 or, if you want to use `msg.payload` as part of the value, you can do this:
 
 ```html
-&lt;!-- Change color based on msg.payload. Expects payload to be either "error", "warning" or "info" -->
-&lt;p :class="'text-' + msg.payload">Hello World&lt;/p>
-&lt;!-- or with string literals: -->
-&lt;p :class="`text-${msg.payload}`">Hello World&lt;/p>
+<!-- Change color based on msg.payload. Expects payload to be either "error", "warning" or "info" -->`
+<p :class="'text-' + msg.payload">Hello World</p>
+<!-- or with string literals: -->
+<p :class="`text-${msg.payload}`">Hello World</p>
 ````
 
-or use `msg.payload` as a condition:
+or even use `msg.payload` as a condition:
 
 ```html
-&lt;!-- 
+<!-- 
   Change color based on the value of msg.payload: 
   * When msg.payload equals "error", set text to the predefined `text-error` color. 
   * Otherwise, set text to the predefined `text-info` color.
 -->
-&lt;p :class="msg.payload === 'error' ? 'text-error' : 'text-info'">Hello World&lt;/p>
+<p :class="msg.payload === 'error' ? 'text-error' : 'text-info'">Hello World</p>
 ````
 
-or even as a conditional block:
+- **Text Interpolation** - Use `{{ }}` to interpolate a variable into the text of an element. Anything inside the curly brackets is treated as JavaScript. For example:
 
 ```html
-&lt;!-- 
-  Show a message based on the value of msg.payload:
-  * When msg.payload equals "error", show the error message.
-  * When msg.payload equals "warning", show the warning message.
-  * Otherwise, show the info message.
--->
-&lt;div>
-  &lt;p v-if="msg.payload === 'error'">Error: Something went wrong!&lt;/p>
-  &lt;p v-else-if="msg.payload === 'warning'">Warning: Be careful!&lt;/p>
-  &lt;p v-else>Info: Everything is fine!&lt;/p>
-&lt;/div>
+<p>Hello {{ msg.payload }}</p>
 ```
 
-- **Text Interpolation** - Use `{{ }}` to interpolate a variable into the text of an element. Anything inside the curly brackets is treated as JavaScript. For example:
-
 ```html
-&lt;p>Hello {{ msg.payload }}&lt;/p>
+<p>Percentage {{ msg.payload * 100 }}%</p>
 ```
 
-```html
-&lt;p>Percentage {{ msg.payload * 100 }}%&lt;/p>
+### Built-in Variables
+
+You have access to a number of built-in variables in your `ui-template` node:
+
+- `id` - The ID of the `ui-template` node, assigned by Node-RED.
+- `msg` - The last message received by the `ui-template` node.
+- `$socket` - The socket.io connection that is used to communicate with the Node-RED backend.
+
+When accessing the `msg` variable inside a `<script />` tag, you need to prefix the variable name with `this.` (e.g. `this.msg.payload`) so that it knows you're accessing the component-bound `msg` variable.
+
+***Important Note:*** On first load, `msg.payload` may be `null` or `undefined`, and trying to access a nested property will throw an error. Using the **optional chaining** (?.) operator, e.g. `msg.payload?.nested?.property` will prevent these errors occurring.
+
+#### Accessing Node-RED Global/Flow Context
+
+The `flow`/`global` context stores are not available in the Dashboard UI, as such, the best practice here is to use a "Change" node prior to the `ui-template` node to assign a `msg.<property>` to the relevant value from the `flow.` or `global.` store:
+
+![Example of using a Change node to assign a value to `msg.payload`](/images/node-examples/change-flow-to-msg.png "Example of using a Change node to assign a value to `msg.payload`"){data-zoomable}
+_Example of using a Change node to assign a value to `msg.payload`._
+
+### Built-in Functions
+
+We also offer some helper functions for the Node-RED integration too:
+
+#### Sending Data
+
+- `this.send(msg)` - Send a message to the Node-RED flow. If a non-Object value is sent, then Dashboard will automatically wrap that into a `msg.payload` object.
+
+#### Receiving Data
+
+There are two ways of responding to messages received by your `ui-template` node:
+
+Option 1: 
+
+In VueJS, we can `watch` a variable for any changes, and react accordingly.
+
+As mentioned in the [Built-in Variables](#built-in-variables) section above, we have access to the `msg` variable in our `ui-template` node. We can watch this variable for any changes, and react accordingly:
+
+```js
+watch: {
+    msg: function () {
+        // do stuff with this.msg
+        // runs onLoad and onInput
+    }
+}
 ```
 
-#### Built In Functions
+It's worth noting though, that whilst this will update when new messages are received, it _also_ updates when a widget first loads, and the latest `msg` is loaded to the widget.
 
-The template comes with two built-in functions:
+Option 2:
 
-`send(msg)` -  Can be used to send a `msg` from the template, e.g:
+We can alternatively add a custom socket listener to the `msg-input:<id>` event. This is useful if you want to listen to messages _only_ when they are received, and not when the widget first loads.
 
-```html
-&lt;v-btn @click="send({'hello': 'world'})">&lt;/v-btn>
+```js
+this.$socket.on('msg-input:' + this.id, (msg) => {
+    // do stuff with msg
+    // runs only when messages are received
+})
 ```
 
-`submit()` - Can be attached to a `<form />`. The `msg` sent will be an object
-  representation of the `FormData` from the attached form, e.g:
+This can be added into the widget's `mounted () { }` handler
+
+### Example (Raw JavaScript)
+
+Putting this together, here is a simple starter widget that will alert the user when they click the button, and send a message into Node-RED.
+
+```vue
+<template>
+    <!-- Any HTML can go here -->
+    <button class="my-class" onclick="onClick()">My Button</button>
+</template>
+
+<script>
+    /* Write any JavaScript here */
+    // add our onClick function to the window object to make it accessible by the HTML <button>
+    window.onClick = function () {
+        alert('Button has been clicked')
+    }
+
+    // Use send() function to pass on data back into Node-RED:
+    this.send('Component has loaded')
+
+    // Subscribe to the incoming msg's
+    this.$socket.on('msg-input:' + this.id, function(msg) {
+        // do stuff with the message
+        alert('message received: ' + msg.payload)
+    })
+</script>
+
+<style>
+    /* define any styles here - supports raw CSS */
+    .my-class {
+        color: red;
+    }
+</style>
+```
+
+### Loading External Dependencies
+
+It is possible to load external dependencies into your `ui-template` node. This is useful if you want to use a library that isn't included in the core Node-RED Dashboard 2.0 nodes.
+
+To do this, you'll need to load the dependency in the `<script>` section of your template. For example, to load the [Babylon.js](https://www.babylonjs.com/) library, you would do the following:
+
 ```html
-&lt;form @submit.prevent="submit">
-    &lt;v-text-field name="first" label="First Name">&lt;/v-text-field>
-    &lt;v-text-field name="last" label="Last Name">&lt;/v-text-field>
-    &lt;v-btn type="submit">&lt;/v-btn>
-&lt;/form>
+<script src="https://cdn.babylonjs.com/babylon.js"></script>
 ```
-Would send the following `msg` when submitted:
-```js
-{ "first": <value>, "last": <value> }
+
+You can then have _another_ `<script />` tag in the same `ui-template` that utilises this library.
+
+An important caveat here is that, whilst this does get injected into the `<head />` of the Dashboard, because our widgets are loaded after the initial page load, the library isn't always available straight away as your Widget and HTML loads. 
+
+If you need access to the library as soon as it's available, the trick to this is to run a `setInterval()` and watch the `window` object for the library to be loaded.
+
+For example:
+
+```vue
+<template>
+    <!-- Template Content Here -->
+</template>
+
+<script src="https://cdn.babylonjs.com/babylon.js"></script>
+
+<script>
+function init () {
+    alert('Babylon.js is loaded')
+}
+
+// run this code when the widget is built
+let interval = setInterval(() => {
+    if (window.BABYLON) {
+        // call an init() to use BABYLON
+        init();
+        // Babylon.js is loaded, so we can now use it
+        clearInterval(interval);
+    }
+}, 100);
+</script>
 ```
 
-#### Sending on Click
-Here, we call it when someone clicks our "Send Hello World" button:
+## Building Full Vue Components
+
+You can build full Vue components in the `ui-template` node, using VueJS's [Options API](https://vuejs.org/api/#options-api). This allows you to build your own bespoke behaviour, and gives you more control over the UI.
+
+A full list of the VueJS Options API properties that we currently support are:
+
+- `name` - The name of your component
+- `data` - A function that returns data you want available across your component (in both `<template>` and `<script>` sections)
+- `watch` - Run a function anytime a particular component variable changes
+- `computed` - Calculate a variable based on other variables in your component
+- `methods` - Define functions that can be called from your `<template>` or `<script>` sections
+- `mounted` - Run code when the component is first loaded
+- `unmounted` - Run code when the component is removed from the Dashboard
+
+### Example (Full Vue Component)
+
+Here we define a counter widget, and utilise Vue's `data`, `watch`, `computed` and `methods` properties. This widget will automatically update the `formattedCount` variable whenever the `count` variable changes and will send a message to Node-RED whenever the `count` variable reaches a multiple of 5.
 
 ```vue
-&lt;v-btn @click="send({payload: 'Hello World'})">Send Hello World</v-btn>
+<template>
+    <div>
+        <h2>Counter - loaded: {{ loaded }}</h2>
+        <p>Current Count: {{ count }}</p>
+        <p class="my-class">Formatted Count: {{ formattedCount }}</p>
+        <v-btn @click="increase()">Increment</v-btn>
+    </div>
+</template>
+
+<script>
+    export default {
+        data() {
+            // define variables available component-wide
+            // (in <template> and component functions)
+            return {
+                loaded: false,
+                count: 0
+            }
+        },
+        watch: {
+            // watch for any changes of "count"
+            count: function () {
+                if (this.count % 5 === 0) {
+                    this.send({payload: 'Multiple of 5'})
+                }
+            }
+        },
+        computed: {
+            // automatically compute this variable
+            // whenever VueJS deems appropriate
+            formattedCount: function () {
+                return `${this.count} Apples`
+            }
+        },
+        methods: {
+            // expose a method to our <template> and Vue Application
+            increase: function () {
+                this.count++
+            }
+        },
+        mounted() {
+            // code here when the component is first loaded
+            this.loaded = true
+        },
+        unmounted() {
+            // code here when the component is removed from the Dashboard
+            // i.e. when the user navigates away from the page
+        }
+    }
+</script>
+<style>
+    /* define any styles here - supports raw CSS */
+    .my-class {
+        color: red;
+    }
+</style>
 ```
 
-#### Sending on Change
-Or another example, where the payload is automatically sent any time the `v-model` is changed:
+Anything returned from the `data` function is automatically made available to the `<template>`. This means that we can use the `count` variable in our template, and it will automatically update as the variable changes.
+
+We can also `watch` any of these `data` variables, and react accordingly. For example, above, we send a message to Node-RED whenever the `count` variable reaches a multiple of 5.
+
+We use a `computed` variable which will automatically update whenever the `count` variable changes. This allows us to format the `count` variable in a way that is more useful to us to display, without affecting the underlying `count` variable.
+
+### Teleports
+
+You can use [Vue's Teleport](https://v3.vuejs.org/guide/teleport.html) feature to render content to a specific location in the DOM.
+
+The code can be written into a `ui-template` node, and the scope set to "group", "page" or "UI" depending on when you want this `<Teleport>` to be active.
+
+We provide some pre-defined locations that you can use:
+
+#### Page Name (`#app-bar-title`)
+
+Add content to the left-side of the header of the Dashboard. `<Teleport>` can be used as follows:
+
+```vue
+<template>
+    <Teleport v-if="mounted" to="#app-bar-title">
+        <v-btn>Button 1</v-btn>
+        <v-btn>Button 2</v-btn>
+    </Teleport>
+</template>
+<script>
+    export default {
+        data() {
+            return {
+                mounted: false
+            }
+        },
+        mounted() {
+            this.mounted = true
+        }
+    }
+</script>
+```
+
+This would result in:
+
+![Example of Teleporting content to the App Bar Title](/assets/images/appbar-title-teleport-actions.png "Example of Teleporting content to the App Bar Title"){data-zoomable}
+_Example of Teleporting content to the App Bar Title, adding to the existing page name_
+
+We can also turn off the rendering of the page name under the Dashboard's main settings, so, when using the teleport, this would be the only content rendered in the top-left.
+
+Here, we can render an image (injected via `msg.payload`) instead of the page name:
+
+```vue
+<template>
+    <Teleport v-if="mounted" to="#app-bar-title">
+        <img height="32px" :src="msg.payload"></img>
+    </Teleport>
+</template>
+<script>
+    export default {
+        data() {
+            return {
+                mounted: false
+            }
+        },
+        mounted() {
+            this.mounted = true
+        }
+    }
+</script>
+```
+
+This would result in:
+
+![Example of Teleporting content to the App Bar Title](/assets/images/appbar-title-teleport-img.png "Example of Teleporting content to the App Bar Title"){data-zoomable}
+_Example of Teleporting content to the App Bar Title, and hiding hte page name_
+
+#### App Bar - Actions (`#app-bar-actions`)
+
+Renders content to the right-hand side of the Dashboard's App Bar. To use this teleport, you can use the following syntax:
+
+```vue
+<template>
+    <Teleport v-if="mounted" to="#app-bar-actions">
+        <v-btn>My Action</v-btn>
+    </Teleport>
+</template>
+<script>
+    export default {
+        data() {
+            return {
+                mounted: false
+            }
+        },
+        mounted() {
+            this.mounted = true
+        }
+    }
+</script>
+```
+
+This would result in:
+
+![Example of Teleporting content to the App Bar](/assets/images/appbar-teleport.png "Example of Teleporting content to the App Bar"){data-zoomable}
+
+Note the use of `v-if="mounted"` in the `<Teleport />` tag. For some reason, Vue complains when trying to render a Teleport inside our `ui-template`, before the component has fully mounted, Including this `v-if` statement prevents this error.
+
+### URL Parameters
+
+Vue has a built-in `this.$route` object which details the information about the active route. This includes any query parameters included in the URL (e.g. `/dashboard/my-page?query=param`), which can be defined when using a [UI Control](./ui-control.md#change-page) or when navigating to a page directly.
+
+An example of how to access these parameters is as follows:
 
 ```vue
-&lt;v-rating hover :length="5" :size="32" v-model="value"
-    active-color="primary" @update:modelValue="send({payload: value})"/>
+<template>
+    <div>
+        <p>Query Parameter: {{ $route.query }}</p>
+    </div>
+</template>
 ```
 
-#### Reading Node Input
 
-Whenever a `ui-template` receives a `msg` in Node-RED, that is automatically assigned to the `msg` variable in the template.
+## Additional Examples
+
+Any Vue Components that you define in `ui-template` extend the underlying `ui-template` Vue component. This includes a collection of builtin methods, data and supported Widgets. You can also render dynamic content using any VueJS data-binding expressions, (e.g. `v-if`, `v-for`).
 
-Additionally, we also bind a computed variable `value` to `msg.payload`. This means that you can access the `msg` object in your template, as well as binding the `value` variable to any widgets you use. 
+### Reading Node-RED Input
 
-Such an example would be:
+Whenever a `ui-template` receives a `msg` in Node-RED, that is automatically assigned to the `msg` variable in the template. Such an example would be:
 
 ```html
-&lt;div>
-    &lt;h2>Latest &lt;code>msg&lt;/code> received:&lt;/h2>
-    &lt;pre>{{ msg }}&lt;/pre>
-&lt;/div>
+<template>
+    <div>
+        <h2>Latest <code>msg</code> received:</h2>
+        <pre>{{ msg }}</pre>
+    </div>
+</template>
 ```
 
-#### Vuetify Widgets
+![Example of UI Template displaying the last received message](/images/node-examples/ui-template-lastmsg.png "Example of UI Template displaying the last received message"){data-zoomable}
 
-The `ui-template` node also has access to the [Vuetify component library](https://vuetifyjs.com/en/components/all/) by default. The library provides a large number of pre-built widgets that you can use in your Dashboard.
+### Sending Messages to Node-RED
 
-These are particularly useful as they provide easy access to a large number of pre-built widgets that aren't necessarily included in the core nodes of Node-RED Dashboard 2.0.
+Two exposed methods, `send` and `submit`, allow you to send messages from the Dashboard to the Node-RED flow. 
 
-### Type - CSS (All Pages)
-When the scope is set to **Site Scoped Style**, the CSS in the template will be added to the `head` of all pages.
-e.g.
-```css
-.my-class {
-  color: red;
-}
+- `send` - Outputs a message (defined by the input to this function call) from this node in the Node-RED flow. 
+- `submit` - Send a `FormData` object when attached to a `<form>` element. The created object will consist of the `name` attributes for each form element, corresponding to their respective `value` attributes.
+
+#### Sending on Click
+Here, we call it when someone clicks our "Send Hello World" button:
+
+```vue
+<v-btn @click="send({payload: 'Hello World'})">Send Hello World</v-btn>
 ```
 
-### Type: CSS (Single Page)
-When the scope is set to **Site Scoped Style**, the CSS in the template will be added to the `head` of the selected page.
-e.g.
-```css
-.my-page1-only-class {
-  color: green;
-}
+#### Sending on Change
+Or another example, where the payload is automatically sent any time the `v-model` is changed:
+
+![Example of UI Template using Vuetify's Rating Widget](/images/node-examples/ui-template-rating1.png "Example of UI Template using Vuetify's Rating Widget"){data-zoomable}
+
+```vue
+<v-rating hover :length="5" :size="32" v-model="value"
+    active-color="primary" @update:model-value="send({payload: value})"/>
 ```
 
-</script>  
\ No newline at end of file
+`v-model` in Vue is a way of two-way binding a variable to a widget. Here, we bind the `value` variable to the `v-rating` widget. Then we watch for changes on that value with `@update:model-value` and send the `value` variable to the Node-RED flow via `msg.payload`.
+
+When changed, if wired to a "Debug" node, then we can see the resulting outcome is as follows:
+
+![Example output from using Vuetify's Rating Widget](/images/node-examples/ui-template-rating2.png "Example output from using Vuetify's Rating Widget"){data-zoomable}
+
+### Vuetify Widgets
+
+The `ui-template` node also has access to the [Vuetify component library](https://vuetifyjs.com/en/components/all/) by default. The library provides a large number of pre-built widgets that you can use in your Dashboard.
+
+These are particularly useful as they provide easy access to a large number of pre-built widgets that aren't necessarily included in the core nodes of Node-RED Dashboard 2.0.
+
+Some example widgets that you may find useful are:
+
+- [File Input](https://vuetifyjs.com/en/components/file-inputs/) - Allows for the selection of a file from the user's local filesystem.
+- [Star Rating Widget](https://vuetifyjs.com/en/components/ratings/) - A star rating widget, where users can select a rating from 1-n stars.
+- [Progress Linear](https://vuetifyjs.com/en/components/progress-linear/) - A horizontal bar to show progress of a task or single bar-graph type visualisations. 
+
+### Articles & Tutorials
+
+- [Building a Custom Video Player with UI Template](https://flowfuse.com/blog/2023/12/dashboard-0-10-0/)
+

From 73fd78a5dc80f8a7f598036b312b49efdc399e29 Mon Sep 17 00:00:00 2001
From: bartbutenaers <bart.butenaers@gmail.com>
Date: Sun, 17 Nov 2024 00:41:17 +0100
Subject: [PATCH 4/6] Force not needed

---
 ui/src/widgets/ui-template/UITemplate.vue | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/ui/src/widgets/ui-template/UITemplate.vue b/ui/src/widgets/ui-template/UITemplate.vue
index ffb68147c..540f12415 100644
--- a/ui/src/widgets/ui-template/UITemplate.vue
+++ b/ui/src/widgets/ui-template/UITemplate.vue
@@ -27,8 +27,8 @@ export default {
             if (!updates) {
                 return
             }
+            // Updating the format will automatically trigger the rerendering (see render hook below)
             this.updateDynamicProperty('format', updates.format)
-            this.$forceUpdate()
         },
         send (component, msg) {
             if (typeof (msg) !== 'object') {

From fc0ab3c1db00658793e9945f8eda881f293350d5 Mon Sep 17 00:00:00 2001
From: bartbutenaers <bart.butenaers@gmail.com>
Date: Sun, 17 Nov 2024 00:52:05 +0100
Subject: [PATCH 5/6] restore commit

---
 nodes/widgets/locales/en-US/ui_template.html | 509 ++++---------------
 1 file changed, 87 insertions(+), 422 deletions(-)

diff --git a/nodes/widgets/locales/en-US/ui_template.html b/nodes/widgets/locales/en-US/ui_template.html
index ac7c06f66..73774e464 100644
--- a/nodes/widgets/locales/en-US/ui_template.html
+++ b/nodes/widgets/locales/en-US/ui_template.html
@@ -1,487 +1,152 @@
----
-description: Harness the power of ui-template in Node-RED Dashboard 2.0 to design custom widgets and unique dashboard layouts.
-props:
-    Group: Defines which group of the UI Dashboard this widget will render in.
-    Scope: "Template nodes can be used  for 3 purposes/scopes: <ul><li><b>Widget (Group-Scoped):</b>A standard HTML/Vue widget rendered in a group in the Dashboard.</li><li><b>Widget (Page-Scoped):</b>A HTML/Vue widget that will render on a page, outside of any existing groups. Note that these widgets will render after any Groups. An example use case for this would be if you wanted to have a fixed footer on a given page.</li><li><b>Widget (UI-Scoped):</b>A HTML/Vue widget rendered on every page of the Dashboard. Most commonly used in conjunction with <a href=\"#teleports\">Teleports</a></li><li><b>CSS (All Pages):</b>Define custom CSS classes/styling that applies to the entire Dashboard.</li><li><b>CSS (Single Page):</b>Define custom CSS classes/styling that applies just a single page of your Dashboard.</li></ul>"
-    Class: Appends CSS classes to the widget
-    Template: The content of the widget or CSS &lt;style&gt;. If using this for CSS, you do not need to include any &lt;style&gt; tags, as these will be automatically added.
-dynamic:
-    Format:
-        payload: msg.ui_update.format
-        structure: ["String"]
----
+<script type="text/markdown" data-help-name="ui-template">
+(see [full docs](https://dashboard.flowfuse.com/nodes/widgets/ui-template.html))
 
-<script setup>
-    import AddedIn from '../../components/AddedIn.vue';
-    import TryDemo from "./../../components/TryDemo.vue";
-</script>
+The content of `ui-template` is controlled by the "Type" property.
 
+Provides a means to render custom content or a set of node-styles depending on scope.
+- **Widget:** A Vue Component (including any <a href="https://vuetifyjs.com/en/components/all/" target="blank">
+  Vuetify component</a>) that is rendered in the Dashboard.
+- **CSS (All Pages):** Define custom CSS classes/styling that applies to the entire Dashboard.
+- **CSS (Single Page):** Define custom CSS classes/styling that applies just a single page of your Dashboard
 
-<TryDemo href="template">
+### Type: Widget
+When the scope is set to **Widget**, the template will be rendered in the Dashboard as HTML.
 
-# Template `ui-template` <AddedIn version="0.10.0"/>
+You can render dynamic content using any VueJS data-binding expressions, (e.g. `v-if`, `v-for`, `:class`)
+and access incoming data to the node via the `msg` object.
 
-</TryDemo>
- 
-Provide custom JS and HTML (including any [Vuetify components](https://vuetifyjs.com/en/components/all/)) to render in the Dashboard.
-
-- Define your own Vue components
-- Load external JS dependencies
-- Write raw JavaScript
-- Use Vuetify components
-
-## Properties
-
-<PropsTable/>
-
-## Dynamic Properties
-
-<DynamicPropsTable/>
-
-## Writing Custom Widgets
-
-UI Template will parse different tags and render them into Dashboard. The available tags are:
-
-- `<template>` - Any HTML code in here will be rendered into the Dashboard.
-- `<script>` - Any JavaScript code in here will be executed when the widget is loaded. You can also [define a full VueJS component](#building-full-vue-components) here.
-- `<style>` - Any CSS code in here will be injected into the Dashboard.
-
-### Working with Variables
+#### Working with Variables
 
 Any variables that you want to render into your `<template />` are done so in one of two ways:
 
-::: v-pre
-- **Attribute Binding** - Use `:` to bind a variable to an attribute. Anything inside the `""` here is treated as JavaScript, for example: 
+- **Attribute Binding** - Use `:` to bind a variable to an attribute. Anything inside the double quotes `""` is treated as JavaScript, for example: 
 
 ```html
-<p :class="msg.payload">Hello World</p>
+&lt;p :class="msg.payload">Hello World&lt;/p>
 ````
 
 or, if you want to use `msg.payload` as part of the value, you can do this:
 
 ```html
-<!-- Change color based on msg.payload. Expects payload to be either "error", "warning" or "info" -->`
-<p :class="'text-' + msg.payload">Hello World</p>
-<!-- or with string literals: -->
-<p :class="`text-${msg.payload}`">Hello World</p>
+&lt;!-- Change color based on msg.payload. Expects payload to be either "error", "warning" or "info" -->
+&lt;p :class="'text-' + msg.payload">Hello World&lt;/p>
+&lt;!-- or with string literals: -->
+&lt;p :class="`text-${msg.payload}`">Hello World&lt;/p>
 ````
 
-or even use `msg.payload` as a condition:
+or use `msg.payload` as a condition:
 
 ```html
-<!-- 
+&lt;!-- 
   Change color based on the value of msg.payload: 
   * When msg.payload equals "error", set text to the predefined `text-error` color. 
   * Otherwise, set text to the predefined `text-info` color.
 -->
-<p :class="msg.payload === 'error' ? 'text-error' : 'text-info'">Hello World</p>
+&lt;p :class="msg.payload === 'error' ? 'text-error' : 'text-info'">Hello World&lt;/p>
 ````
 
-- **Text Interpolation** - Use `{{ }}` to interpolate a variable into the text of an element. Anything inside the curly brackets is treated as JavaScript. For example:
-
-```html
-<p>Hello {{ msg.payload }}</p>
-```
+or even as a conditional block:
 
 ```html
-<p>Percentage {{ msg.payload * 100 }}%</p>
-```
-
-### Built-in Variables
-
-You have access to a number of built-in variables in your `ui-template` node:
-
-- `id` - The ID of the `ui-template` node, assigned by Node-RED.
-- `msg` - The last message received by the `ui-template` node.
-- `$socket` - The socket.io connection that is used to communicate with the Node-RED backend.
-
-When accessing the `msg` variable inside a `<script />` tag, you need to prefix the variable name with `this.` (e.g. `this.msg.payload`) so that it knows you're accessing the component-bound `msg` variable.
-
-***Important Note:*** On first load, `msg.payload` may be `null` or `undefined`, and trying to access a nested property will throw an error. Using the **optional chaining** (?.) operator, e.g. `msg.payload?.nested?.property` will prevent these errors occurring.
-
-#### Accessing Node-RED Global/Flow Context
-
-The `flow`/`global` context stores are not available in the Dashboard UI, as such, the best practice here is to use a "Change" node prior to the `ui-template` node to assign a `msg.<property>` to the relevant value from the `flow.` or `global.` store:
-
-![Example of using a Change node to assign a value to `msg.payload`](/images/node-examples/change-flow-to-msg.png "Example of using a Change node to assign a value to `msg.payload`"){data-zoomable}
-_Example of using a Change node to assign a value to `msg.payload`._
-
-### Built-in Functions
-
-We also offer some helper functions for the Node-RED integration too:
-
-#### Sending Data
-
-- `this.send(msg)` - Send a message to the Node-RED flow. If a non-Object value is sent, then Dashboard will automatically wrap that into a `msg.payload` object.
-
-#### Receiving Data
-
-There are two ways of responding to messages received by your `ui-template` node:
-
-Option 1: 
-
-In VueJS, we can `watch` a variable for any changes, and react accordingly.
-
-As mentioned in the [Built-in Variables](#built-in-variables) section above, we have access to the `msg` variable in our `ui-template` node. We can watch this variable for any changes, and react accordingly:
-
-```js
-watch: {
-    msg: function () {
-        // do stuff with this.msg
-        // runs onLoad and onInput
-    }
-}
-```
-
-It's worth noting though, that whilst this will update when new messages are received, it _also_ updates when a widget first loads, and the latest `msg` is loaded to the widget.
-
-Option 2:
-
-We can alternatively add a custom socket listener to the `msg-input:<id>` event. This is useful if you want to listen to messages _only_ when they are received, and not when the widget first loads.
-
-```js
-this.$socket.on('msg-input:' + this.id, (msg) => {
-    // do stuff with msg
-    // runs only when messages are received
-})
-```
-
-This can be added into the widget's `mounted () { }` handler
-
-### Example (Raw JavaScript)
-
-Putting this together, here is a simple starter widget that will alert the user when they click the button, and send a message into Node-RED.
-
-```vue
-<template>
-    <!-- Any HTML can go here -->
-    <button class="my-class" onclick="onClick()">My Button</button>
-</template>
-
-<script>
-    /* Write any JavaScript here */
-    // add our onClick function to the window object to make it accessible by the HTML <button>
-    window.onClick = function () {
-        alert('Button has been clicked')
-    }
-
-    // Use send() function to pass on data back into Node-RED:
-    this.send('Component has loaded')
-
-    // Subscribe to the incoming msg's
-    this.$socket.on('msg-input:' + this.id, function(msg) {
-        // do stuff with the message
-        alert('message received: ' + msg.payload)
-    })
-</script>
-
-<style>
-    /* define any styles here - supports raw CSS */
-    .my-class {
-        color: red;
-    }
-</style>
+&lt;!-- 
+  Show a message based on the value of msg.payload:
+  * When msg.payload equals "error", show the error message.
+  * When msg.payload equals "warning", show the warning message.
+  * Otherwise, show the info message.
+-->
+&lt;div>
+  &lt;p v-if="msg.payload === 'error'">Error: Something went wrong!&lt;/p>
+  &lt;p v-else-if="msg.payload === 'warning'">Warning: Be careful!&lt;/p>
+  &lt;p v-else>Info: Everything is fine!&lt;/p>
+&lt;/div>
 ```
 
-### Loading External Dependencies
-
-It is possible to load external dependencies into your `ui-template` node. This is useful if you want to use a library that isn't included in the core Node-RED Dashboard 2.0 nodes.
-
-To do this, you'll need to load the dependency in the `<script>` section of your template. For example, to load the [Babylon.js](https://www.babylonjs.com/) library, you would do the following:
+- **Text Interpolation** - Use `{{ }}` to interpolate a variable into the text of an element. Anything inside the curly brackets is treated as JavaScript. For example:
 
 ```html
-<script src="https://cdn.babylonjs.com/babylon.js"></script>
-```
-
-You can then have _another_ `<script />` tag in the same `ui-template` that utilises this library.
-
-An important caveat here is that, whilst this does get injected into the `<head />` of the Dashboard, because our widgets are loaded after the initial page load, the library isn't always available straight away as your Widget and HTML loads. 
-
-If you need access to the library as soon as it's available, the trick to this is to run a `setInterval()` and watch the `window` object for the library to be loaded.
-
-For example:
-
-```vue
-<template>
-    <!-- Template Content Here -->
-</template>
-
-<script src="https://cdn.babylonjs.com/babylon.js"></script>
-
-<script>
-function init () {
-    alert('Babylon.js is loaded')
-}
-
-// run this code when the widget is built
-let interval = setInterval(() => {
-    if (window.BABYLON) {
-        // call an init() to use BABYLON
-        init();
-        // Babylon.js is loaded, so we can now use it
-        clearInterval(interval);
-    }
-}, 100);
-</script>
+&lt;p>Hello {{ msg.payload }}&lt;/p>
 ```
 
-## Building Full Vue Components
-
-You can build full Vue components in the `ui-template` node, using VueJS's [Options API](https://vuejs.org/api/#options-api). This allows you to build your own bespoke behaviour, and gives you more control over the UI.
-
-A full list of the VueJS Options API properties that we currently support are:
-
-- `name` - The name of your component
-- `data` - A function that returns data you want available across your component (in both `<template>` and `<script>` sections)
-- `watch` - Run a function anytime a particular component variable changes
-- `computed` - Calculate a variable based on other variables in your component
-- `methods` - Define functions that can be called from your `<template>` or `<script>` sections
-- `mounted` - Run code when the component is first loaded
-- `unmounted` - Run code when the component is removed from the Dashboard
-
-### Example (Full Vue Component)
-
-Here we define a counter widget, and utilise Vue's `data`, `watch`, `computed` and `methods` properties. This widget will automatically update the `formattedCount` variable whenever the `count` variable changes and will send a message to Node-RED whenever the `count` variable reaches a multiple of 5.
-
-```vue
-<template>
-    <div>
-        <h2>Counter - loaded: {{ loaded }}</h2>
-        <p>Current Count: {{ count }}</p>
-        <p class="my-class">Formatted Count: {{ formattedCount }}</p>
-        <v-btn @click="increase()">Increment</v-btn>
-    </div>
-</template>
-
-<script>
-    export default {
-        data() {
-            // define variables available component-wide
-            // (in <template> and component functions)
-            return {
-                loaded: false,
-                count: 0
-            }
-        },
-        watch: {
-            // watch for any changes of "count"
-            count: function () {
-                if (this.count % 5 === 0) {
-                    this.send({payload: 'Multiple of 5'})
-                }
-            }
-        },
-        computed: {
-            // automatically compute this variable
-            // whenever VueJS deems appropriate
-            formattedCount: function () {
-                return `${this.count} Apples`
-            }
-        },
-        methods: {
-            // expose a method to our <template> and Vue Application
-            increase: function () {
-                this.count++
-            }
-        },
-        mounted() {
-            // code here when the component is first loaded
-            this.loaded = true
-        },
-        unmounted() {
-            // code here when the component is removed from the Dashboard
-            // i.e. when the user navigates away from the page
-        }
-    }
-</script>
-<style>
-    /* define any styles here - supports raw CSS */
-    .my-class {
-        color: red;
-    }
-</style>
-```
-
-Anything returned from the `data` function is automatically made available to the `<template>`. This means that we can use the `count` variable in our template, and it will automatically update as the variable changes.
-
-We can also `watch` any of these `data` variables, and react accordingly. For example, above, we send a message to Node-RED whenever the `count` variable reaches a multiple of 5.
-
-We use a `computed` variable which will automatically update whenever the `count` variable changes. This allows us to format the `count` variable in a way that is more useful to us to display, without affecting the underlying `count` variable.
-
-### Teleports
-
-You can use [Vue's Teleport](https://v3.vuejs.org/guide/teleport.html) feature to render content to a specific location in the DOM.
-
-The code can be written into a `ui-template` node, and the scope set to "group", "page" or "UI" depending on when you want this `<Teleport>` to be active.
-
-We provide some pre-defined locations that you can use:
-
-#### Page Name (`#app-bar-title`)
-
-Add content to the left-side of the header of the Dashboard. `<Teleport>` can be used as follows:
-
-```vue
-<template>
-    <Teleport v-if="mounted" to="#app-bar-title">
-        <v-btn>Button 1</v-btn>
-        <v-btn>Button 2</v-btn>
-    </Teleport>
-</template>
-<script>
-    export default {
-        data() {
-            return {
-                mounted: false
-            }
-        },
-        mounted() {
-            this.mounted = true
-        }
-    }
-</script>
-```
-
-This would result in:
-
-![Example of Teleporting content to the App Bar Title](/assets/images/appbar-title-teleport-actions.png "Example of Teleporting content to the App Bar Title"){data-zoomable}
-_Example of Teleporting content to the App Bar Title, adding to the existing page name_
-
-We can also turn off the rendering of the page name under the Dashboard's main settings, so, when using the teleport, this would be the only content rendered in the top-left.
-
-Here, we can render an image (injected via `msg.payload`) instead of the page name:
-
-```vue
-<template>
-    <Teleport v-if="mounted" to="#app-bar-title">
-        <img height="32px" :src="msg.payload"></img>
-    </Teleport>
-</template>
-<script>
-    export default {
-        data() {
-            return {
-                mounted: false
-            }
-        },
-        mounted() {
-            this.mounted = true
-        }
-    }
-</script>
-```
-
-This would result in:
-
-![Example of Teleporting content to the App Bar Title](/assets/images/appbar-title-teleport-img.png "Example of Teleporting content to the App Bar Title"){data-zoomable}
-_Example of Teleporting content to the App Bar Title, and hiding hte page name_
-
-#### App Bar - Actions (`#app-bar-actions`)
-
-Renders content to the right-hand side of the Dashboard's App Bar. To use this teleport, you can use the following syntax:
-
-```vue
-<template>
-    <Teleport v-if="mounted" to="#app-bar-actions">
-        <v-btn>My Action</v-btn>
-    </Teleport>
-</template>
-<script>
-    export default {
-        data() {
-            return {
-                mounted: false
-            }
-        },
-        mounted() {
-            this.mounted = true
-        }
-    }
-</script>
+```html
+&lt;p>Percentage {{ msg.payload * 100 }}%&lt;/p>
 ```
 
-This would result in:
-
-![Example of Teleporting content to the App Bar](/assets/images/appbar-teleport.png "Example of Teleporting content to the App Bar"){data-zoomable}
+#### Built In Functions
 
-Note the use of `v-if="mounted"` in the `<Teleport />` tag. For some reason, Vue complains when trying to render a Teleport inside our `ui-template`, before the component has fully mounted, Including this `v-if` statement prevents this error.
+The template comes with two built-in functions:
 
-### URL Parameters
+`send(msg)` -  Can be used to send a `msg` from the template, e.g:
 
-Vue has a built-in `this.$route` object which details the information about the active route. This includes any query parameters included in the URL (e.g. `/dashboard/my-page?query=param`), which can be defined when using a [UI Control](./ui-control.md#change-page) or when navigating to a page directly.
-
-An example of how to access these parameters is as follows:
-
-```vue
-<template>
-    <div>
-        <p>Query Parameter: {{ $route.query }}</p>
-    </div>
-</template>
+```html
+&lt;v-btn @click="send({'hello': 'world'})">&lt;/v-btn>
 ```
 
-
-## Additional Examples
-
-Any Vue Components that you define in `ui-template` extend the underlying `ui-template` Vue component. This includes a collection of builtin methods, data and supported Widgets. You can also render dynamic content using any VueJS data-binding expressions, (e.g. `v-if`, `v-for`).
-
-### Reading Node-RED Input
-
-Whenever a `ui-template` receives a `msg` in Node-RED, that is automatically assigned to the `msg` variable in the template. Such an example would be:
-
+`submit()` - Can be attached to a `<form />`. The `msg` sent will be an object
+  representation of the `FormData` from the attached form, e.g:
 ```html
-<template>
-    <div>
-        <h2>Latest <code>msg</code> received:</h2>
-        <pre>{{ msg }}</pre>
-    </div>
-</template>
+&lt;form @submit.prevent="submit">
+    &lt;v-text-field name="first" label="First Name">&lt;/v-text-field>
+    &lt;v-text-field name="last" label="Last Name">&lt;/v-text-field>
+    &lt;v-btn type="submit">&lt;/v-btn>
+&lt;/form>
+```
+Would send the following `msg` when submitted:
+```js
+{ "first": <value>, "last": <value> }
 ```
-
-![Example of UI Template displaying the last received message](/images/node-examples/ui-template-lastmsg.png "Example of UI Template displaying the last received message"){data-zoomable}
-
-### Sending Messages to Node-RED
-
-Two exposed methods, `send` and `submit`, allow you to send messages from the Dashboard to the Node-RED flow. 
-
-- `send` - Outputs a message (defined by the input to this function call) from this node in the Node-RED flow. 
-- `submit` - Send a `FormData` object when attached to a `<form>` element. The created object will consist of the `name` attributes for each form element, corresponding to their respective `value` attributes.
 
 #### Sending on Click
 Here, we call it when someone clicks our "Send Hello World" button:
 
 ```vue
-<v-btn @click="send({payload: 'Hello World'})">Send Hello World</v-btn>
+&lt;v-btn @click="send({payload: 'Hello World'})">Send Hello World</v-btn>
 ```
 
 #### Sending on Change
 Or another example, where the payload is automatically sent any time the `v-model` is changed:
 
-![Example of UI Template using Vuetify's Rating Widget](/images/node-examples/ui-template-rating1.png "Example of UI Template using Vuetify's Rating Widget"){data-zoomable}
-
 ```vue
-<v-rating hover :length="5" :size="32" v-model="value"
-    active-color="primary" @update:model-value="send({payload: value})"/>
+&lt;v-rating hover :length="5" :size="32" v-model="value"
+    active-color="primary" @update:modelValue="send({payload: value})"/>
 ```
 
-`v-model` in Vue is a way of two-way binding a variable to a widget. Here, we bind the `value` variable to the `v-rating` widget. Then we watch for changes on that value with `@update:model-value` and send the `value` variable to the Node-RED flow via `msg.payload`.
+#### Reading Node Input
 
-When changed, if wired to a "Debug" node, then we can see the resulting outcome is as follows:
+Whenever a `ui-template` receives a `msg` in Node-RED, that is automatically assigned to the `msg` variable in the template.
 
-![Example output from using Vuetify's Rating Widget](/images/node-examples/ui-template-rating2.png "Example output from using Vuetify's Rating Widget"){data-zoomable}
+Additionally, we also bind a computed variable `value` to `msg.payload`. This means that you can access the `msg` object in your template, as well as binding the `value` variable to any widgets you use. 
 
-### Vuetify Widgets
+Such an example would be:
 
-The `ui-template` node also has access to the [Vuetify component library](https://vuetifyjs.com/en/components/all/) by default. The library provides a large number of pre-built widgets that you can use in your Dashboard.
+```html
+&lt;div>
+    &lt;h2>Latest &lt;code>msg&lt;/code> received:&lt;/h2>
+    &lt;pre>{{ msg }}&lt;/pre>
+&lt;/div>
+```
 
-These are particularly useful as they provide easy access to a large number of pre-built widgets that aren't necessarily included in the core nodes of Node-RED Dashboard 2.0.
+#### Vuetify Widgets
 
-Some example widgets that you may find useful are:
+The `ui-template` node also has access to the [Vuetify component library](https://vuetifyjs.com/en/components/all/) by default. The library provides a large number of pre-built widgets that you can use in your Dashboard.
 
-- [File Input](https://vuetifyjs.com/en/components/file-inputs/) - Allows for the selection of a file from the user's local filesystem.
-- [Star Rating Widget](https://vuetifyjs.com/en/components/ratings/) - A star rating widget, where users can select a rating from 1-n stars.
-- [Progress Linear](https://vuetifyjs.com/en/components/progress-linear/) - A horizontal bar to show progress of a task or single bar-graph type visualisations. 
+These are particularly useful as they provide easy access to a large number of pre-built widgets that aren't necessarily included in the core nodes of Node-RED Dashboard 2.0.
 
-### Articles & Tutorials
+### Type - CSS (All Pages)
+When the scope is set to **Site Scoped Style**, the CSS in the template will be added to the `head` of all pages.
+e.g.
+```css
+.my-class {
+  color: red;
+}
+```
 
-- [Building a Custom Video Player with UI Template](https://flowfuse.com/blog/2023/12/dashboard-0-10-0/)
+### Type: CSS (Single Page)
+When the scope is set to **Site Scoped Style**, the CSS in the template will be added to the `head` of the selected page.
+e.g.
+```css
+.my-page1-only-class {
+  color: green;
+}
+```
 
+</script>  

From 23e339c04e834d63e184535a9fd8fbdc7c812fdc Mon Sep 17 00:00:00 2001
From: bartbutenaers <bart.butenaers@gmail.com>
Date: Sun, 17 Nov 2024 00:52:58 +0100
Subject: [PATCH 6/6] dynamic ui-template

---
 docs/nodes/widgets/ui-template.md | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/docs/nodes/widgets/ui-template.md b/docs/nodes/widgets/ui-template.md
index 77857a147..ac7c06f66 100644
--- a/docs/nodes/widgets/ui-template.md
+++ b/docs/nodes/widgets/ui-template.md
@@ -5,6 +5,10 @@ props:
     Scope: "Template nodes can be used  for 3 purposes/scopes: <ul><li><b>Widget (Group-Scoped):</b>A standard HTML/Vue widget rendered in a group in the Dashboard.</li><li><b>Widget (Page-Scoped):</b>A HTML/Vue widget that will render on a page, outside of any existing groups. Note that these widgets will render after any Groups. An example use case for this would be if you wanted to have a fixed footer on a given page.</li><li><b>Widget (UI-Scoped):</b>A HTML/Vue widget rendered on every page of the Dashboard. Most commonly used in conjunction with <a href=\"#teleports\">Teleports</a></li><li><b>CSS (All Pages):</b>Define custom CSS classes/styling that applies to the entire Dashboard.</li><li><b>CSS (Single Page):</b>Define custom CSS classes/styling that applies just a single page of your Dashboard.</li></ul>"
     Class: Appends CSS classes to the widget
     Template: The content of the widget or CSS &lt;style&gt;. If using this for CSS, you do not need to include any &lt;style&gt; tags, as these will be automatically added.
+dynamic:
+    Format:
+        payload: msg.ui_update.format
+        structure: ["String"]
 ---
 
 <script setup>
@@ -30,6 +34,10 @@ Provide custom JS and HTML (including any [Vuetify components](https://vuetifyjs
 
 <PropsTable/>
 
+## Dynamic Properties
+
+<DynamicPropsTable/>
+
 ## Writing Custom Widgets
 
 UI Template will parse different tags and render them into Dashboard. The available tags are:
@@ -476,3 +484,4 @@ Some example widgets that you may find useful are:
 ### Articles & Tutorials
 
 - [Building a Custom Video Player with UI Template](https://flowfuse.com/blog/2023/12/dashboard-0-10-0/)
+