Merge pull request #408 from FlowFuse/258-ui-control

Widget: UI Control

docs/.vitepress/config.js

@@ -81,6 +81,7 @@ export default ({ mode }) => {
               collapsed: false,
               items: [
                 { text: 'ui-button', link: '/nodes/widgets/ui-button' },
+                { text: 'ui-control', link: '/nodes/widgets/ui-control' },
                 { text: 'ui-chart', link: '/nodes/widgets/ui-chart' },
                 { text: 'ui-dropdown', link: '/nodes/widgets/ui-dropdown' },
                 { text: 'ui-event', link: '/nodes/widgets/ui-event' },

docs/components/AddedIn.vue

@@ -0,0 +1,37 @@
+<template>
+    <a class="added-in" :href="'https://github.com/FlowFuse/node-red-dashboard/releases/tag/v' + version" target="_blank">Added In: v{{ version }}</a>
+</template>
+
+<script>
+export default {
+    name: 'AddedIn',
+    props: {
+        version: {
+            type: String,
+            required: true
+        }
+    }
+}
+</script>
+
+<style scoped>
+.added-in {
+    display: inline-flex;
+    font-size: 14px;
+    line-height: 20px;
+    padding: 3px 9px;
+    color: var(--vp-c-brand-1);
+    margin-left: 0.5em;
+    border-radius: 2rem;
+    background-color: var(--vp-c-brand-soft);
+    border: 1px solid var(--vp-c-brand-1);
+    text-decoration: none;
+    transition: none;
+    vertical-align: middle;
+}
+
+.added-in:hover {
+    background-color: var(--vp-c-brand-1);
+    color: #fff;
+}
+</style>

docs/contributing/widgets/third-party.md

@@ -1,4 +1,8 @@
-# Building Third Party Widgets
+<script setup>
+    import AddedIn from '../../components/AddedIn.vue'
+</script>
+
+# Building Third Party Widgets <AddedIn version="0.8.0" />
 
 If you have an idea for a widget that you'd like to build in Dashboard 2.0 we are open to Pull Requests and ideas for additions to the [core collection](../../nodes/widgets.md) of Widgets.
 

docs/layouts/notebook.md

@@ -1,4 +1,8 @@
-# Layout: Notebook
+<script setup>
+    import AddedIn from '../components/AddedIn.vue'
+</script>
+
+# Layout: Notebook <AddedIn version="0.4.0" />
 
 This layout mimics a traditional Jupyter Notebook, where the layout will stretch to 100% width, up to a maximum width of 1024px, and will centrally align.
 

docs/nodes/widgets/ui-control.md

@@ -0,0 +1,157 @@
+---
+{
+    "events": [
+        {
+            "event": "$pageview",
+            "payload": "{ page }",
+            "description": "Sent whenever a user <i>views</i> a given page on the Dashboard"
+        },
+        {
+            "event": "$pageleave",
+            "payload": "{ page }",
+            "description": "Sent whenever a user <i>leaves</i> a given page on the Dashboard"
+        }
+    ]
+}
+---
+
+<script setup>
+    import EventsList from '../../components/EventsList.vue'
+    import AddedIn from '../../components/AddedIn.vue'
+</script>
+
+# Control `ui-control` <AddedIn version="0.9.0" />
+
+This widget doesn't render any content into your Dashboard. Instead, it provides an interface for you to control the behaviour of your Dashboard from within the Node-RED Editor.
+
+Functionality is generally divided into two main features:
+
+- **Navigation**: Force the user to move to a new page
+- **Display**: Show/Hide groups and pages
+- **Disability**: Enable/Disable groups and pages, this still shows them, but prevents interaction
+
+## Controls List
+
+Currently, we support the following controls:
+
+### Navigation
+
+You can programmaticaly force navigation with the following payloads with `ui-control`:
+
+#### Change Page
+
+Explicitely choose the page you want to navigate to:
+
+```js
+// String
+msg.payload = '<Page Name>'
+
+// Object
+msg.payload = {
+    page: '<Page Name>',
+}
+```
+
+#### Next/Previous
+
+Navigate to the next or previous page in the list:
+
+```js
+// Next Page
+msg.payload = "+1"
+
+// Previous Page
+msg.payload = "-1"
+```
+
+#### Refresh
+
+You can force a refresh of the current view by sending a blank string payload:
+
+```js
+msg.payload = ""
+```
+
+### Show/Hide
+
+You can programmaticaly show/hide groups and pages with the following payload into `ui-control`:
+
+```js
+msg.payload = {
+    pages: {
+        show: ['<Page Name>', '<Page Name>'],
+        hide: ['<Page Name>']
+    }
+    groups: {
+        show: ['<Group Name>', '<Group Name>'],
+        hide: ['<Group Name>']
+    }
+}
+```
+
+_Note:_ `pages` can be subbed with `tabs` as per Dashboard 1.0 and `groups` can also be subbed with `group` as per Dashboard 1.0.
+
+### Enable/Disable
+
+You can programmaticaly disable/enable groups and pages with the following payload into `ui-control`:
+
+```js
+msg.payload = {
+    pages: {
+        enable: ['<Page Name>', '<Page Name>'],
+        disable: ['<Page Name>']
+    }
+    groups: {
+        enable: ['<Group Name>', '<Group Name>'],
+        disable: ['<Group Name>']
+    }
+}
+```
+
+_Note:_ `pages` can be subbed with `tabs` as per Dashboard 1.0 and `groups` can also be subbed with `group` as per Dashboard 1.0.
+
+## Events List
+
+In addition to `ui-control` taking input to _control_ the UI, we have also maintained support for all events emitted by `ui-control` from Dashboard 1.0 here too.
+
+### Connection Status
+
+We follow the Dashboard 1.0 convention for emitting socket-based events from the `ui-control` node.
+
+#### .on('connection')
+
+When a new Dashboard client connects to Node-RED, the `ui-control` node will emit:
+
+```js
+msg = {
+    payload: 'connect',
+    socketid: '<socketid>',
+    socketip: '<socketip>'
+}
+```
+
+#### .on('disconnect')
+
+When a Dashboard client disconnects from Node-RED, the `ui-control` node will emit:
+
+```js
+msg = {
+    payload: 'lost',
+    socketid: '<socketid>',
+    socketip: '<socketip>'
+}
+```
+
+### Change Tab/Page
+
+When a user changes the active tab or page, the `ui-control` node will emit:
+
+```js
+msg = {
+    payload: 'change',
+    socketid: '<socketid>',
+    socketip: '<socketip>',
+    tab: '<Page Index>',
+    name: '<Page Name>'
+}
+```

docs/nodes/widgets/ui-event.md

@@ -17,9 +17,10 @@
 
 <script setup>
     import EventsList from '../../components/EventsList.vue'
+    import AddedIn from '../../components/AddedIn.vue'
 </script>
 
-# Event `ui-event`
+# Event `ui-event` <AddedIn version="0.9.0" />
 
 This widget doesn't render any content into your Dashboard. Instead, it listens for user-driven behaviour and events in your Dashboard and emits accordingly into the Node-RED Editor when those events have taken place.
 
@@ -36,6 +37,8 @@ Each time a user views a page, the `ui-event` node will emit:
 ```js
 msg = {
     topic: '$pageview',
+    socketid: '1234',
+    socketip: '127.0.0.1'
     payload: {
         page: {
             name: 'Page Name',

docs/nodes/widgets/ui-markdown.md

@@ -5,6 +5,7 @@ props:
 ---
 
 <script setup>
+    import AddedIn from '../../components/AddedIn.vue'
 </script>
 
 # Markdown Viewer `ui-markdown`
@@ -70,7 +71,7 @@ function () {
 | `msg.payload` | {{ msg.payload || 'Placeholder' }} |
 ````
 
-## Mermaid Charts
+## Mermaid Charts <AddedIn version="0.5.0" />
 
 The `ui-markdown` widget also supports the injection of [Mermaid](https://mermaid.js.org/intro/). To do so, you can include a mermaid chart definition inside a Markdown fenced code block, defined with the `mermaid` type:
 

docs/nodes/widgets/ui-notification.md

@@ -10,7 +10,11 @@ props:
     Class: Appends CSS classes to the widget
 ---
 
-# Notification `ui-notification`
+<script setup>
+    import AddedIn from '../../components/AddedIn.vue'
+</script>
+
+# Notification `ui-notification` <AddedIn version="0.5.0" />
 
 Known in Dashboard 1.0 as a "Toast", this widget displays text/HTML in a small window that will appear on the screen for a defined duration of time (`timeout`) and at a defined location on the screen (`position`).
 

docs/nodes/widgets/ui-table.md

@@ -9,9 +9,10 @@ props:
 ---
 
 <script setup>
+    import AddedIn from '../../components/AddedIn.vue'
 </script>
 
-# Data Table `ui-table`
+# Data Table `ui-table` <AddedIn version="0.4.0" />
 
 Renders a set of data in a tabular format. Expects an input (`msg.payload`) in the format of:
 

docs/user/migration.md

@@ -4,6 +4,7 @@
 
     import uiButton from './migration/ui_button.json'
     import uiChart from './migration/ui_chart.json'
+    import uiControl from './migration/ui_control.json'
     import uiDropdown from './migration/ui_dropdown.json'
     import uiForm from './migration/ui_form.json'
     import uiSlider from './migration/ui_slider.json'
@@ -16,6 +17,7 @@
     const widgets = ref({
         'ui_button': uiButton,
         'ui_chart': uiChart,
+        'ui_control': uiControl,
         'ui_dropdown': uiDropdown,
         'ui_form': uiForm,
         'ui_slider': uiSlider,
@@ -140,6 +142,16 @@ is currently _not_ supported. If this is of particular importance, please do voi
 
 Whilst there is currently not an explicit `ui_colour_picker` widget, the `ui_text_input` widget can be used to achieve the same result, by setting _"type"_ to _"color"_
 
+### `ui_control`
+
+<MigrationWidgetProfile :profile="widgets['ui_control']" />
+
+#### Controls List
+
+All Dashboard 1.0 controls are supported in Dashboard 2.0, with the exception of the `open/close` control for a group, which is currently not supported.
+
+You can see detailed documentation of the available controls, and emitted events [here](/nodes/widgets/ui-control.html).
+
 ### `ui_date_picker`
 
 Whilst there is currently not an explicit `ui_date_picker` widget, the `ui_text_input` widget can be used to achieve the same result, by setting _"type"_ to _"date"_,  _"time"_,  _"week"_ or  _"month"_.
@@ -198,13 +210,6 @@ You can track progress of this development effort here: [Issue #41](https://gith
 <MigrationWidgetProfile :profile="widgets['ui_toast']" />
 
 
-### `ui_control`
-
-<MigrationWidgetProfile :profile="widgets['ui_control']" />
-
-Track progress, and input ideas here: [UI Control #258](https://github.com/FlowFuse/node-red-dashboard/issues/258).
-
-
 ## Theming
 
 We have tried to make theming in Dashboard 2.0 more low-code friendly, by providing a number of exposed properties, and a wrapping `ui-theme` config node which is assigned at the `ui-page` level.

docs/user/migration/ui_control.json

@@ -1,11 +1,16 @@
 {
     "node": "ui_button",
-    "description": "Button",
+    "description": "Send events to Dashboard in order to show/hide content, disable/enable content and navigate between pages",
     "properties": [
         {
-            "property": "label",
-            "changes": "label",
-            "notes": "label"
+            "property": "name",
+            "changes": null,
+            "notes": null
+        },
+        {
+            "property": "events",
+            "changes": null,
+            "notes": "All events supported except for the group open/close events. Track <a href=\"https://github.com/FlowFuse/node-red-dashboard/issues/406\" target=\"blank\">#406 progress here</a>."
         }
     ]
 }