(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}} |
||
− | | |
+ | | 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
andcontent-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 ofAltLink
.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 ofdeactivate()
. Acts the same asshow()
if the modal hasn't been created.deactivate()
— Shows a throbber on the modal. Acts the same asshow()
if the modal hasn't been created.close()
/hide()
— Closes the modal.setAltLink(options)
—options
can be either an object representingAltLink
's parameters or anAltLink
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
andnormal
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 tolink
. title
- Title of the link, if
type
is set tolink
. target
- Target of the link, if
type
is set tolink
. name
- Name of the input element, if
type
is set toinput
.
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();
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();
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();
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();
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();