notification.js 7.0 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225
  1. /**
  2. * @license Copyright (c) 2003-2020, CKSource - Frederico Knabben. All rights reserved.
  3. * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
  4. */
  5. /**
  6. * @module ui/notification/notification
  7. */
  8. /* globals window */
  9. import ContextPlugin from '@ckeditor/ckeditor5-core/src/contextplugin';
  10. /**
  11. * The Notification plugin.
  12. *
  13. * This plugin sends a few types of notifications: `success`, `info` and `warning`. The notifications need to be
  14. * handled and displayed by a plugin responsible for showing the UI of the notifications. Using this plugin for dispatching
  15. * notifications makes it possible to switch the notifications UI.
  16. *
  17. * Note that every unhandled and not stopped `warning` notification will be displayed as a system alert.
  18. * See {@link module:ui/notification/notification~Notification#showWarning}.
  19. *
  20. * @extends module:core/contextplugin~ContextPlugin
  21. */
  22. export default class Notification extends ContextPlugin {
  23. /**
  24. * @inheritDoc
  25. */
  26. static get pluginName() {
  27. return 'Notification';
  28. }
  29. /**
  30. * @inheritDoc
  31. */
  32. init() {
  33. // Each unhandled and not stopped `show:warning` event is displayed as a system alert.
  34. this.on( 'show:warning', ( evt, data ) => {
  35. window.alert( data.message ); // eslint-disable-line no-alert
  36. }, { priority: 'lowest' } );
  37. }
  38. /**
  39. * Shows a success notification.
  40. *
  41. * By default, it fires the {@link #event:show:success `show:success` event} with the given `data`. The event namespace can be extended
  42. * using the `data.namespace` option. For example:
  43. *
  44. * showSuccess( 'Image is uploaded.', {
  45. * namespace: 'upload:image'
  46. * } );
  47. *
  48. * will fire the `show:success:upload:image` event.
  49. *
  50. * You can provide the title of the notification:
  51. *
  52. * showSuccess( 'Image is uploaded.', {
  53. * title: 'Image upload success'
  54. * } );
  55. *
  56. * @param {String} message The content of the notification.
  57. * @param {Object} [data={}] Additional data.
  58. * @param {String} [data.namespace] Additional event namespace.
  59. * @param {String} [data.title] The title of the notification.
  60. */
  61. showSuccess( message, data = {} ) {
  62. this._showNotification( {
  63. message,
  64. type: 'success',
  65. namespace: data.namespace,
  66. title: data.title
  67. } );
  68. }
  69. /**
  70. * Shows an information notification.
  71. *
  72. * By default, it fires the {@link #event:show:info `show:info` event} with the given `data`. The event namespace can be extended
  73. * using the `data.namespace` option. For example:
  74. *
  75. * showInfo( 'Editor is offline.', {
  76. * namespace: 'editor:status'
  77. * } );
  78. *
  79. * will fire the `show:info:editor:status` event.
  80. *
  81. * You can provide the title of the notification:
  82. *
  83. * showInfo( 'Editor is offline.', {
  84. * title: 'Network information'
  85. * } );
  86. *
  87. * @param {String} message The content of the notification.
  88. * @param {Object} [data={}] Additional data.
  89. * @param {String} [data.namespace] Additional event namespace.
  90. * @param {String} [data.title] The title of the notification.
  91. */
  92. showInfo( message, data = {} ) {
  93. this._showNotification( {
  94. message,
  95. type: 'info',
  96. namespace: data.namespace,
  97. title: data.title
  98. } );
  99. }
  100. /**
  101. * Shows a warning notification.
  102. *
  103. * By default, it fires the {@link #event:show:warning `show:warning` event}
  104. * with the given `data`. The event namespace can be extended using the `data.namespace` option. For example:
  105. *
  106. * showWarning( 'Image upload error.', {
  107. * namespace: 'upload:image'
  108. * } );
  109. *
  110. * will fire the `show:warning:upload:image` event.
  111. *
  112. * You can provide the title of the notification:
  113. *
  114. * showWarning( 'Image upload error.', {
  115. * title: 'Upload failed'
  116. * } );
  117. *
  118. * Note that each unhandled and not stopped `warning` notification will be displayed as a system alert.
  119. * The plugin responsible for displaying warnings should `stop()` the event to prevent displaying it as an alert:
  120. *
  121. * notifications.on( 'show:warning', ( evt, data ) => {
  122. * // Do something with the data.
  123. *
  124. * // Stop this event to prevent displaying it as an alert.
  125. * evt.stop();
  126. * } );
  127. *
  128. * You can attach many listeners to the same event and `stop()` this event in a listener with a low priority:
  129. *
  130. * notifications.on( 'show:warning', ( evt, data ) => {
  131. * // Show the warning in the UI, but do not stop it.
  132. * } );
  133. *
  134. * notifications.on( 'show:warning', ( evt, data ) => {
  135. * // Log the warning to some error tracker.
  136. *
  137. * // Stop this event to prevent displaying it as an alert.
  138. * evt.stop();
  139. * }, { priority: 'low' } );
  140. *
  141. * @param {String} message The content of the notification.
  142. * @param {Object} [data={}] Additional data.
  143. * @param {String} [data.namespace] Additional event namespace.
  144. * @param {String} [data.title] The title of the notification.
  145. */
  146. showWarning( message, data = {} ) {
  147. this._showNotification( {
  148. message,
  149. type: 'warning',
  150. namespace: data.namespace,
  151. title: data.title
  152. } );
  153. }
  154. /**
  155. * Fires the `show` event with the specified type, namespace and message.
  156. *
  157. * @private
  158. * @param {Object} data The message data.
  159. * @param {String} data.message The content of the notification.
  160. * @param {'success'|'info'|'warning'} data.type The type of the message.
  161. * @param {String} [data.namespace] Additional event namespace.
  162. * @param {String} [data.title=''] The title of the notification.
  163. */
  164. _showNotification( data ) {
  165. const event = `show:${ data.type }` + ( data.namespace ? `:${ data.namespace }` : '' );
  166. this.fire( event, {
  167. message: data.message,
  168. type: data.type,
  169. title: data.title || ''
  170. } );
  171. }
  172. /**
  173. * Fired when one of the `showSuccess()`, `showInfo()`, `showWarning()` methods is called.
  174. *
  175. * @event show
  176. * @param {Object} data The notification data.
  177. * @param {String} data.message The content of the notification.
  178. * @param {String} data.title The title of the notification.
  179. * @param {'success'|'info'|'warning'} data.type The type of the notification.
  180. */
  181. /**
  182. * Fired when the `showSuccess()` method is called.
  183. *
  184. * @event show:success
  185. * @param {Object} data The notification data.
  186. * @param {String} data.message The content of the notification.
  187. * @param {String} data.title The title of the notification.
  188. * @param {'success'} data.type The type of the notification.
  189. */
  190. /**
  191. * Fired when the `showInfo()` method is called.
  192. *
  193. * @event show:info
  194. * @param {Object} data The notification data.
  195. * @param {String} data.message The content of the notification.
  196. * @param {String} data.title The title of the notification.
  197. * @param {'info'} data.type The type of the notification.
  198. */
  199. /**
  200. * Fired when the `showWarning()` method is called.
  201. *
  202. * When this event is not handled or stopped by `event.stop()`, the `data.message` of this event will
  203. * be automatically displayed as a system alert.
  204. *
  205. * @event show:warning
  206. * @param {Object} data The notification data.
  207. * @param {String} data.message The content of the notification.
  208. * @param {String} data.title The title of the notification.
  209. * @param {'warning'} data.type The type of the notification.
  210. */
  211. }