Modal

Modal library is a library for easier and faster creation and display of Fandom's built-in modals.
== ==
=== 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:
=== 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 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:
; 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!