5 // The #mw-notification-area div that all notifications are contained inside.
7 // Number of open notification boxes at any time
8 openNotificationCount
= 0,
10 preReadyNotifQueue
= [];
13 * A Notification object for 1 message.
15 * The underscore in the name is to avoid a bug <https://github.com/senchalabs/jsduck/issues/304>.
16 * It is not part of the actual class name.
18 * @class mw.Notification_
19 * @alternateClassName mw.Notification
21 * @constructor The constructor is not publicly accessible; use mw.notification#notify instead.
22 * This does not insert anything into the document (see #start).
25 function Notification( message
, options
) {
26 var $notification
, $notificationTitle
, $notificationContent
;
28 $notification
= $( '<div class="mw-notification"></div>' )
29 .data( 'mw.notification', this )
30 .addClass( options
.autoHide
? 'mw-notification-autohide' : 'mw-notification-noautohide' );
33 // Sanitize options.tag before it is used by any code. (Including Notification class methods)
34 options
.tag
= options
.tag
.replace( /[ _\-]+/g, '-' ).replace( /[^\-a-z0-9]+/ig, '' );
36 $notification
.addClass( 'mw-notification-tag-' + options
.tag
);
43 // Sanitize options.type
44 options
.type
= options
.type
.replace( /[ _\-]+/g, '-' ).replace( /[^\-a-z0-9]+/ig, '' );
45 $notification
.addClass( 'mw-notification-type-' + options
.type
);
48 if ( options
.title
) {
49 $notificationTitle
= $( '<div class="mw-notification-title"></div>' )
50 .text( options
.title
)
51 .appendTo( $notification
);
54 $notificationContent
= $( '<div class="mw-notification-content"></div>' );
56 if ( typeof message
=== 'object' ) {
57 // Handle mw.Message objects separately from DOM nodes and jQuery objects
58 if ( message
instanceof mw
.Message
) {
59 $notificationContent
.html( message
.parse() );
61 $notificationContent
.append( message
);
64 $notificationContent
.text( message
);
67 $notificationContent
.appendTo( $notification
);
69 // Private state parameters, meant for internal use only
70 // isOpen: Set to true after .start() is called to avoid double calls.
71 // Set back to false after .close() to avoid duplicating the close animation.
72 // isPaused: false after .resume(), true after .pause(). Avoids duplicating or breaking the hide timeouts.
73 // Set to true initially so .start() can call .resume().
74 // message: The message passed to the notification. Unused now but may be used in the future
75 // to stop replacement of a tagged notification with another notification using the same message.
76 // options: The options passed to the notification with a little sanitization. Used by various methods.
77 // $notification: jQuery object containing the notification DOM node.
80 this.message
= message
;
81 this.options
= options
;
82 this.$notification
= $notification
;
86 * Start the notification. Called automatically by mw.notification#notify
87 * (possibly asynchronously on document-ready).
89 * This inserts the notification into the page, closes any matching tagged notifications,
90 * handles the fadeIn animations and replacement transitions, and starts autoHide timers.
94 Notification
.prototype.start = function () {
97 $notification
, options
,
98 // Original opacity so that we can animate back to it later
100 // Other notification elements matching the same tag
114 openNotificationCount
++;
116 options
= this.options
;
117 $notification
= this.$notification
;
119 opacity
= this.$notification
.css( 'opacity' );
121 // Set the opacity to 0 so we can fade in later.
122 $notification
.css( 'opacity', 0 );
125 // Check to see if there are any tagged notifications with the same tag as the new one
126 $tagMatches
= $area
.find( '.mw-notification-tag-' + options
.tag
);
129 // If we found a tagged notification use the replacement pattern instead of the new
130 // notification fade-in pattern.
131 if ( options
.tag
&& $tagMatches
.length
) {
133 // Iterate over the tag matches to find the outerHeight we should use
134 // for the placeholder.
136 $tagMatches
.each( function () {
137 var notif
= $( this ).data( 'mw.notification' );
139 // Use the notification's height + padding + border + margins
140 // as the placeholder height.
141 outerHeight
= notif
.$notification
.outerHeight( true );
142 if ( notif
.$replacementPlaceholder
) {
143 // Grab the height of a placeholder that has not finished animating.
144 placeholderHeight
= notif
.$replacementPlaceholder
.height();
145 // Remove any placeholders added by a previous tagged
146 // notification that was in the middle of replacing another.
147 // This also makes sure that we only grab the placeholderHeight
148 // for the most recent notification.
149 notif
.$replacementPlaceholder
.remove();
150 delete notif
.$replacementPlaceholder
;
152 // Close the previous tagged notification
153 // Since we're replacing it do this with a fast speed and don't output a placeholder
154 // since we're taking care of that transition ourselves.
155 notif
.close( { speed
: 'fast', placeholder
: false } );
158 if ( placeholderHeight
!== undefined ) {
159 // If the other tagged notification was in the middle of replacing another
160 // tagged notification, continue from the placeholder's height instead of
161 // using the outerHeight of the notification.
162 outerHeight
= placeholderHeight
;
166 // Insert the new notification before the tagged notification(s)
167 .insertBefore( $tagMatches
.first() )
169 // Use an absolute position so that we can use a placeholder to gracefully push other notifications
170 // into the right spot.
171 position
: 'absolute',
172 width
: $notification
.width()
174 // Fade-in the notification
175 .animate( { opacity
: opacity
},
178 complete: function () {
179 // After we've faded in clear the opacity and let css take over
180 $( this ).css( { opacity
: '' } );
186 // Create a clear placeholder we can use to make the notifications around the notification that is being
187 // replaced expand or contract gracefully to fit the height of the new notification.
188 notif
.$replacementPlaceholder
= $( '<div>' )
189 // Set the height to the space the previous notification or placeholder took
190 .css( 'height', outerHeight
)
191 // Make sure that this placeholder is at the very end of this tagged notification group
192 .insertAfter( $tagMatches
.eq( -1 ) )
193 // Animate the placeholder height to the space that this new notification will take up
194 .animate( { height
: $notification
.outerHeight( true ) },
196 // Do space animations fast
198 complete: function () {
199 // Reset the notification position after we've finished the space animation
200 // However do not do it if the placeholder was removed because another tagged
201 // notification went and closed this one.
202 if ( notif
.$replacementPlaceholder
) {
203 $notification
.css( 'position', '' );
205 // Finally, remove the placeholder from the DOM
210 // Append to the notification area and fade in to the original opacity.
213 .animate( { opacity
: opacity
},
216 complete: function () {
217 // After we've faded in clear the opacity and let css take over
218 $( this ).css( 'opacity', '' );
224 // By default a notification is paused.
225 // If this notification is within the first {autoHideLimit} notifications then
226 // start the auto-hide timer as soon as it's created.
227 autohideCount
= $area
.find( '.mw-notification-autohide' ).length
;
228 if ( autohideCount
<= notification
.autoHideLimit
) {
234 * Pause any running auto-hide timer for this notification
236 Notification
.prototype.pause = function () {
237 if ( this.isPaused
) {
240 this.isPaused
= true;
242 if ( this.timeout
) {
243 clearTimeout( this.timeout
);
249 * Start autoHide timer if not already started.
250 * Does nothing if autoHide is disabled.
251 * Either to resume from pause or to make the first start.
253 Notification
.prototype.resume = function () {
255 if ( !notif
.isPaused
) {
258 // Start any autoHide timeouts
259 if ( notif
.options
.autoHide
) {
260 notif
.isPaused
= false;
261 notif
.timeout
= setTimeout( function () {
262 // Already finished, so don't try to re-clear it
263 delete notif
.timeout
;
265 }, notification
.autoHideSeconds
* 1000 );
270 * Close/hide the notification.
272 * @param {Object} options An object containing options for the closing of the notification.
274 * - speed: Use a close speed different than the default 'slow'.
275 * - placeholder: Set to false to disable the placeholder transition.
277 Notification
.prototype.close = function ( options
) {
278 if ( !this.isOpen
) {
282 openNotificationCount
--;
283 // Clear any remaining timeout on close
286 options
= $.extend( {
291 // Remove the mw-notification-autohide class from the notification to avoid
292 // having a half-closed notification counted as a notification to resume
293 // when handling {autoHideLimit}.
294 this.$notification
.removeClass( 'mw-notification-autohide' );
296 // Now that a notification is being closed. Start auto-hide timers for any
297 // notification that has now become one of the first {autoHideLimit} notifications.
298 notification
.resume();
302 // Don't trigger any mouse events while fading out, just in case the cursor
303 // happens to be right above us when we transition upwards.
304 pointerEvents
: 'none',
305 // Set an absolute position so we can move upwards in the animation.
306 // Notification replacement doesn't look right unless we use an animation like this.
307 position
: 'absolute',
308 // We must fix the width to avoid it shrinking horizontally.
309 width
: this.$notification
.width()
311 // Fix the top/left position to the current computed position from which we
312 // can animate upwards.
313 .css( this.$notification
.position() );
315 // This needs to be done *after* notification's position has been made absolute.
316 if ( options
.placeholder
) {
317 // Insert a placeholder with a height equal to the height of the
318 // notification plus it's vertical margins in place of the notification
319 var $placeholder
= $( '<div>' )
320 .css( 'height', this.$notification
.outerHeight( true ) )
321 .insertBefore( this.$notification
);
324 // Animate opacity and top to create fade upwards animation for notification closing
330 duration
: options
.speed
,
331 complete: function () {
332 // Remove the notification
334 // Hide the area manually after closing the last notification, since it has padding,
335 // causing it to obscure whatever is behind it in spite of being invisible (bug 52659).
336 // It's okay to do this before getting rid of the placeholder, as it's invisible as well.
337 if ( openNotificationCount
=== 0 ) {
340 if ( options
.placeholder
) {
341 // Use a fast slide up animation after closing to make it look like the notifications
342 // below slide up into place when the notification disappears
343 $placeholder
.slideUp( 'fast', function () {
344 // Remove the placeholder
353 * Helper function, take a list of notification divs and call
354 * a function on the Notification instance attached to them.
358 * @param {jQuery} $notifications A jQuery object containing notification divs
359 * @param {string} fn The name of the function to call on the Notification instance
361 function callEachNotification( $notifications
, fn
) {
362 $notifications
.each( function () {
363 var notif
= $( this ).data( 'mw.notification' );
372 * Must only be called once, and not before the document is ready.
377 var offset
, $window
= $( window
);
379 $area
= $( '<div id="mw-notification-area" class="mw-notification-area mw-notification-area-layout"></div>' )
380 // Pause auto-hide timers when the mouse is in the notification area.
382 mouseenter
: notification
.pause
,
383 mouseleave
: notification
.resume
385 // When clicking on a notification close it.
386 .on( 'click', '.mw-notification', function () {
387 var notif
= $( this ).data( 'mw.notification' );
392 // Stop click events from <a> tags from propogating to prevent clicking.
393 // on links from hiding a notification.
394 .on( 'click', 'a', function ( e
) {
399 // Prepend the notification area to the content area and save it's object.
400 mw
.util
.$content
.prepend( $area
);
401 offset
= $area
.offset();
403 function updateAreaMode() {
404 var isFloating
= $window
.scrollTop() > offset
.top
;
406 .toggleClass( 'mw-notification-area-floating', isFloating
)
407 .toggleClass( 'mw-notification-area-layout', !isFloating
);
410 $window
.on( 'scroll', updateAreaMode
);
417 * @class mw.notification
422 * Pause auto-hide timers for all notifications.
423 * Notifications will not auto-hide until resume is called.
425 * @see mw.Notification#pause
428 callEachNotification(
429 $area
.children( '.mw-notification' ),
435 * Resume any paused auto-hide timers from the beginning.
436 * Only the first #autoHideLimit timers will be resumed.
438 resume: function () {
439 callEachNotification(
440 // Only call resume on the first #autoHideLimit notifications.
441 // Exclude noautohide notifications to avoid bugs where #autoHideLimit
442 // `{ autoHide: false }` notifications are at the start preventing any
443 // auto-hide notifications from being autohidden.
444 $area
.children( '.mw-notification-autohide' ).slice( 0, notification
.autoHideLimit
),
450 * Display a notification message to the user.
452 * @param {HTMLElement|HTMLElement[]|jQuery|mw.Message|string} message
453 * @param {Object} options The options to use for the notification.
454 * See #defaults for details.
455 * @return {mw.Notification} Notification object
457 notify: function ( message
, options
) {
459 options
= $.extend( {}, notification
.defaults
, options
);
461 notif
= new Notification( message
, options
);
466 preReadyNotifQueue
.push( notif
);
474 * The defaults for #notify options parameter.
477 * A boolean indicating whether the notifification should automatically
478 * be hidden after shown. Or if it should persist.
481 * An optional string. When a notification is tagged only one message
482 * with that tag will be displayed. Trying to display a new notification
483 * with the same tag as one already being displayed will cause the other
484 * notification to be closed and this new notification to open up inside
485 * the same place as the previous notification.
488 * An optional title for the notification. Will be displayed above the
489 * content. Usually in bold.
492 * An optional string for the type of the message used for styling:
493 * Examples: 'info', 'warn', 'error'.
504 * Number of seconds to wait before auto-hiding notifications.
510 * Maximum number of notifications to count down auto-hide timers for.
511 * Only the first #autoHideLimit notifications being displayed will
512 * auto-hide. Any notifications further down in the list will only start
513 * counting down to auto-hide after the first few messages have closed.
515 * This basically represents the number of notifications the user should
516 * be able to process in #autoHideSeconds time.
526 // Handle pre-ready queue.
528 while ( preReadyNotifQueue
.length
) {
529 notif
= preReadyNotifQueue
.shift();
534 mw
.notification
= notification
;
536 }( mediaWiki
, jQuery
) );