Cordova - Dialogs

Cordova - Dialogs

The Cordova Dialogs plugin (cordova-plugin-dialogs) provides access to native platform dialog UI elements, such as alerts, confirmations, prompts, and beeps. This allows for a more native user experience for notifications and user interactions.

Step 1 - Installing the Dialogs Plugin

Install the plugin using the Cordova CLI in your project’s root directory:

your-cordova-project/ cordova plugin add cordova-plugin-dialogs

Step 2 - Add UI Elements (Buttons)

Let’s add buttons to index.html to trigger different types of dialogs:

<body>
    <button id="showAlertBtn">Show Alert</button>
    <button id="showConfirmBtn">Show Confirm</button>
    <button id="showPromptBtn">Show Prompt</button>
    <button id="playBeepBtn">Play Beep</button>
    <div id="dialogResult">Dialog results will appear here.</div>
</body>

Step 3 - Add Event Listeners

In www/js/index.js, within onDeviceReady, attach event listeners to these buttons:

// Inside onDeviceReady in www/js/index.js
document.getElementById("showAlertBtn").addEventListener("click", showCustomAlert);
document.getElementById("showConfirmBtn").addEventListener("click", showCustomConfirm);
document.getElementById("showPromptBtn").addEventListener("click", showCustomPrompt);
document.getElementById("playBeepBtn").addEventListener("click", playBeepNotification);

Step 4 - Implement Dialog Functions

Now, define the JavaScript functions that will use the navigator.notification API provided by the plugin.

const dialogResultDisplay = document.getElementById('dialogResult');

// 4A - Alert Dialog
function showCustomAlert() {
    navigator.notification.alert(
        'This is a native alert message!', // message
        () => { dialogResultDisplay.textContent = 'Alert dismissed.'; }, // alertCallback
        'Alert Title',                     // title
        'Done'                             // buttonName
    );
}

// 4B - Confirm Dialog
function showCustomConfirm() {
    navigator.notification.confirm(
        'Do you want to proceed?', // message
        (buttonIndex) => { // confirmCallback
            // buttonIndex is 1-based. 1 for first button, 2 for second, etc.
            // If 0, it means dialog was dismissed without pressing a button (e.g. back button on Android)
            if (buttonIndex === 1) {
                dialogResultDisplay.textContent = 'User chose: Yes!';
            } else if (buttonIndex === 2) {
                dialogResultDisplay.textContent = 'User chose: No.';
            } else {
                dialogResultDisplay.textContent = 'Confirm dialog dismissed.';
            }
        },
        'Confirmation',           // title
        ['Yes', 'No']             // buttonLabels (Array of strings)
    );
}

// 4C - Prompt Dialog
function showCustomPrompt() {
    navigator.notification.prompt(
        'Please enter your name:', // message
        (results) => { // promptCallback
            // results.buttonIndex: 1-based index of the pressed button.
            // results.input1: The text entered by the user.
            if (results.buttonIndex === 1 && results.input1) {
                dialogResultDisplay.textContent = `Hello, ${results.input1}!`;
            } else if (results.buttonIndex === 2) {
                dialogResultDisplay.textContent = 'Prompt cancelled.';
            } else {
                 dialogResultDisplay.textContent = `Prompt dismissed. Input: ${results.input1}`;
            }
        },
        'User Input',             // title
        ['OK', 'Cancel'],         // buttonLabels (Array of strings)
        'Your name here'          // defaultText
    );
}

// 4D - Beep Notification
function playBeepNotification() {
    const times = 2; // Number of times to repeat the beep
    navigator.notification.beep(times);
    dialogResultDisplay.textContent = `Played beep ${times} times.`;
}

Understanding Dialog Behavior

Alert: Clicking “Show Alert” will display a native alert dialog. For example, it will show a box with the title “Alert Title”, message “This is a native alert message!”, and a button labeled “Done”. When dismissed, “Alert dismissed.” will appear in the dialogResult div.

Confirm: Clicking “Show Confirm” presents a dialog with a question like “Do you want to proceed?” and buttons “Yes” and “No”. If “Yes” is pressed, the dialogResult div will show “User chose: Yes!”. If “No” is pressed, it will show “User chose: No.”.

Prompt: Clicking “Show Prompt” opens a dialog asking for input, e.g., “Please enter your name:”, with an input field pre-filled with “Your name here” and buttons “OK” and “Cancel”. If the user types “Alex” and clicks “OK”, the dialogResult div will display “Hello, Alex!”.

Beep: Clicking “Play Beep” will cause the device to play its native notification beep sound twice (as times is 2). The dialogResult div will indicate “Played beep 2 times.”.

Key Points

• Native UI: These dialogs use the platform’s native UI elements, providing a consistent user experience.
• Asynchronous: All dialog methods are asynchronous. The callback function is invoked when the user interacts with the dialog.
• Customization: You can customize the title, message, and button labels for most dialogs.
• Button Indexing: For confirm and prompt callbacks, the buttonIndex is 1-based. A value of 0 or absence of buttonIndex often means the dialog was dismissed in a way other than pressing a button (e.g., Android back button), though this behavior can be platform-specific.