fbDialog

Updated pdexter 2025-11-18

Formbird Dialog provides functions for presenting dialogs to the Formbird application.

The following functions are intended to replace use of the ruleset include "SweetAlert Dialog", with its dependence on the 3rd party SweetAlert library (older version). It endeavours to meet most of the functionality that we use from SweetAlert, much of which is unused.

There is also no dependence on or relation to the ntf.scope.ModalService object.

This library is built on the native dialog element of html, using JQuery, so there is no dependence on 3rd party libraries (apart from JQuery).

Caveat Due to over complexity, I've omitted the "attended" flag and the "dialog stacking" for unattended dialogs, ie, where if multiple simple dialogs were opened in code sequentially, they ran unattended (ie the ruleset continued to run), but would be opened from a stack of configurations one after the other, rather than the last gazumping all previous dialogs.

It now relies on coders using await to open dialogs, for the code to stop until the dialog is closed.

To use

Be sure that the ruleset include document "Formbird Dialog" is installed on your environment.

Insert the following line at the top of your ruleset

#include "Formbird Dialog",

If this is not available, look for the package "Formbird Ruleset Includes" on My Metadata Releases Listing and install to your environment.

Simple Usage

The following functions can be used to do quick message boxes

Syntax

To wait for the dialog to complete await ft3.fbDialog.showDialogSimple(ntf, title, text, type)

To set and forget, omit the await keyword ft3.fbDialog.showDialogSimple(ntf, title, text, type)

With set and forget mode above, code will continue to run once the dialog is opened, and not wait for it to be closed. A caveat is, if a subsequent call is made to any dialog function, the first dialog will be replaced, perhaps not even visibly showing. If a sequence of dialogs needs to be displayed, use await for the code to wait for each to be closed. The function is coded to suspend the timeout of the ruleset and to restore again once it is closed.

Type "wait" will display an hour glass icon; intended to display while a long running process is in progress. If type is omitted, then no icon is displayed.

Example

await ft3.fbDialog.showDialogSimple(ntf, 'Sample Title', 'Hey how goes, fbDialog (info)!!', 'info');

Full Usage

The following function can be used for more complicated dialogs.

Syntax

[await] ft3.fbDialog.showDialog(ntf, options);

If used with "await", code will stop until the dialog has been closed.

Options

options is an object containing the following items:

Showing a progress dialog

For showing a progressive dialog showing that something is occurring "in the background".

Syntax

ft3.fbDialog.showProgress(ntf, title, text, stopFunction );

WARNING: Do not call with await.

Example

var stopFlag = false;
const stopF = () => {stopFlag = true};

for (var i=0; i<38; i++) {
    ft3.fbDialog.showProgress(ntf, 'Progressing Test', `Showing progress ${i}/38`, i, 38, stopF);
    await ft3.sleep(300);

    if (stopFlag) break;
}
if (stopFlag) {
    ft3.fbDialog.showDialogSimple(ntf, 'Progress Test', 'Progress cancelled', 'error');
}
else {
    ft3.fbDialog.showDialogSimple(ntf, 'Progress Test', 'Progress done!!', 'success');    
}

Examples

Simple dialogs

// No title, no icon
await ft3.fbDialog.showDialogSimple(ntf, '', 'Hey how goes, fbDialog!!');

// No icon
await ft3.fbDialog.showDialogSimple(ntf, 'Sample Title', 'Hey how goes, fbDialog!!');

// Info
await ft3.fbDialog.showDialogSimple(ntf, 'Sample Title', 'Hey how goes, fbDialog (info)!!', 'info');

// Question
await ft3.fbDialog.showDialogSimple(ntf, 'Sample Title', 'Hey how goes, fbDialog (question)!!', 'question');

// Warning
await ft3.fbDialog.showDialogSimple(ntf, 'Sample Title', 'Hey how goes, fbDialog (warn)!!', 'warning');

// Success
await ft3.fbDialog.showDialogSimple(ntf, 'Sample Title', 'Hey how goes, fbDialog (success)!!', 'success');

// Error
await ft3.fbDialog.showDialogSimple(ntf, 'Sample Title', 'Hey how goes, fbDialog (error)!!', 'error');

Confirm, OK or Cancel

Returns true for OK, false for Cancel

var response = await ft3.fbDialog.showDialog(ntf, {
    title : 'Confirm Dialog Test FBD',
    html : `<font color="Red">aaa</font> testing html`,
    type : 'info',
    showCancelButton : true,
    cancelButtonColor : 'Red'
});
ntf.logger.info(`response: ${response}`);  
// response: true     // if ok clicked
// response: false    // if cancel clicked

Get text input

Returns the text input if OK clicked, otherwise false.

var response = await ft3.fbDialog.showDialog(ntf, {
    title : 'Input Test FBD',
    html : `<font color="Red">aaa</font> testing html`,
    type : 'question',
    input : 'text',
    inputPlaceholder : 'Enter some stuff',
    showCancelButton : true
});
ntf.logger.info(`response: ${response}`);
// "response: your-entered-text"

Get password

Returns the password entered if OK clicked, otherwise false.

var response = await ft3.fbDialog.showDialog(ntf, {
    title : 'Password Test FBD',
    text : `Enter your password`,
    type : 'question',
    input : 'password',
    showCancelButton : true,
    cancelButtonColor : 'Red'
});
ntf.logger.info(`response: ${response}`);
// response: your-entered-password

Pick from checklist of options

Returns an array of the checked items of the checklist if OK clicked, otherwise false

var response = await ft3.fbDialog.showDialog(ntf, {
    title : 'Checkbox Test FBD',
    html : `Select the items you want:`,
    type : 'question',
    input : 'checklist',
    inputOptions : ['Do the thing', 'Lorem ipsum dolor sit amet',"Don't do the thing"],
    showCancelButton : true,
    cancelButtonColor : 'Red'
});
ntf.logger.info(`response: ${JSON.stringify(response)}`);
// response: ["Do the thing", "Lorem ipsum dolor sit amet"]

Pick from a radiolist of options

Returns the text value of the item selected if OK clicked, otherwise false

var response = await ft3.fbDialog.showDialog(ntf, {
    title : 'Radiolist Test FBD',
    html : `Choose which colour you want:`,
    type : 'question',
    input : 'radiolist',
    inputOptions : 'Red,Orange,Yellow,Green,Blue,Indigo'.split(','),
    showCancelButton : true,
    cancelButtonColor : 'Red'
});
ntf.logger.info(`response: ${JSON.stringify(response)}`);
// response: "Orange"

Add extra buttons

Returns the button id (eg value of "customButton1") of the clicked button.

var response = await ft3.fbDialog.showDialog(ntf, {
    title : 'More button Test FBD',
    html : `<font color="Red">aaa</font> testing html`,
    type : 'question',

    customButton1 : 'denyAction',
    customButton1Text : 'Deny Action',
    customButton1Color : '#880000',

    customButton2 : 'confirmAction',
    customButton2Text : 'Confirm Action',
    customButton2Color : 'Green',

    showCancelButton : true,
});
ntf.logger.info(`response: ${JSON.stringify(response)}`);
// response: "denyAction"

Showing Progress Dialog

No return value (or irrelevant).

var stopFlag = false;
// Make stop function
const stopF = () => {stopFlag = true};

for (var i=0; i<38; i++) {
    ft3.fbDialog.showProgress(ntf, 'Progressing Test', `Showing progress ${i}/38`, i, 38, stopF);
    await ft3.sleep(10); // May need this to repaint dialog

    // Do heavy processing here 
    await ft3.sleep(2000);  // test loading only

    if (stopFlag) break;    
}

if (stopFlag) {
    ntf.logger.info('Progress cancelled :(');
}
else {
    ntf.logger.info('Progress done!! :)');    
}

Migrating from SweetAlert Dialog

It has been endeavoured to keep the use of this dialog function simpler than that of the SweetAlert dialog functions, where a number of complex usages crept in.

Therefore there is not a one to one replacement of the functions for SweetAlert. There needs be a conscious replacement of each call to SweetAlert.

ntf passing

Most functions require "ntf" to now be passed as the first argument.

eg

ft3.dialog('title', 'here is the text', 'info')

becomes

await ft3.fbDialog.showDialogSimple(ntf, 'title', 'here is the text', 'info');

Synchronous vs Asynchronous

The functions in Formbird Dialog run synchronously or asynchronously depending on whether they are called with await

eg

ft3.fbDialog.showDialogSimple(ntf, 'title', 'here is the text', 'info');
ntf.logger.info('This line will run while the dialog is still open.');

vs

await ft3.fbDialog.showDialogSimple(ntf, 'title', 'here is the text', 'info');
ntf.logger.info('This line will run after the dialog is closed.');