Fandom Developers Wiki
Register
(Fix)
m (+Noreplyz)
Line 1: Line 1:
 
<noinclude>{{LangSelect}}</noinclude><includeonly>{{Infobox JavaScript
 
<noinclude>{{LangSelect}}</noinclude><includeonly>{{Infobox JavaScript
| Type = libraries
+
| Type = libraries
| Status = stable
+
| Status = stable
| Description = {{{description|Makes creation of Fandom modals easier.}}}
+
| Description = {{{description|Makes creation of Fandom modals easier.}}}
| Author = [[User:KockaAdmiralac|KockaAdmiralac]]
+
| Author = [[User:KockaAdmiralac|KockaAdmiralac]]
  +
| Using code by = [[User:Noreplyz|Noreplyz]] ([[WHAM]])
| Scope = ps
+
| Scope = ps
| Updated = {{Updated|MediaWiki:Modal.js}}
 
| Code =
+
| Updated = {{Updated|MediaWiki:Modal.js}}
  +
| Code =
 
* [[MediaWiki:Modal.js|Modal.js]]
 
* [[MediaWiki:Modal.js|Modal.js]]
 
* [[MediaWiki:Modal/demo.js|demo.js]]
 
* [[MediaWiki:Modal/demo.js|demo.js]]

Revision as of 13:19, 22 August 2020

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.
AltLink
Class for the alternative link in the modal. Will be instantiated by the library but can also be instantiated manually with appropriate parameters and passed to setAltLink.
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, 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 Escape button is pressed. By default enabled, set to false to disable.
closeTitle
Title on the X button for closing the modal.
altLink
Alternative link displayed next to modal buttons.

Properties

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

  • id
  • context
  • altLink — Instance of AltLink.
  • 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.
  • activate() — Opposite of deactivate(). Acts the same as show() if the modal hasn't been created.
  • deactivate() — Shows a throbber on the modal. Acts the same as show() if the modal hasn't been created.
  • close() / hide() — Closes the modal.
  • setAltLink(options)options can be either an object representing AltLink's parameters or an AltLink object.
  • 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.

AltLink

Class representing an alternative link in the modal.

Parameters

id
ID of the link.
href
Location the link is pointing to.
title
Title of the link.
text
Text in the link.

Properties

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

  • id
  • href
  • title
  • text

Methods

AltLink has a single method, create(), which returns an object with Mustache parameters required to render it.

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
  • setType
  • 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!

Alternative link modal

This example creates a large modal with a primary button on the right side and alternative link on the left side.

var modal = new window.dev.modal.Modal({
    altLink: {
        href: mw.util.getUrl('Special:MyPage'),
        id: 'my-alt-link',
        text: 'An alternative link approaches.',
        title: 'This is the alternative link\'s title.'
    },
    buttons: [
        {
            event: 'close',
            primary: true,
            text: 'Close me'
        }
    ],
    closeEscape: false,
    closeTitle: 'Cubes!',
    content: 'This modal has an alternative link. Also, it doesn\'t close when pressing Escape and the title when you hover over the X button is different. Woo!',
    id: 'AltLinkModal',
    size: 'large'
});
modal.create();
modal.show();
Try it out!
Text above can be found here (edit)