FANDOM


QDmodal is a library allowing scripts to display a modal dialog. It provides an adaptive layout without complex styling by using the CSS flexbox layout.

QDmodal supports both vanilla MediaWiki wikis (e.g. Wikipedia) and the Fandom wiki platform (where it'll match the theme of the wiki it's displayed on). It should work in most browsers released within the last few years, specifically browsers with unprefixed support for CSS flexbox.

Usage

Loading the library

First, you'll need to make sure the QDmodal script is loaded:

if (mw.libs.QDmodal) {
    // QDmodal library is already loaded - we can run our function directly!
    doThingsUsingModal();
} else {
    // not loaded - fetch QDmodal library (and let it be cached),
    // then run our function once it's loaded
    $.ajax({
        cache: true,
        dataType: "script",
        url: "https://dev.fandom.com/load.php?mode=articles&only=scripts&articles=MediaWiki:QDmodal.js"
    }).done(doThingsUsingModal);
}

Using the modal

Once the script has been loaded, you can initialise a new modal using the mw.libs.QDmodal constructor:

var myModal = new mw.libs.QDmodal("my-modal-id");

The myModal variable will be a modal object.

To show the modal, use the modal object's show function with a data object as the argument:

myModal.show({
    content: "Content to be shown within the modal.",
    title: "Title for the modal header",
    buttons: [{
        text: "Button One",
        href: "https://example.com/",
        attr: {
            id: "my-modal-button-two"
        }
    }, {
        text: "Button Two",
        handler: function (event) {
            // do something when button is clicked
        }
    }]
});
If an onBeforeShow property was included in the data object, its function will be run before the modal is added to the DOM and before any hook is fired. If a hook property was included in the data object, it will be fired before the modal is added to the DOM but after the onBeforeShow function is called. If an onShow property was included in the data object, its function will be run after the modal is added to the DOM. Arbitrary properties may also be included in the data object: these can be useful for storing information about the current modal content for use within a hook or event handler.

To hide the modal, use the modal object's hide function:

myModal.hide();

If an onHide property was included in the data object passed when the modal was shown, its function will be run before the modal is removed from the DOM.

Object details

Modal object

Key Type Description
$content jQuery obj. Main content area within the modal.
$title jQuery obj. Title element within the modal.
$footer jQuery obj. Footer element within the modal.
visible boolean Whether the modal is currently being displayed.
data object Data object representing the modal's current content. If the modal isn't visible, this will be null.
$element jQuery obj. Entire modal element.
$container jQuery obj. Parent element of the modal (used to dim background).

Data object

Key Description
content A HTML string or jQuery object to be shown as content within the modal.
title Text-only string to be shown in the modal header.
hook Name of a hook to be fired using the mw.hook API. The modal object will be passed to the hook function. Note that it is fired before the modal is added to the DOM but after the onBeforeShow function is called.
loading If this value is truthy, the mw-ajax-loader class will be added to the modal's content area, displaying a spinning animation.
buttons An array of button objects to be added to the modal footer.
onBeforeShow Function run whenever the modal object's show function is called. The modal object will be passed to the function. Note that it is run before the modal is added to the DOM and before any hook is fired.
onShow Function run whenever the modal object's show function is called. The modal object will be passed to the function. Note that it is run after the modal is added to the DOM.
onHide Function run whenever the modal object's hide function is called. The modal object will be passed to the function. Note that it is run before the modal is removed from the DOM.

Button object

Key Description
text Text to be displayed on the button.
href URL to be navigated to whenever the button is clicked. Note this will change the button from a <span> element to an <a>nchor element.
handler Function run whenever the button is clicked. The jQuery click event object will be passed to the function.
attr Object consisting of attribute names and values to add to the button element. It is passed as-is to jQuery's attr function and can be used to add an ID, data attributes, etc.
Community content is available under CC-BY-SA unless otherwise noted.

Fandom may earn an affiliate commission on sales made from links on this page.

Stream the best stories.

Fandom may earn an affiliate commission on sales made from links on this page.

Get Disney+