Message

Use the bsMessageModal function to alert users to a simple message or to capture information via a pop-up modal dialog.

Note, the bsMessageModal function requires the Bootstrap 4+ JavaScript library. This library can be downloaded or referenced via CDN from https://www.bootstrapcdn.com.

The example below displays a simple message in a modal dialog by setting the message property on the configuration parameter to the constructor.

wire.bsMessageModal({
    message: "Hello from my first message modal"
});

The message property can also be set to HTML.

wire.bsMessageModal({
    message: "Click <a href='#'>here</a>"
});

Add a title by using the title property.

wire.bsMessageModal({
    title: "My Modal",
    message: "Hello from my first message modal"
});

Give the modal a DOM id using the id property. This is convenient of its required to reference the modal from code or inside style sheets.

wire.bsMessageModal({
    id: "my-modal",
    message: "Hello from my first message modal"
});

Buttons

A simple modal like the one above will contain an Ok button that can be pressed when the user has finished reading the message. To add a Cancel button, set the cancel property's visible attribute to true.

wire.bsMessageModal({
    message: "Hello from my first message modal",
    cancel: {
        visible: true
    }
});

Labels

To change the labels for either the Ok or Cancel button, use the label attributes of each.

wire.bsMessageModal({
    message: "Hello from my first message modal",
    ok: {
        label: "For Sure"
    },
    cancel: {
        visible: true,
        label: "No Way"
    }
});

Colors

To change the colors for the modal and/or the buttons, set the css properties. The property on the root configuration is set on the modal's title.

wire.bsMessageModal({
    message: "Hello from my first message modal",
    css: "alert-primary",
    ok: {
        css: "btn-secondary"
    },
    cancel: {
        visible: true,
        css: "btn-secondary"
    }
});

Callback

Add a custom callback function to the configuration via the callback property. This function will be called when either the Ok or Cancel buttons have been clicked.

The first parameter tells the function whether the Ok button was clicked. The second parameter is a method that when called returns control to the modal. This method takes an optional parameter that tells the modal whether it should stay up (true) or is ok to drop (false or undefined).

wire.bsMessageModal({
    message: "Hello from my first message modal",
    cancel: {
        visible: true
    },
    callback: (ok, returnControl) => {

        // ok == true  -> the Ok button was pressed
        // ok == false -> the Cancel button was pressed
        
        // return control to the modal
        // not passing a 'true' parameter lets the modal know its ok to drop
        returnControl();
    }
});

Await

A call to bsMessageModal runs synchronously which means after the modal is displayed the code below the line that called the modal continues to run. In some cases, it is required that the response from the modal be considered before continuing with the code logic. Callbacks are typically the constructs used in JavaScript for this purpose. However, callbacks can get clumsy if responses from a number of them need to be chained together.

The await keyword can be used to asynchronously pause the code execution via a promise at the line in which the modal was called. Here, the code waits for the modal response before continuing.

In the example below, bsMessageModal returns a promise and waits for the response from the modal. It returns the same ok parameter from the callback in the earlier example.

const ok = await wire.bsMessageModal({
    message: "Are you Ok with this?",
    cancel: {
        visible: true
    }
});

if(ok)
    // the Ok button was pressed
else
    // the Cancel button was pressed

Data Inputs

Because the message property supports HTML, advanced templates can be used with the message modal that include forms and other data input HTML blocks.

const template = "Tell me your name: <input id='your-name' type='text'>";

await wire.bsMessageModal({
    message: template
});

const yourName = (<HTMLInputElement>document.getElementById("your-name")).value;

Validation

Sometimes it is required that the modal stay up based on the user input. For example, if data input fails validation, the user may be asked to change the input.

Returning true in the callback in the example below, will prevent the modal from dropping based on the your-name input failing validation.

// $ = jQuery reference

const template = "Tell me your name: <input id='your-name' type='text'>";

wire.bsMessageModal({
    message: template, 
    callback: (ok, returnControl) => {
        
        const yourName = $("#your-name").val();
        
        // Simple test to be sure field is not empty
        if(yourName == "") {
        
            // highlight the input box in red
            $("#your-name").css("border", "1px solid red");
            
            // keep the modal up
            returnControl(true); 
        }
        else        
            // (default) drop the modal
            returnControl();
    }
});