Control ui-control Added In: v0.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 programmatically force navigation with the following payloads with ui-control:

Change Page

Explicitly choose the page you want to navigate to:

// String
msg.payload = '<Page Name>'

// Object
msg.payload = {
    page: '<Page Name>',
}

With the object format, you can also specify query parameters with which to load the page:

msg.payload = {
    page: '<Page Name>',
    query: {
        hello: 'world'
    }
}

Which would navigate to a page with ?hello=world appended to the URL.

Next/Previous

Navigate to the next or previous page in the list:

// 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:

msg.payload = ""

External URL

If you want to trigger navigation to an external resource or website, you can do so by passing a url property into the msg.payload, e.g:

msg.payload = {
    url: 'https://nodered.org'
}

You can also specify a target property to open the website in a new browser window or tab.

msg.payload = {
    url: 'https://nodered.org',
    target: '_blank'
}

Show/Hide

You can programmatically show/hide groups and pages with the following payload into ui-control:

msg.payload = {
    pages: {
        show: ['<Page Name>',
               '<Page Id>'
               {page: '<Page Name>'},
               {page: '<Page Id>'}],
        hide: ['<Page Id>']
    },
    groups: {
        show: ['<Group Name>',
               '<Group Id>'
               '<Page Name>:<Group Name>',
               '<Page Id>:<Group Name>',
               {group: '<Group Name>'},
               {group: '<Group Id>'},
               {page: '<Page Name>', group: '<Group Name>'},
               {page: '<Page Id>', group: '<Group Name>'}],
        hide: ['<Group Id>']
    }
}

Note: pages can be subbed with tabs as per Node-RED Dashboard and groups can also be subbed with group as per Node-RED Dashboard.

Enable/Disable

You can programmatically disable/enable groups and pages with the following payload into ui-control:

msg.payload = {
    pages: {
        enable: ['<Page Id>''],
        disable: ['<Page Id>']
    },
    groups: {
        enable: ['<Group Id>'],
        disable: ['<Group Id>']
    },
    widgets: {
        enable: ['<Widget Id>'],
        disable: ['<Widget Id>']
    }
}

Note: pages can be subbed with tabs as per Node-RED Dashboard and groups can also be subbed with group as per Node-RED Dashboard.

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 Node-RED Dashboard here too.

Connection Status

We follow the Node-RED Dashboard 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:

msg = {
    payload: 'connect',
    socketid: '<socketid>',
    socketip: '<socketip>'
}

.on('disconnect')

When a Dashboard client disconnects from Node-RED, the ui-control node will emit:

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:

msg = {
    payload: 'change',
    socketid: '<socketid>',
    socketip: '<socketip>',
    tab: '<Page Index>',
    name: '<Page Name>'
}