Getting Started

Update 2022-01-19: This page requires updating. Please check out the more detailed information available in the Tech docs either here on GitHub pages or via the link in any uibuilder node.

The basics

When you install this node and add it to a flow, you get a new web page created. By default, that is at the url /uibuilder.

The page that is created is illustrating quite a lot. Mainly that you get access to messages sent from Node-RED and can send messages back as well. You don't need to reload the page to see those messages. But you do need to do something to make those messages appear on the page. The default template uses VueJS to do all the dynamic page updates with minimal coding from yourself. All you need to do is link anything coming in from Node-RED to a VueJS variable then whenever you get a new message, the web page updates. That's it!

If you haven't made any changes, open up your browser's developer console by pressing key F12. Look for the "console" and you will see the message objects listed along with some other information that lets you know what is happening.

Extending the basic example

Of course, the default page isn't much use to you so you now need to start creating your own page.

To do that, you can edit the code that is already provided using the code editor built right into uibuilder.

The default files are index.html, index.css and index.js, if you delete them, they will reappear having been copied over from a master template folder. If you don't want that, you can turn it off using a switch that is hidden in the "Advanced Settings" section of the configuration panel.

You can create other pages and even sub-folders (though there is no editor for sub-folders as yet) to use for your web app.

Using a different front-end library

As you progress, you might find that you want to play with some additional front-end libraries like RiotJS, REACT. This is possible too. All you need to do is to open the configuration panel for any uibuilder node and click on the "Manage front end libraries" button. Then click "Add" and type in the name of an npm package such as react, click install and wait for the notification that it worked - that can take quite a while with some packages.

Finally, change your .html files to use the new library.

None of this requires a restart of Node-RED.

Debugging

The debug setting lets you get at detailed logs of what is happening on the server when you use uibuilder. A log file is created at ~/.node-red/uibuilder.log.

In addition, the front-end also has additional logging and you can turn that on manually from within your own code with uibuilder.debug(true) or you can turn it on from the setting in each node instance in the Node-RED admin UI.

A note on locations

As always, ~/.node-red is shorthand for the folder containing the "userDir" for the user running Node-RED. This may be different if you have changed it in the startup command for running Node-RED.

You will see references to <uibRoot> elsewhere in the documentation. This refers to the home folder for uibuilder. That folder contains sub-folders for each instance of uibuilder you have deployed as well as common and configuration folders. Normally, uibRoot will be located at ~/.node-red/uibuilder unless you are using Node-RED's projects feature in which case it will normally be located at ~/.node-red/projects/<currentProjectName>/uibuilder.

Where next?

Now you know the basics and should have a working example. There are a number of different examples in this WIKI. These will help you explore some other popular, lightweight, front-end libraries such as MoonJS and Riot. They will also give you an insight to some of the things you need to deal with and how to do so.

The How To pages in this WIKI cover a number of specific challenges such as making sure new/reloaded client connections get a basic set of data from the server, creating a mobile browser app, sending messages from Node-RED to a specific client and so on.