Modal

Modal library is a library for easier and faster creation and display of Fandom's built-in modals.

Usage

Importing

To import the Modal library inside your script, use:

importArticle({
    type: 'script',
    article: 'u:dev:MediaWiki:Modal.js'
});

The script's object won't be immediately available, but it will call a hook through mw.hook. To ensure it exists, you can use:

mw.hook('dev.modal').add(function(modal) {
    // `modal` object is the library's exported object, same as window.dev.modal.
});

Exported object

The library exposes an object with several properties:

Modal: The main class of the library. Instantiating it registers the modal in the library.
ModalButton: Class for modal's buttons.
modals: Object with all registered modals.
_init: Function called before the hook is fired as a callback for when Fandom's modal component loads.
_modal: Fandom's modal component internally used by the library.

Models

`Modal`

Class representing the modal object.

Parameters

id: Unique ID of the modal. This parameter is required.
context: Object that modal events should be bound to.
size: Size of the modal. Accepted values are small, medium, large and content-size.
content: Content of the modal.; If set to a string, it represents the HTML the modal contains.; If set to an object while UI-js is imported (UI-js must be imported before Modal, otherwise it won't work), it runs the object through the dev.ui function and sets the generated HTML as the modal's content.; Note: DOM events set on the nodes through UI-js will get unregistered, as the library calls .outerHTML on the node.
title: Title of the modal. By default set to "Modal". This is safe by default unless isHTML is set, in that case it must be escaped properly.
isHTML: Whether the title of the modal is passed as HTML.
buttons: Array of objects representing parameters to the ModalButton model.
events: Map of event names to event listeners to register in the modal. These events can be called by modal buttons.; By default, Fandom's modal component registers a close event called when the close button is clicked.; Values of the events object can be single functions, which registers as the only event listeners, or arrays of functions, which registers them all as event listeners.
class / classes: String or an array of strings representing the classes of the modal.
close: Function called upon closing the modal, which can return false if the modal should not continue closing.
closeEscape: Whether the modal should be closed when the Esc button is pressed. By default enabled, set to false to disable.
closeTitle: Title on the X button for closing the modal.

Properties

Here are the available properties of a Modal instance. Most of them are based on input parameters described above.

id
context
buttons
classes
closeFunc — Callback after closing the modal.
closeEscape
closeTitle
content — HTML of the modal as a string.
events — Map of event names to arrays of callback functions when these events are fired.
size
title
titleIsHTML — Whether the title is displayed unescaped.
_loading — Internal promise object that is resolved at the time the modal's component is created.
_modal — Internal modal object returned by the modal factory.

Methods

Here are the available methods of a Modal instance. Most of them as used as setters for properties mentioned above. Each of these methods returns a self instance so they can be easily chained together.

create() — Starts the creation of the modal component and returns a promise that resolves when the creation is done.
show() — Shows the modal. If its creation hasn't finished yet, it will wait until the creation and then show the modal.
close() / hide() — Closes the modal.
setButtons(buttons)
setClass(class)
setClasses(classes)
setClose(close)
setCloseEscape(closeEscape)
setCloseTitle(title)
setContent(content)
setEvent(name, listener)
setEvents(events) — Note: This resets all other events of the modal.
setSize(size)
setTitle(title, isHTML)
_close() — Internal callback after a close event has been triggered. Starts recreation of the modal.
_created(modal) — Internal callback after the modal component has been created.

`ModalButton`

Class representing a button in the modal's footer.

Parameters

type

Type of the button. Set to button by default. Can be set to either:

link
input
button

primary: Whether the button is a primary one or not. Adds a primary class to the button.
normal: Adds a normal class to the button.
text / value: Text on the button. This parameter is required.
events / event: Array of events the button is triggering, or a string if it's triggering a single event.
classes: Array of classes, in addition to the primary and normal ones.
id: ID of the button.
disabled: Whether the button is disabled.
sprite / imageClass: Sprite class added to the button. Available sprite classes are:

edit
talk
talk-two
categorization
move
new
photo
video
search
mytools
follow
share
logo
logo2
logo3
logo4
logo9
drag
trash
activity
random
close
edit-pencil
edit-pencil-small
blog
message
lock
remove
details
info-icon
ok
error
contribute
question
close-notification
popout
embed
email
share2
gear
facebook
external
progress
play

href: Location the button is linking to if type is set to link.
title: Title of the link, if type is set to link.
target: Target of the link, if type is set to link.
name: Name of the input element, if type is set to input.

Properties

Available properties of the button object. Their purpose is described in the parameters.

primary
normal
classes
disabled
events
href
id
name
text
type
sprite
target
title

Methods

Available methods of the button object. Most of these are setters for the properties described above.

create — Returns required Mustache parameters for rendering the modal button.
setClasses
setDisabled
setEvents / setEvent
setHref
setID
setName
setText
setSprite
setTarget
setTitle

Examples

As the documentation above might be confusing, here are a few examples with demonstrations. Wrappers mentioned in the Usage section won't be used.

Simple modal

This example simply creates a small modal with the default title, ID of SimpleModal and "Hello World!" as contents.

var modal = new window.dev.modal.Modal({
    content: 'Hello World!',
    id: 'SimpleModal',
    size: 'small'
});
modal.create();
modal.show();

Try it out!

Medium-sized modal

This example creates a medium-sized modal with the title of "Medium sized modal" and ID of MediumModal.

var modal = new window.dev.modal.Modal({
    content: 'This is a medium-sized modal.',
    id: 'MediumModal',
    size: 'medium',
    title: 'Medium-sized modal'
});
modal.create();
modal.show();

Try it out!

UI-js modal

This example creates a modal with contents being generated by UI-js and sized the same as the page content.

var modal = new window.dev.modal.Modal({
    content: {
        children: [
            'This modal uses UI-js to generate the content and it\'s the same size as the content.',
            {
                attr: {
                    alt: 'Fandom logo',
                    title: 'Fandom logo',
                    src: 'https://vignette.wikia.nocookie.net/central/images/8/8f/FANDOM-logo.svg/revision/latest/scale-to-width-down/300'
                },
                type: 'img'
            }
        ],
        type: 'div'
    },
    id: 'UIModal',
    size: 'content-size'
});
modal.create();
modal.show();

Try it out!

Buttons modal

This example creates a modal with various kinds of buttons. One is disabled, one is primary, one is an input element and one is a link.

var modal = new window.dev.modal.Modal({
    buttons: [
        {
            classes: ['my-custom-class'],
            event: 'custom1',
            id: 'my-custom-id',
            primary: true,
            text: 'Primary button'
        },
        {
            disabled: true,
            text: 'Disabled button'
        },
        {
            event: 'custom2',
            sprite: 'ok',
            text: ' '
        },
        {
            event: 'custom3',
            name: 'my-name',
            type: 'input',
            value: 'This is actually an input element!'
        },
        {
            href: mw.util.getUrl('Special:Random'),
            target: 'hmm',
            text: 'This is a link!',
            title: 'This is the link\'s title!',
            type: 'link'
        }
    ],
    content: 'This modal has buttons!',
    events: {
        custom1: function() {
            new BannerNotification('Custom event 1!', 'confirm').show();
        },
        custom2: function() {
            new BannerNotification('Custom event 2!', 'warn').show();
        },
        custom3: function() {
            new BannerNotification('Custom event 3!', 'error').show();
        }
    },
    id: 'ButtonsModal'
});
modal.create();
modal.show();

Try it out!

Text above can be found here (edit)