CKEDITOR.plugins.notificationAggregator

// Declare one aggregator that will be used for all tasks.
var aggregator;

// ...

// Create a new aggregator if the previous one finished all tasks.
if ( !aggregator || aggregator.isFinished() ) {
    // Create a new notification aggregator instance.
    aggregator = new CKEDITOR.plugins.notificationAggregator( editor, 'Loading process, step {current} of {max}...' );

    // Change the notification type to 'success' on finish.
    aggregator.on( 'finished', function() {
        aggregator.notification.update( { message: 'Done', type: 'success' } );
    } );
}

// Create 3 tasks.
var taskA = aggregator.createTask(),
    taskB = aggregator.createTask(),
    taskC = aggregator.createTask();

// At this point the notification contains a message: "Loading process, step 0 of 3...".

// Let's close the first one immediately.
taskA.done(); // "Loading process, step 1 of 3...".

// One second later the message will be: "Loading process, step 2 of 3...".
setTimeout( function() {
    taskB.done();
}, 1000 );

// Two seconds after the previous message the last task will be completed, meaning that
// the notification will be closed.
setTimeout( function() {
    taskC.done();
}, 3000 );

Properties

• readonly

  editor : editorCKEDITOR.plugins.notificationAggregator#editor

  See source

• readonly

  notification : notification | nullCKEDITOR.plugins.notificationAggregator#notification

  See source

  Notification created by the aggregator.

  The notification object is modified as aggregator tasks are being closed.

• private

  _doneTasks : NumberCKEDITOR.plugins.notificationAggregator#_doneTasks

  See source

  Stores the count of tasks done.

• private

  _doneWeights : NumberCKEDITOR.plugins.notificationAggregator#_doneWeights

  See source

  Stores the sum of done weights for all contained tasks.

• private

  _message : templateCKEDITOR.plugins.notificationAggregator#_message

  See source

  A template for the notification message.

  The template can use the following variables:

  • {current} – The number of completed tasks.
  • {max} – The number of tasks.
  • {percentage} – The progress (number 0-100).

• private

  _singularMessage : template | nullCKEDITOR.plugins.notificationAggregator#_singularMessage

  See source

  A template for the notification message used when only one task is loading.

  Sometimes there might be a need to specify a special message when there is only one task loading, and to display standard messages in other cases.

  For example, you might want to show a message "Translating a widget" rather than "Translating widgets (1 of 1)", but still you would want to have a message "Translating widgets (2 of 3)" if more widgets are being translated at the same time.

  Template variables are the same as in _message.

• private

  _tasks : task[]CKEDITOR.plugins.notificationAggregator#_tasks

  See source

  Array of tasks tracked by the aggregator.

• private

  _totalWeights : NumberCKEDITOR.plugins.notificationAggregator#_totalWeights

  See source

  Stores the sum of declared weights for all contained tasks.

Static properties

• mixed static

  useCapture : BooleanCKEDITOR.plugins.notificationAggregator#useCapture

  See source

Methods

• constructor( editor, message, [ singularMessage ] ) → notificationAggregatorCKEDITOR.plugins.notificationAggregator#constructor

  See source

  Creates a notification aggregator instance.

  Parameters

  editor : editor

  message : String

  The template for the message to be displayed in the notification. The template can use the following variables:

  • {current} – The number of completed tasks.
  • {max} – The number of tasks.
  • {percentage} – The progress (number 0-100).

  [ singularMessage ] : String | null

  An optional template for the message to be displayed in the notification when there is only one task remaining. This template can use the same variables as the message template. If null, then the message template will be used.

  Defaults to null

  Returns

  notificationAggregator

  capture()CKEDITOR.plugins.notificationAggregator#capture

  See source

  Register event handler under the capturing stage on supported target.

  createTask( [ options ] ) → taskCKEDITOR.plugins.notificationAggregator#createTask

  See source

  Creates a new task that can be updated to indicate the progress.

  Parameters

  [ options ] : Object

  Options object for the task creation.

  Returns

  task

  An object that represents the task state, and allows for its manipulation.

  define( name, meta )CKEDITOR.plugins.notificationAggregator#define

  See source

  Predefine some intrinsic properties on a specific event name.

  Parameters

  name : String

  The event name

  meta : Object

  fire( eventName, [ data ], [ editor ] ) → Boolean | ObjectCKEDITOR.plugins.notificationAggregator#fire

  See source

  Fires an specific event in the object. All registered listeners are called at this point.

  someObject.on( 'someEvent', function() { ... } );
  someObject.on( 'someEvent', function() { ... } );
  someObject.fire( 'someEvent' );             // Both listeners are called.
  
  someObject.on( 'someEvent', function( event ) {
      alert( event.data );                    // 'Example'
  } );
  someObject.fire( 'someEvent', 'Example' );
  

  Parameters

  eventName : String

  The event name to fire.

  [ data ] : Object

  Data to be sent as the CKEDITOR.eventInfo.data when calling the listeners.

  [ editor ] : editor

  The editor instance to send as the CKEDITOR.eventInfo.editor when calling the listener.

  Returns

  Boolean | Object

  A boolean indicating that the event is to be canceled, or data returned by one of the listeners.

  fireOnce( eventName, [ data ], [ editor ] ) → Boolean | ObjectCKEDITOR.plugins.notificationAggregator#fireOnce

  See source

  Fires an specific event in the object, releasing all listeners registered to that event. The same listeners are not called again on successive calls of it or of fire.

  someObject.on( 'someEvent', function() { ... } );
  someObject.fire( 'someEvent' );         // Above listener called.
  someObject.fireOnce( 'someEvent' );     // Above listener called.
  someObject.fire( 'someEvent' );         // No listeners called.
  

  Parameters

  eventName : String

  The event name to fire.

  [ data ] : Object

  Data to be sent as the CKEDITOR.eventInfo.data when calling the listeners.

  [ editor ] : editor

  The editor instance to send as the CKEDITOR.eventInfo.editor when calling the listener.

  Returns

  Boolean | Object

  A booloan indicating that the event is to be canceled, or data returned by one of the listeners.

  getDoneTaskCount() → NumberCKEDITOR.plugins.notificationAggregator#getDoneTaskCount

  See source

  Returns

  Number

  Returns the number of tasks done.

  getPercentage() → NumberCKEDITOR.plugins.notificationAggregator#getPercentage

  See source

  Returns a number from 0 to 1 representing the done weights to total weights ratio (showing how many of the tasks are done).

  Note: For an empty aggregator (without any tasks created) it will return 1.

  Returns

  Number

  Returns the percentage of tasks done as a number ranging from 0 to 1.

  getTaskCount() → NumberCKEDITOR.plugins.notificationAggregator#getTaskCount

  See source

  Returns

  Number

  Returns a total tasks count.

  hasListeners( eventName ) → BooleanCKEDITOR.plugins.notificationAggregator#hasListeners

  See source

  Checks if there is any listener registered to a given event.

  var myListener = function() { ... };
  someObject.on( 'someEvent', myListener );
  alert( someObject.hasListeners( 'someEvent' ) );    // true
  alert( someObject.hasListeners( 'noEvent' ) );      // false
  

  Parameters

  eventName : String

  The event name.

  Returns

  Boolean

  isFinished() → BooleanCKEDITOR.plugins.notificationAggregator#isFinished

  See source

  Returns

  Boolean

  Returns true if all notification tasks are done (or there are no tasks at all).

  on( eventName, listenerFunction, [ scopeObj ], [ listenerData ], [ priority ] ) → ObjectCKEDITOR.plugins.notificationAggregator#on

  See source

  Registers a listener to a specific event in the current object.

  someObject.on( 'someEvent', function() {
      alert( this == someObject );        // true
  } );
  
  someObject.on( 'someEvent', function() {
      alert( this == anotherObject );     // true
  }, anotherObject );
  
  someObject.on( 'someEvent', function( event ) {
      alert( event.listenerData );        // 'Example'
  }, null, 'Example' );
  
  someObject.on( 'someEvent', function() { ... } );                       // 2nd called
  someObject.on( 'someEvent', function() { ... }, null, null, 100 );      // 3rd called
  someObject.on( 'someEvent', function() { ... }, null, null, 1 );        // 1st called
  

  Note: CKEditor's event system has a limitation that one function cannot be used as a listener for the same event more than once. Hence, to reuse it with multiple listeners, it should be wrapped into additional wrapper function:

  function listener( evt ) { ... };
  
  someObject.on( 'someEvent', function() {
      listener();
  } );
  
  someObject.on( 'someEvent', function( evt ) {
      listener( evt );
  } );
  

  Parameters

  eventName : String

  The event name to which listen.

  listenerFunction : Function

  The function listening to the event. A single CKEDITOR.eventInfo object instanced is passed to this function containing all the event data.

  [ scopeObj ] : Object

  The object used to scope the listener call (the this object). If omitted, the current object is used.

  [ listenerData ] : Object

  Data to be sent as the CKEDITOR.eventInfo.listenerData when calling the listener.

  [ priority ] : Number

  The listener priority. Lower priority listeners are called first. Listeners with the same priority value are called in registration order.

  Defaults to 10

  Returns

  Object

  An object containing the removeListener function, which can be used to remove the listener at any time.

  once()CKEDITOR.plugins.notificationAggregator#once

  See source

  Similiar with on but the listener will be called only once upon the next event firing.

  CKEDITOR.event.on

  removeAllListeners()CKEDITOR.plugins.notificationAggregator#removeAllListeners

  See source

  Remove all existing listeners on this object, for cleanup purpose.

  removeListener( eventName, listenerFunction )CKEDITOR.plugins.notificationAggregator#removeListener

  See source

  Unregisters a listener function from being called at the specified event. No errors are thrown if the listener has not been registered previously.

  var myListener = function() { ... };
  someObject.on( 'someEvent', myListener );
  someObject.fire( 'someEvent' );                 // myListener called.
  someObject.removeListener( 'someEvent', myListener );
  someObject.fire( 'someEvent' );                 // myListener not called.
  

  Parameters

  eventName : String

  The event name.

  listenerFunction : Function

  The listener function to unregister.

  update()CKEDITOR.plugins.notificationAggregator#update

  See source

  Triggers an update on the aggregator, meaning that its UI will be refreshed.

  When all the tasks are done, the finished event is fired.

  private

  _addTask( options ) → taskCKEDITOR.plugins.notificationAggregator#_addTask

  See source

  Creates a CKEDITOR.plugins.notificationAggregator.task instance based on options, and adds it to the task list.

  Parameters

  options : Object

  Options object coming from the createTask method.

  Returns

  task

  private

  _createNotification() → notificationCKEDITOR.plugins.notificationAggregator#_createNotification

  See source

  Creates a notification object.

  Returns

  notification

  private

  _getNotificationMessage() → StringCKEDITOR.plugins.notificationAggregator#_getNotificationMessage

  See source

  Returns a message used in the notification.

  Returns

  String

  private

  _onTaskDone( evt )CKEDITOR.plugins.notificationAggregator#_onTaskDone

  See source

  A listener called on the CKEDITOR.plugins.notificationAggregator.task.done event.

  Parameters

  evt : eventInfo

  Event object of the CKEDITOR.plugins.notificationAggregator.task.done event.

  private

  _onTaskUpdate( evt )CKEDITOR.plugins.notificationAggregator#_onTaskUpdate

  See source

  A listener called on the CKEDITOR.plugins.notificationAggregator.task.update event.

  Parameters

  evt : eventInfo

  Event object of the CKEDITOR.plugins.notificationAggregator.task.update event.

  private

  _removeTask( task )CKEDITOR.plugins.notificationAggregator#_removeTask

  See source

  Removes a given task from the _tasks array and updates the UI.

  Parameters

  task : task

  Task to be removed.

  private

  _updateNotification()CKEDITOR.plugins.notificationAggregator#_updateNotification

  See source

  Updates the notification content.

  Static methods

  • mixed static

    implementOn( targetObject )CKEDITOR.plugins.notificationAggregator#implementOn

    See source

    Implements the CKEDITOR.event features in an object.

    var myObject = { message: 'Example' };
    CKEDITOR.event.implementOn( myObject );
    
    myObject.on( 'testEvent', function() {
        alert( this.message );
    } );
    myObject.fire( 'testEvent' ); // 'Example'
    

    Parameters

    targetObject : Object

    The object into which implement the features.

    Events

    • finished( evt )CKEDITOR.plugins.notificationAggregator#finished

      See source

      Fired when all tasks are done. When this event occurs, the notification may change its type to success or be hidden:

      aggregator.on( 'finished', function() {
          if ( aggregator.getTaskCount() == 0 ) {
              aggregator.notification.hide();
          } else {
              aggregator.notification.update( { message: 'Done', type: 'success' } );
          }
      } );
      

      Parameters

      evt : eventInfo