gDialog

Display macOS dialogs from Node.js projects, terminal and scripts, capable of displaying advanced dialogs and forms using the different templates.

gDialog is using the system color scheme, if the Mac has Dark Mode turned on, the background will be dark, if Dark Mode is turned off, the background will be bright. | Light Mode | Dark Mode | | --- | --- | | | |

Supported on:

• macOS Catalina (10.15.x)
• macOS Big Sur (11.x) - Intel or M1 with Rosetta

Current Status

gDialog is available as a Node.js module and as a standalone application.

Installing gDialog

Install the gDialog package with the command:

npm install -P gdialog

NOTE: If you have spaces in the project's folder path, node-gyp's build will fail.

Usage

gDialog requires an options object, if the options object is not provided, gDialog will attempt to parse the command line arguments as the described in the standalone application.
The options object must contain a type key/value with the name of the template, if the buttons key is not provided, an "OK" button will be added by default.
gDialog can be called in the following formats:

• Synchronous - Waits for the dialog to be closed before returning

const gDialog = require('gdialog');
let options = {
    type: 'msgbox',
    title: 'Dialog Title',
    header: 'Dialog Header',
    text: 'Dialog Text',
    icon_file: '/path/to/logo.png',
    buttons: [ 'OK', 'Cancel' ],
    focus: true
};
const dialog = new gDialog();
console.log(dialog.runSync(options));

• Asynchronous - Returns a promise

const gDialog = require('gdialog');
let options = {
    type: 'msgbox',
    title: 'Dialog Title',
    header: 'Dialog Header',
    text: 'Dialog Text',
    icon_file: '/path/to/logo.png',
    buttons: [ 'OK', 'Cancel' ],
    focus: true
};
const dialog = new gDialog();
dialog.run(options).then(result => {
    console.log("Run Result:", result);
}).catch(err => {
    console.log("Run Error:", err);
});

• Asynchronous with callback - All dialog interactions will be routed to the callback function, dialog will remain open until explicitly closed

const gDialog = require('gdialog');
function dialogCallback(returnString) {
    console.log("Callback:", returnString);
    dialog.close();
}
let options = {
    type: 'msgbox',
    title: 'Dialog Title',
    header: 'Dialog Header',
    text: 'Dialog Text',
    icon_file: '/path/to/logo.png',
    buttons: [ 'OK', 'Cancel' ],
    focus: true
};
const dialog = new gDialog();
dialog.setCallback(dialogCallback);
dialog.run(options).then(result => {
    console.log("Run Result:", result);
}).catch(err => {
    console.log("Run Error:", err);
});

Return Values / Output

The return values will be handled depends on which method gDialog was invoked with.
The return values will contain which button number was clicked (Right to Left) and each value will be separated by a new line "\n".

Table of Contents

• Global Options
• Message Box
• Input Box
• Secure Input Box
• Text Box
• Credentials Box
• HTML Box
• Progress Bar
• Picker Box
• File Select
• File Save
• Banner Box
• Notification

Global Options

| Key | Value (Example) | Description | | --- | --- | --- | | title | "Dialog Title" | Text for the dialog's title, if the title option is not provided, the title bar will not be displayed | | header | "Dialog Header" | Text for the dialog's header | | text | "Text" | Text for the dialog's main text area | | scrollable_text | true | In case of long text, allow the text box to have a (vertical) scrollbar instead of the text getting trimmed | | icon_file | "/path/to/logo.png" | Path to your logo image, the dialog will constraint the image to width of 75 pixels, for best results it is recommended to use a 75x75 pixels PNG image | | system_icon | "NSImageNameInfo" | Name of macOS's System Image to use, see full list of System Images at Apple's website, use the names in the "API" column | | width | 700 | Sets the width of the dialog window to 700 | | height | 350 | Sets the height of the dialog window to 350 | | window_size | "700x350" | Sets the size of the dialog window to 700x350 | | buttons | ["Yes", "No"] | Sets the dialog buttons from right to left. The buttons must be provided as an array | | allow_quit | true | Allows the user to close the dialog with CMD+Q, if the user closes the dialog with CMD+Q the dialog will return "-1" as the output | | no_return | false | Suppress the dialog's output text | | focus | true | Makes the dialog window take focus and become the active window | | timeout | 300 | Sets the dialog timeout to 300 seconds (5 minutes) | | static | true | Prevents the user from being able to move / drag the dialog window |

Message Box

Template Name is msgbox.
Displays a message box.

Command Example:

const gDialog = require('gdialog');
let options = {
    type: 'msgbox',
    title: 'Dialog Title',
    header: 'Dialog Header',
    text: 'Dialog Text',
    icon_file: '/path/to/logo.png',
    focus: true
};
const dialog = new gDialog();
console.log(dialog.runSync(options));

Input Box

Template Name is inputbox.
Displays an input box with one field.

Command Example:

const gDialog = require('gdialog');
let options = {
    type: 'inputbox',
    title: 'Title',
    header: 'Header',
    text: 'Enter your name:',
    background_text: 'Full Name',
    icon_file: '/path/to/logo.png',
    focus: true
};
const dialog = new gDialog();
console.log(dialog.runSync(options));

| Key | Value (Example) | Description | | --- | --- | --- | | background_text | "Background Text" | Background text for the input box | | initial_text | "Initial Text" | Initial text for the input box, can be used to prepopulate the inputbox with text | | encode_text | true | Encodes returned values in Base64 to ensure environments like Bash won't interpet special characters and combinations ("\n" for example) |

Secure Input Box

Template Name is secure-inputbox.
Displays an input box with one secured field, input is masked for use cases like passwords, output is still in plain text.

Command Example:

const gDialog = require('gdialog');
let options = {
    type: 'secure-inputbox',
    title: 'Title',
    header: 'Header',
    text: 'Enter your password:',
    icon_file: '/path/to/logo.png',
    focus: true
};
const dialog = new gDialog();
console.log(dialog.runSync(options));

| Key | Value (Example) | Description | | --- | --- | --- | | background_text | "Background Text" | Background text for the input box | | initial_text | "Initial Text" | Initial text for the input box, can be used to prepopulate the inputbox with text | | encode_text | true | Encodes returned values in Base64 to ensure environments like Bash won't interpet special characters and combinations ("\n" for example) |

Text Box

Template Name is textbox.
Displays a text box.

Command Example:

const gDialog = require('gdialog');
let options = {
    type: 'textbox',
    title: 'Dialog Title',
    header: 'Dialog Header',
    text: 'Do you agree to the T&C?',
    initial_text: 'Lorem ipsum dolor sit amet, ...lacinia. Cras.',
    icon_file: '/path/to/logo.png',
    window_size: '500x300',
    buttons: [ 'Agree', 'Cancel' ],
    focus: true
};
const dialog = new gDialog();
console.log(dialog.runSync(options));

| Key | Value (Example) | Description | | --- | --- | --- | | initial_text | "Initial Text" | Initial text for the text box, can be used to prepopulate the text box with text | | encode_text | true | Encodes returned values in Base64 to ensure environments like Bash won't interpet special characters and combinations ("\n" for example) |

Credentials Box

Template Name is credentialsbox.
Displays an input box with 2-3 fields, a plain input field, secured input field and an extra (optional) input field.

Command Example:

const gDialog = require('gdialog');
let options = {
    type: 'credentialsbox',
    title: 'Title',
    header: 'Header',
    text: 'Enter your corporate credentials:',
    icon_file: '/path/to/logo.png',
    focus: true
};
const dialog = new gDialog();
console.log(dialog.runSync(options));

| Key | Value (Example) | Description | | --- | --- | --- | | user_label | "First Field:" | First input field's label, defaults to "Username:" if option is not provided | | user_initial_text | "Initial Text" | Initial text for the first input field | | user_background_text | "Background Text" | Background text for the first input field, defaults to "Enter your username" if option is not provided | | pass_label | "Second Field:" | Second input field's label, defaults to "Password:" if option is not provided | | pass_initial_text | "Initial Text" | Initial text for the second input field | | pass_background_text | "Background Text" | Background text for the second input field, defaults to "Enter your password" if option is not provided | | extra_field_label | "Extra Field:" | Extra input field's label, if option is not provided, the extra field will not be shown | | extra_field_initial_text | "Initial Text" | Initial text for the extra input field | | extra_field_background_text | "Background Text" | Background text for the extra input field | | extra_field_secured | true | Toggles the extra input field from plain text to secured input field | | encode_text | true | Encodes returned values in Base64 to ensure environments like Bash won't interpet special characters and combinations ("\n" for example) |

HTML Box

Template Name is htmlbox.
Displays a window which allows to load HTML for advanced forms and GUI.
The following global options are not available in this template:
header, text, icon_file, system_icon, buttons and scrollable_text.

To return text from the dialog, use the javascript function print("text"). To close the dialog, use the javascript function quit().

Command Example:

const gDialog = require('gdialog');
let options = {
    type: 'htmlbox',
    title: 'gDialog',
    file: '/path/to/html_file.html',
    focus: true
};
const dialog = new gDialog();
console.log(dialog.runSync(options));

HTML Page Example:

<form action="" id="sampleForm">
 <h2>Hello World</h2>
 <label>Enter your name:</label>
 <input type="text" name="username">
 <button type="submit" id="btnSubmit">Submit</button>
</form>
<script type="text/javascript">
 var sampleForm = document.querySelector("#sampleForm");
 if (sampleForm) {
  sampleForm.addEventListener("submit", function(e) {
   e.preventDefault();
   var btnSubmit = document.getElementById("btnSubmit");
   btnSubmit.disabled = true;
   var jsonData = {};
   for (var pair of new FormData(this)) {
    jsonData[pair[0]] = pair[1];
   }
   print(JSON.stringify(jsonData));
   quit();
  });
 }
</script>

| Key | Value (Example) | Description | | --- | --- | --- | | html_b64 | "HTML file in Base64" | HTML page encoded in a Base64 string | | file | "/path/to/html_file.html" | Path to the HTML file | | base_path | "/path/to/folder" | Base path of the running HTML, useful when using dynamic links to local files and images | | url | "https://github.com/giladdarshan/gdialog" | Displays the provided URL | | kiosk | true | Displays the HTML dialog in a full screen kiosk mode, preventing the user from moving away or closing the dialog | | normal_window | true | Displays the HTML dialog as a normal window with a menu bar, quit/resize/minimize buttons and a dock icon |

Progress Bar

Template Name is progressbar.
Displays an indeterminate progress bar.
The following global options are not available in this template:
header, scrollable_text and buttons.
NOTE: Currently only the indeterminate progress bar is supported in the Node.js module.

Indeterminate Progress Bar Example:

const gDialog = require('gdialog');
let options = {
    type: 'progressbar',
    title: 'Attack',
    header: 'App Header',
    text: 'Attacking The Death Star',
    indeterminate: true,
    icon_file: '/path/to/logo.png',
    focus: true
};
const dialog = new gDialog();
dialog.run(options).then(result => {
    console.log("Run Result:", result);
}).catch(err => {
    console.log("Run Error:", err);
});
// Do Stuff
setTimeout(() => {dialog.close()}, 5000);

| Key | Value (Example) | Description | | --- | --- | --- | | indeterminate | true | Displays an indeterminate progress bar | | stoppable | true | Adds a "Stop" button to the progress bar |

Picker Box

Template Name is pickerbox.
Displays a dialog window with either a drop down menu (default), radio buttons or segmented buttons, depends on the options used.

| Drop Down Menu | Radio Buttons | Segmented Buttons | | --- | --- | --- | | | | |

Command Example:

const gDialog = require('gdialog');
const dialog = new gDialog();
let options = {};

// Drop Down Menu
options = {
    type: 'pickerbox',
    title: 'Title',
    header: 'Header',
    text: 'Select a number:',
    items: ['1', '2', '3'],
    icon_file: '/path/to/logo.png',
    buttons: [ 'OK', 'Cancel' ],
    focus: true
};
console.log(dialog.runSync(options));

// Radio Buttons
options = {
    type: 'pickerbox',
    title: 'Title',
    header: 'Header',
    text: 'Select a number:',
    items: ['1', '2'],
    style: 'radio',
    icon_file: '/path/to/logo.png',
    buttons: [ 'OK', 'Cancel' ],
    focus: true
};
console.log(dialog.runSync(options));

# Segmented Buttons
options = {
    type: 'pickerbox',
    title: 'Title',
    header: 'Header',
    text: 'Select a number:',
    items: ['1', '2'],
    style: 'segmented',
    icon_file: '/path/to/logo.png',
    buttons: [ 'OK', 'Cancel' ],
    focus: true
};
console.log(dialog.runSync(options));

| Key | Value (Example) | Description | | --- | --- | --- | | items | ["Item 1", "Item 2"] | The items to display in the picker box. The value must be provided as an array | | style | "style" | Defines the style of the picker box, options are default, radio and segmented. "default" style is the drop down menu |

File Select

Template Name is fileselect.
Displays a dialog window with an input field and a button to open the file select dialog.

Command Example:

const gDialog = require('gdialog');
let options = {
    type: 'fileselect',
    title: 'Title',
    header: 'Header',
    text: 'Please select a file',
    icon_file: '/path/to/logo.png',
    buttons: [ 'OK', 'Cancel' ],
    focus: true
};
const dialog = new gDialog();
console.log(dialog.runSync(options));

| Key | Value (Example) | Description | | --- | --- | --- | | with_file | "/starting/path" | Starts the file select dialog with the specified file alrady selected | | with_directory | "/starting/directory" | Starts the file select dialog showing the specified directory | | with_extensions | ["jpg", "png"] | Limits file selection to specified file extensions. The value must be provided as an array | | packages_as_directories | true | Treats installation packages as directories | | select_directories | true | Allows the user to select directories | | select_only_directories | true | Allows the user to select only directories | | select_multiple | true | Allows the user to select multiple files |

File Save

Template Name is filesave.
Displays a dialog window with an input field and a button to open the file save dialog.

Command Example:

const gDialog = require('gdialog');
let options = {
    type: 'filesave',
    title: 'Title',
    header: 'Header',
    text: 'Please select where to save the file',
    icon_file: '/path/to/logo.png',
    buttons: [ 'OK', 'Cancel' ],
    focus: true
};
const dialog = new gDialog();
console.log(dialog.runSync(options));

| Key | Value (Example) | Description | | --- | --- | --- | | with_file | "/starting/path" | Starts the file select dialog with the specified file alrady selected | | with_directory | "/starting/directory" | Starts the file select dialog showing the specified directory | | with_extensions | ["jpg", "png"] | Limits file selection to specified file extensions. The value must be provided as an array | | packages_as_directories | true | Treats installation packages as directories | | dont_create_directories | true | Prevents the user from creating directories |

Banner Box

Template Name is bannerbox.
Displays a banner dialog window in the top right corner of the screen with up to two buttons.
NOTE: This template is not utilizing macOS's notification center.

| Banner Box | Banner Box with one button | Banner Box with two buttons | | --- | --- | --- | | | | |

Command Example:

const gDialog = require('gdialog');
let options = {
    type: 'bannerbox',
    header: 'Header',
    text: 'Banner Box with two buttons',
    icon_file: '/path/to/logo.png',
    buttons: [ 'OK', 'Cancel' ],
    focus: true
};
const dialog = new gDialog();
console.log(dialog.runSync(options));

| Key | Value (Example) | Description | | --- | --- | --- | | background_color | "#000000" | Specify a background color in hex color code |

Notification

Template Name is notification.
Sends a notification to macOS's notification center.
NOTE: Notifications will not work from unsigned non-application bundles (.app), in order to use the notifications in a Node.js project, it must be compiled into a a signed application with a Bundle ID, it is recommended to use the gDialog app for notifications
NOTE: Unless node is pre-approved for notifications via the MDM notifications payload, the user will get a notification asking to approve node to present notifications:
The following global options are not available in this template:
icon_file, system_icon, buttons, width, height, window_size, allow_quit, no_return, focus and scrollable_text.

| macOS Big Sur | macOS Catalina | | --- | --- | | | |

Command Example:

const gDialog = require('gdialog');
let options = {
    type: 'notification',
    title: 'Title',
    header: 'Header',
    text: 'Notification Text',
    buttons: [ 'OK', 'Cancel' ],
    focus: true
};
const dialog = new gDialog();
console.log(dialog.runSync(options));

| Key | Value (Example) | Description | | --- | --- | --- | | dont_wait | true | Don't wait for for the notification to be seen by the user |