gdialog v1.0.4

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

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));

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));

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));

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));

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>

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);

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.

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));

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));

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));

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.

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));

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.

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));