Skip to content

Commit 48cbbf6

Browse files
joepavittjoepavitt
authored
Merge pull request #408 from FlowFuse/258-ui-control
Widget: UI Control
2 parents 35017c3 + fa10cb8 commit 48cbbf6

File tree

35 files changed

+986
-69
lines changed

35 files changed

+986
-69
lines changed

‎docs/.vitepress/config.js‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -81,6 +81,7 @@ export default ({ mode }) => {
8181
collapsed: false,
8282
items: [
8383
{ text: 'ui-button', link: '/nodes/widgets/ui-button' },
84+
{ text: 'ui-control', link: '/nodes/widgets/ui-control' },
8485
{ text: 'ui-chart', link: '/nodes/widgets/ui-chart' },
8586
{ text: 'ui-dropdown', link: '/nodes/widgets/ui-dropdown' },
8687
{ text: 'ui-event', link: '/nodes/widgets/ui-event' },

‎docs/components/AddedIn.vue‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
<template>
2+
<a class="added-in" :href="'https://github.com/FlowFuse/node-red-dashboard/releases/tag/v' + version" target="_blank">Added In: v{{ version }}</a>
3+
</template>
4+
5+
<script>
6+
export default {
7+
name: 'AddedIn',
8+
props: {
9+
version: {
10+
type: String,
11+
required: true
12+
}
13+
}
14+
}
15+
</script>
16+
17+
<style scoped>
18+
.added-in {
19+
display: inline-flex;
20+
font-size: 14px;
21+
line-height: 20px;
22+
padding: 3px 9px;
23+
color: var(--vp-c-brand-1);
24+
margin-left: 0.5em;
25+
border-radius: 2rem;
26+
background-color: var(--vp-c-brand-soft);
27+
border: 1px solid var(--vp-c-brand-1);
28+
text-decoration: none;
29+
transition: none;
30+
vertical-align: middle;
31+
}
32+
33+
.added-in:hover {
34+
background-color: var(--vp-c-brand-1);
35+
color: #fff;
36+
}
37+
</style>

‎docs/contributing/widgets/third-party.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,8 @@
1-
# Building Third Party Widgets
1+
<script setup>
2+
import AddedIn from '../../components/AddedIn.vue'
3+
</script>
4+
5+
# Building Third Party Widgets <AddedIn version="0.8.0" />
26

37
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.
48

‎docs/layouts/notebook.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,8 @@
1-
# Layout: Notebook
1+
<script setup>
2+
import AddedIn from '../components/AddedIn.vue'
3+
</script>
4+
5+
# Layout: Notebook <AddedIn version="0.4.0" />
26

37
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.
48

‎docs/nodes/widgets/ui-control.md‎

Lines changed: 157 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,157 @@
1+
---
2+
{
3+
"events": [
4+
{
5+
"event": "$pageview",
6+
"payload": "{ page }",
7+
"description": "Sent whenever a user <i>views</i> a given page on the Dashboard"
8+
},
9+
{
10+
"event": "$pageleave",
11+
"payload": "{ page }",
12+
"description": "Sent whenever a user <i>leaves</i> a given page on the Dashboard"
13+
}
14+
]
15+
}
16+
---
17+
18+
<script setup>
19+
import EventsList from '../../components/EventsList.vue'
20+
import AddedIn from '../../components/AddedIn.vue'
21+
</script>
22+
23+
# Control `ui-control` <AddedIn version="0.9.0" />
24+
25+
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.
26+
27+
Functionality is generally divided into two main features:
28+
29+
- **Navigation**: Force the user to move to a new page
30+
- **Display**: Show/Hide groups and pages
31+
- **Disability**: Enable/Disable groups and pages, this still shows them, but prevents interaction
32+
33+
## Controls List
34+
35+
Currently, we support the following controls:
36+
37+
### Navigation
38+
39+
You can programmaticaly force navigation with the following payloads with `ui-control`:
40+
41+
#### Change Page
42+
43+
Explicitely choose the page you want to navigate to:
44+
45+
```js
46+
// String
47+
msg.payload = '<Page Name>'
48+
49+
// Object
50+
msg.payload = {
51+
page: '<Page Name>',
52+
}
53+
```
54+
55+
#### Next/Previous
56+
57+
Navigate to the next or previous page in the list:
58+
59+
```js
60+
// Next Page
61+
msg.payload = "+1"
62+
63+
// Previous Page
64+
msg.payload = "-1"
65+
```
66+
67+
#### Refresh
68+
69+
You can force a refresh of the current view by sending a blank string payload:
70+
71+
```js
72+
msg.payload = ""
73+
```
74+
75+
### Show/Hide
76+
77+
You can programmaticaly show/hide groups and pages with the following payload into `ui-control`:
78+
79+
```js
80+
msg.payload = {
81+
pages: {
82+
show: ['<Page Name>', '<Page Name>'],
83+
hide: ['<Page Name>']
84+
}
85+
groups: {
86+
show: ['<Group Name>', '<Group Name>'],
87+
hide: ['<Group Name>']
88+
}
89+
}
90+
```
91+
92+
_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.
93+
94+
### Enable/Disable
95+
96+
You can programmaticaly disable/enable groups and pages with the following payload into `ui-control`:
97+
98+
```js
99+
msg.payload = {
100+
pages: {
101+
enable: ['<Page Name>', '<Page Name>'],
102+
disable: ['<Page Name>']
103+
}
104+
groups: {
105+
enable: ['<Group Name>', '<Group Name>'],
106+
disable: ['<Group Name>']
107+
}
108+
}
109+
```
110+
111+
_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.
112+
113+
## Events List
114+
115+
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.
116+
117+
### Connection Status
118+
119+
We follow the Dashboard 1.0 convention for emitting socket-based events from the `ui-control` node.
120+
121+
#### .on('connection')
122+
123+
When a new Dashboard client connects to Node-RED, the `ui-control` node will emit:
124+
125+
```js
126+
msg = {
127+
payload: 'connect',
128+
socketid: '<socketid>',
129+
socketip: '<socketip>'
130+
}
131+
```
132+
133+
#### .on('disconnect')
134+
135+
When a Dashboard client disconnects from Node-RED, the `ui-control` node will emit:
136+
137+
```js
138+
msg = {
139+
payload: 'lost',
140+
socketid: '<socketid>',
141+
socketip: '<socketip>'
142+
}
143+
```
144+
145+
### Change Tab/Page
146+
147+
When a user changes the active tab or page, the `ui-control` node will emit:
148+
149+
```js
150+
msg = {
151+
payload: 'change',
152+
socketid: '<socketid>',
153+
socketip: '<socketip>',
154+
tab: '<Page Index>',
155+
name: '<Page Name>'
156+
}
157+
```

‎docs/nodes/widgets/ui-event.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,9 +17,10 @@
1717

1818
<script setup>
1919
import EventsList from '../../components/EventsList.vue'
20+
import AddedIn from '../../components/AddedIn.vue'
2021
</script>
2122

22-
# Event `ui-event`
23+
# Event `ui-event` <AddedIn version="0.9.0" />
2324

2425
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.
2526

@@ -36,6 +37,8 @@ Each time a user views a page, the `ui-event` node will emit:
3637
```js
3738
msg = {
3839
topic: '$pageview',
40+
socketid: '1234',
41+
socketip: '127.0.0.1'
3942
payload: {
4043
page: {
4144
name: 'Page Name',

‎docs/nodes/widgets/ui-markdown.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ props:
55
---
66

77
<script setup>
8+
import AddedIn from '../../components/AddedIn.vue'
89
</script>
910

1011
# Markdown Viewer `ui-markdown`
@@ -70,7 +71,7 @@ function () {
7071
| `msg.payload` | {{ msg.payload || 'Placeholder' }} |
7172
````
7273

73-
## Mermaid Charts
74+
## Mermaid Charts <AddedIn version="0.5.0" />
7475

7576
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:
7677

‎docs/nodes/widgets/ui-notification.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,11 @@ props:
1010
Class: Appends CSS classes to the widget
1111
---
1212

13-
# Notification `ui-notification`
13+
<script setup>
14+
import AddedIn from '../../components/AddedIn.vue'
15+
</script>
16+
17+
# Notification `ui-notification` <AddedIn version="0.5.0" />
1418

1519
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`).
1620

‎docs/nodes/widgets/ui-table.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,9 +9,10 @@ props:
99
---
1010

1111
<script setup>
12+
import AddedIn from '../../components/AddedIn.vue'
1213
</script>
1314

14-
# Data Table `ui-table`
15+
# Data Table `ui-table` <AddedIn version="0.4.0" />
1516

1617
Renders a set of data in a tabular format. Expects an input (`msg.payload`) in the format of:
1718

‎docs/user/migration.md‎

Lines changed: 12 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@
44

55
import uiButton from './migration/ui_button.json'
66
import uiChart from './migration/ui_chart.json'
7+
import uiControl from './migration/ui_control.json'
78
import uiDropdown from './migration/ui_dropdown.json'
89
import uiForm from './migration/ui_form.json'
910
import uiSlider from './migration/ui_slider.json'
@@ -16,6 +17,7 @@
1617
const widgets = ref({
1718
'ui_button': uiButton,
1819
'ui_chart': uiChart,
20+
'ui_control': uiControl,
1921
'ui_dropdown': uiDropdown,
2022
'ui_form': uiForm,
2123
'ui_slider': uiSlider,
@@ -140,6 +142,16 @@ is currently _not_ supported. If this is of particular importance, please do voi
140142

141143
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"_
142144

145+
### `ui_control`
146+
147+
<MigrationWidgetProfile :profile="widgets['ui_control']" />
148+
149+
#### Controls List
150+
151+
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.
152+
153+
You can see detailed documentation of the available controls, and emitted events [here](/nodes/widgets/ui-control.html).
154+
143155
### `ui_date_picker`
144156

145157
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
198210
<MigrationWidgetProfile :profile="widgets['ui_toast']" />
199211

200212

201-
### `ui_control`
202-
203-
<MigrationWidgetProfile :profile="widgets['ui_control']" />
204-
205-
Track progress, and input ideas here: [UI Control #258](https://github.com/FlowFuse/node-red-dashboard/issues/258).
206-
207-
208213
## Theming
209214

210215
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.

0 commit comments

Comments
 (0)