QDmodal — dev

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

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&articles=MediaWiki:QDmodal.js&only=scripts"
    }).done(doThingsUsingModal);
}

Alternatively, if you want to check if the library is loaded with a jQuery promise that resolves on the library loading, you can do somthing like this:

$.Deferred(function (promise) {
	if (mw.libs.QDmodal) {
		promise.resolve(mw.libs.QDmodal);
	} else {
		$.ajax({
			cache: true,
			dataType: "script",
			url: "https://dev.fandom.com/load.php?mode=articles&articles=MediaWiki:QDmodal.js&only=scripts"
		}).done(function () { 
            promise.resolve(mw.libs.QDmodal);
        });
	}
});

A third way is to use hook to synchronize loading.

importArticle({
    type: 'script',
    article: 'u:dev:MediaWiki:QDmodal.js'
});
mw.hook('dev.qdmodal').add(function(QDmodal) {
    // QDmodal is the modal constructor
    new QDmodal("my-modal-id");
    // You can also access it with `mw.libs.QDmodal`
});

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: "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.",
    buttons: [{
        text: "Button One",
        href: "https://example.com/",
        attr: {
            id: "my-modal-button-one"
        }
    }, {
        text: "Button Two",
        handler: function (event) {
            // do something when button is clicked
        },
        condition: function (modal) {
            // check if this button should be included
        }
    }]
});

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. If this function returns false, the modal won't be hidden.

Object details

Modal object

Key	Type	Description
`$content`	jQuery object	Main content area within the modal.
`$title`	jQuery object	Title element within the modal.
`$footer`	jQuery object	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 object	Entire modal element.
`$container`	jQuery object	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, an SVG image will replace the modal's content, 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. If this function returns `false`, the modal won't be hidden.

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.
`condition`	If this property is present and is a function, the function will be run. The modal object will be passed to the function. The button will only be added to the modal footer if this function returns a truthy value.
`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.

Text above can be found here (edit)