node-red-contrib-uibuilder/nodes/uibuilder/locales/en-US/uibuilder.html

Easily create data-driven web UI's for Node-RED. Single- & Multi-page. Multiple UI's. Work with existing web development workflows or mix and match with no-code/low-code features.

<script type="text/html" data-help-name="uibuilder">  
    <p>
        Provides a stand-alone web server that allows for interfacing with Node-RED, while giving you help and complete freedom to create custom web interfaces.<br><br>

        You need at least one of these in order to make full use of all of <span class="uib-name"><span class="uib-red">UI</span>BUILDER</span>'s features.
    </p><p>
        It is this node that creates a custom web server. You can have many nodes if that best meets your needs. But each node can serve many pages.
    </p><p>
        It also creates a set of filing system folders and files on the Node-RED server. 
        These define the front-end UI you see in the browser as well as providing some important configuration.
    </p><p>
        This node is also where you configure much of UIBUILDER's web server such as installing helper libraries that 
        you may wish to use to support your interfaces (e.g. VueJS, jQuery, etc). You can also use it to edit your custom UI code.
    </p>

    <p id="uib_help_docs">
        Detailed documentation can be found <a href="./uibuilder/docs" target="_blank">HERE</a>.
    </p>

    <p>
        More information on how to configure this node: <a href="./uibuilder/docs/#/nodes/uibuilder" target="_blank">UIBUILDER node configuration</a>.
    </p>

    <p>
        Specific information on how to use the front-end library: <a href="./uibuilder/docs/#/uibuilder.module" target="_blank">Client Library</a>. 
    </p>

    <h3>Status display</h3>
    <p>
        Each instance (node) of UIBUILDER has a status display. Normally, the icon is blue.
        When 1 or more clients are connected, the text will show how many clients are connected.
    </p>

    <h3>Inputs</h3>
    <dl class="message-properties">
        <dt class="optional">payload <span class="property-type">string | buffer</span></dt>
        <dd> Optionally, the payload of the message to send to all connected client browser tabs. </dd>

        <dt class="optional">_uib <span class="property-type">object</span></dt>
        <dd>
            Optionally, trigger low-code front-end events such as 
            <a href="./uibuilder/docs/#/pre-defined-msgs?id=ui-notification-toast-control-message-partially-deprecated-in-v51" target="_blank">showing a notification message</a>.
            Also used to <a href="uibuilder/docs/#/pre-defined-msgs?id=browser-client-reload-page" target="_blank">
            signal to the front-end that the page should reload automatically</a>. Useful when developing front-end code via the node's editor.
        </dd>

        <dt class="optional">topic <span class="property-type">string</span></dt>
        <dd> Optionally, the MQTT topic to use. Takes preference over the topic defined in settings.</dd>
    </dl>

    <h3>Outputs</h3>
    <ol class="node-ports">

        <li>Standard output (data from front-end)
            <dl class="message-properties">
                <dt class="optional">payload <span class="property-type">string | buffer</span></dt>
                <dd>
                    Typical data sent by the client.
                </dd>

                <dt class="optional">uibDomEvent <span class="property-type">object</span></dt>
                <dd>
                    Used by the <code>uibuilder.eventSend()</code> front-end function. 
                    See the <a href="./uibuilder/docs/#/client-docs/features?id=eventsend-function" target="_blank">eventSend feature in the documentation</a> for specifics.
                </dd>
        
                <dt>topic <span class="property-type">string</span></dt>
                <dd>
                    A copy of the last inbound topic if present. Otherwise, the topic from the node's settings. 
                    Could also be changed by the front-end.
                </dd>

                <dt class="optional">_uib <span class="property-type">string</span></dt>
                <dd>
                    Included only if turned on in advanced settings.
                    Provides detailed information about the sending client.
                    Useful for custom security processing.<br><br>
                    See the control output below for more specifics.
                </dd>

                <dt>other</dt>
                <dd>
                    The client may send other data on the <code>msg</code> object.
                </dd>
            </dl>
            <p>
                Note that input messages are not forwarded to the output unless the flag is set in the advanced settings.
            </p>
        </li>

        <li>Control output (controls from front-end or server)
            <dl class="message-properties">
                <dt>uibuilderCtrl <span class="property-type">string</span></dt>
                <dd>
                    The name/id of the control message. 
                    See the <a href="./uibuilder/docs/#/pre-defined-msg" target="_blank">documentation</a> for details.
                </dd>

                <dt>cacheControl <span class="property-type">string</span></dt>
                <dd>
                    Use in your flow to control the sending or clearing of a cache of messages to be sent to new/refreshed clients.<br>
                    This requires a separate function node to capture and replay inbound messages.
                    <table>
                        <tr><th>REPLAY</th> <td>Indicate to the back-end flow that a copy of the cached messages should be dumped to the front-end. Retaining the <code>_socket.id</code> will send the cache contents back to the requesting client.<hr></td></tr>
                        <tr><th>CLEAR</th> <td>Indicate to the back-end flow that any cache should be completely cleared for everyone.</td></tr>
                    </table>
                    See the <a href="./uibuilder/docs/#/pre-defined-msg" target="_blank">documentation</a> for details.
                </dd>

                <dt>from <span class="property-type">string</span></dt>
                <dd>
                    Identifies the source of the msg since both <i>server</i> (back-end) and <i>client</i> (front-end) control messages
                    will appear out of port #2.
                </dd>

                <dt>Other <span class="property-type">string</span></dt>
                <dd>
                    Additional details about the client the message relates to is included.
                    This varies somewhat between the different control message types.
                    See <a href="./uibuilder/docs/#/pre-defined-msg" target="_blank">the documentation</a> for more details.
                </dd>
            </dl>
        </li>

    </ol>

    <h3>Node Settings</h3>
        <dl class="message-properties">
            <dt>Name <span class="property-type">string</span></dt>
            <dd>A short description shown in the admin interface</dd>

            <dt>Topic <span class="property-type">string</span></dt>
            <dd>A topic name to use if the incoming msg does not contain one.</dd>

            <dt>URL <span class="property-type">string</span></dt>
            <dd>
                There is no default and this entry is required.<br>
                The URL path that the resulting page and other resources will be served from.
                Must be unique across Node-RED. Will also use the Node-RED scheme (http/https)
                and port or the custom UIBUILDER scheme and port if specified in settings.js. 
                Will also be prefixed by the Node-RED setting <i>httpNodeRoot</i>.<br>
                The url is also used to define the server filing system path for front-end code files.<br>
                The url must be valid as a filename as well as a url path. It may not exceed 20 characters.
            </dd>

            <h4>Files tab</h4>
            <p>
                Clicking this tab will display a file editor allowing you
                to edit the front-end files that define your user interface.<br />
                All text-based files in the <code>&lt;uibRoot>/&lt;url>/</code> folder on the server's filing system will
                be available to edit.
                <p>
                    Note that you can expand the edit panel by clicking on the <kbd class="help-key">&#x2921;</kbd> arrow button underneath the panel.
                    To exit fullscreen, press the same button (now highlighted) or the <kbd class="help-key">Esc</kbd> key.
                </p>
            </p>
        </dl>

        <h4>Template Settings</h4>
        <dl class="message-properties">
            <dt>Template <span class="property-type">drop-down</span></dt>
            <dd>
                Select one of the built-in templates or load an external template.
            </dd>

            <dt>Ext. Template <span class="property-type">text</span></dt>
            <dd>
                Only if "Load an external template using Degit" is selected.
                <a href="https://github.com/Rich-Harris/degit" target="_blank">Degit</a> is used to load a template from an external <code>git</code> repository.<br>
                Try "totallyinformation/uib-template-test" as an example.
            </dd>

            <dt>Load & Overwrite <span class="property-type">button</span></dt>
            <dd>
                Clicking the button will display a warning dialog. If you accept the warning, 
                all of your current front-end code will be replaced with the template.
            </dd>
        </dl>

        <h4>Libraries tab</h4>
        <p>
            Clicking this tab will display a list of currently available
            front-end library packages. This interface allows you to add, remove and update any library
            that can be installed via <a href="https://www.npmjs.com/" target="_blank">npm</a>.<br>
            Libraries will be loaded into your <code>&lt;userDir>/</code> folder in the same place as custom nodes.
            UIBUILDER retains an internal list of front-end libraries loaded this way.
            Each library will be served so that you can use it in your front-end html.
        </p>

        <h4>Advanced tab</h4>
        <dl class="message-properties">
            <dt>Serve <span class="property-type">drop-down</span></dt>
            <dd>
                Choose which folder to serve files from. Only <code>src</code> and <code>dist</code> are available at the moment.
                This can now be changed simply by redeploying your flow, you don't need to restart Node-RED.
            </dd>

            <dt>Include <code>msg._uib</code> in standard msg output <span class="property-type">check box</span></dt>
            <dd>
                If selected, will show the browser clientId, page name and real IP address in standard output (it is always shown in control msgs).
            </dd>

            <dt>Description input boxes</dt>
            <dd>
                The short & long descriptions are used in both the <i>UIBUILDER apps page</i> and the <a href="./uibuilder/uibindex" target="_blank">Detailed Information page</a>.
            </dd>

            <dt>Code editor URL</dt>
            <dd>
                By default, this will contain UIBUILDERs best guess at a custom URL that allows editing of your front-end code files.
            </dd>
            <dd>
                UIBUILDER only knows about VSCode's URL schema.
            </dd>
            <dd>
                This will be correct if editing code on the same device as Node-RED. 
                If Node-RED is running on another device, it will be a guess of the VSCode remote edit URL.
            </dd>
            <dd>
                Change as needed for your editor and/or configuration.
            </dd>

            <dt>Forward input to output? <span class="property-type">check box</span></dt>
            <dd>
                Forwards a copy of every received message direct to the output.
                Adds the topic from the above setting if one isn't present in the msg.
                <p>
                    <i>Note</i> that this may result in multiple output messages if your front-end
                    code also auto-sends inbound messages.
                </p>
            </dd>
        </dl>

        <h4>Button Row</h4>
        <dl class="message-properties">
            <dt><i class="fa fa-globe" aria-hidden="true"></i> Open <span class="property-type">link</span></dt>
            <dd>
                The web app url for this instance. Click to see the app page in a new tab.
                Also available as a button at the top of the panel on all tabs.
            </dd>

            <dt><i class="fa fa-info-circle" aria-hidden="true"></i> Full details <span class="property-type">link</span></dt>
            <dd>
                Shows the <a href="./uibuilder/uibindex" target="_blank">Detailed Information page</a>.
                That includes details of all uibuilder instance apps, of the vendor modules that are
                available, and all of the UIBUILDER endpoints along with both server
                and URL paths.
            </dd>

            <dt><i class="fa fa-info" aria-hidden="true"></i> Node Details <span class="property-type">link</span></dt>
            <dd>
                Shows a web page with detailed information relavent just for this
                instance (node) of UIBUILDER. May be easier to read than the full details.
            </dd>

            <dt><i class="fa fa-book" aria-hidden="true"></i> Docs <span class="property-type">link</span></dt>
            <dd>
                Opens the documentation for UIBUILDER in a separate tab.
                This does not require an Internet connection, the local docs are used.
                Also available as a button at the top of the panel on all tabs.
            </dd>

        </dl>

    <h3>File/Folder Structure</h3>
    <p>
        For more information, see the <a href="./uibuilder/docs" target="_blank">UIBUILDER documentation</a>.
    </p>


    <h3>Details</h3>
    <p>
        For more information, see the <a href="./uibuilder/docs" target="_blank">UIBUILDER documentation</a>.
    </p>
    <p>
        There are also examples of how to use UIBUILDER in the Node-RED import library, on the <a href="https://flows.nodered.org/search?term=uibuilder" target="_blank"></a>, and in the <a href="https://github.com/TotallyInformation/node-red-contrib-uibuilder/wiki" target="_blank">GitHub WIKI</a>.
    </p>
    <p>
        UIBUILDER can be discussed in the <a href="https://discourse.nodered.org/tag/node-red-contrib-uibuilder" target="_blank">Node-RED Forum</a>. Issues/bugs can be raised on <a href="https://github.com/TotallyInformation/node-red-contrib-uibuilder/issues" target="_blank">GitHub</a>.
    </p>

    <h3>Admin Index (Details) page</h3>
    <p>
        The <a href="./uibuilder/uibindex" target="_blank">&lt;admin url&gt;/uibindex</a> page lists all of the UIBUILDER endpoints and other details. You can use the following parameters:
    </p>
    <dl class="message-properties">
        <dt>type</dt>
        <dd>
            The type of data returned:
            <dl class="message-properties">
                <dt><a href="./uibuilder/uibindex?type=html" target="_blank">html</a> <span class="property-type">(default)</span></dt>
                <dd>
                    Also used if no type parameter is given. 
                    Returns an HTML page showing the details for all deployed UIBUILDER nodes.
                    Shows the server file locations of the instance and for vendor libraries.
                </dd>
                <dt><a href="./uibuilder/uibindex?type=json" target="_blank">json</a></dt>
                <dd>
                    Returns JSON data with both the source node ID's and matching URL's.
                </dd>
                <dt><a href="./uibuilder/uibindex?type=urls" target="_blank">urls</a></dt>
                <dd>
                    Returns a JSON array of just the URL's in use from deployed UIBUILDER nodes.
                    Used internally to ensure that new nodes use unique url's.
                </dd>
            </dl>
        </dd>
    </dl>
    <ul>
    </ul>
</script>