Notifications plugin

[Piotr Jasiun]

Because of new features we need a way to show users notifications.

There are multiple types of notifications:

• information pop-up - show information for few seconds and hide it after a timeout e.g. "This type of files is not supported".
• "permanent" information - this type of notifications should not disappear after a timeout (e.g. "70% upload progress", should wait for changers),

Also:

• user should be able to hide a notification,
• it would be useful if notifications plugin handle multiple information and queue then, so if e.g., two separate plugins want to show some pop-up it will show the first one and then, after timeout (or user interaction), hide the first one and show the second notification; the different way is to show both in the same time, but plugin should ensure that the second notification will not hide first one too soon,
• because of accessibility we should probably provide two types of notifications: more and less important; user who use screen reader should be informed that "file has been uploaded", but it would be very annoying if he would hear "71% upload progress", "72% upload progress"...

[Jakub Ś]

two separate plugins want to show some pop-up it will show the first one and then, after timeout (or user interaction), hide the first one and show the second notification;

Definitely not. What if you have ten such notifications? User will have to go through all ten one by one? Man I would be sacred to make any mistake in CKE so that I didn’t get punished :).
Messages should all be shown in single popup one under another.

annoying if he would hear "71% upload progress", "72% upload progress"...

Yes thus it should only say something at 50% and 100%. IMO 25% 50% 75% 100% is also to much in case of small files. Perhaps bigger number of steps should be considered only for bigger files e.g. >=50MB.

[Piotrek Koszuliński]

See ​http://dev.ckeditor.com/ticket/11437#comment:14.

[Piotr Jasiun]

I'm working on the toast notifications for CKEditor and here an API concept.

First of all: for those who don't know how toast notification looks like this: ​http://tinyurl.com/qgsh57f

In our case it will looks like this:

The goals are:

• API should be as simple as possible,
• API should be flexible so many plugins could use toasts for very different usage,
• API should separate visual representation of toast and it's information, so the web developer could integrate editors notifications with the CMS: catch the toast event, show the information somewhere on the website and cancel in-editor notification.

To create and show a toast notification with all options user will call:

var toast = CKEDITOR.plugins.toast.make( {
	message: 'bar',
	progress: 0.23,
	type: CKEDITOR.TOAST_INFO,
	icon: 'someicon.png',
	duration: CKEDITOR.DURATION_LONG
} );

All parameters beside 'message' are optional.

Parameters:

• message - the message to be shown in the toast notification,
• progress - if is set, the progress bar is shown with the defined progress,
• type - type of the notification; every type may have different background color and different default icon; might be:
  • information (default) - "File is uploading", "ACF modified some content."
  • warning - "This type of files is not supported", "You cannot insert iframe as an image description."
  • success - "File uploaded.", "Data imported.".
• icon - let user replace the default icon and show his custom icon instead,
• duration - time after which notification is hidden; if not set the notification will be visible until user close it; there will be provided predefined constants DURATION_LONG and DURATION_SHORT but user can put any time in milliseconds.

Created toast might be updated:

toast.update( {

message: 'bar', progress: 0.23, important: true

} );

Update method use the same options with one addition: 'important'. If update is important it will be read by screen readers and shown even if user hide the original toast. By default 'important' is false.

Toast is hidden automatically after duration timeout, might be closed by user if he press "X" in the top right corner or by script:

toast.hide();

API should contain shortcut methods:

var toast = editor.makeToast( 'bar', type=TOAST_INFO, duration=(undefined|DURATION_LONG) );
// default value of duration should be 'undefined' (forever) if type is warning or DURATION_LONG otherwise.

Every toast method emit en event with all parameters. User can catch that event do something and cancel native method behavior.

Other ideas (rejected):

• close toast by clicking it; on one hand it would be useful if user could close toast by clicking anywhere on it, but toast can contains a link (ex. "ACF removed your content. <a href=...>Read more about ACF.</a>") and it would be very annoying if your miss the link.
• title - bolded title above the message. On the one hand, most toasts notifications has titles (ex. Windows 8 toasts) and some users may want to have it. Also if users will create titles using HTML in the message we will lose separation between content and visual representation. It could be optional. On the other hand usually title is needed to show the context when many application can show notifications and in our case we have only one (editor) context. Also Android toasts work fine without titles. In our case the most important think is to make toast as small as possible and toasts with titles are simple too big.

• separate content and toast mechanism; in fact we could separate toast mechanism parameters (duration, important) and the content (message, title, icon, progress). Everything what the second group parameters do is creating HTML which have to be put into the toast so the API with this separation could be:

  var toast = CKEDITOR.plugins.toast.make( {
  	content: CKEDITOR.plugins.toast.progressContent( {
  		icon: 'someicon.png',
  		message: 'bar',
  		progress: 0.23	
  	} ),
  	duration: CKEDITOR.DURATION_LONG
  } );
  

Where progressContent just create an HTML. But I believe we do not need such complication.

• I also considered ERROR type, it's common to have 'INFO', 'WARNING' and 'ERROR' types, but I don't think that toast are the best way to show editors errors; toast are used to give user some information what happen, not to report errors and in my opinion separation between 'WARNING' and 'ERROR' does not make sense in our case.
• No icon. Without icons toast would be smaller, but because content of the editor is text, mostly, toasts without icons are not visible enough.

[Wim Leers]

I read ​http://ckeditor.com/blog/CKEditor-Weekly-for-November-17-2014 and am pretty puzzled by the following:

Some members of the team are fine with continuing to call it the "Notification" plugin, while others want to call it the "Toast" plugin, since that's the common term used for such notifications.

I have 'never' seen a notification or a notification system be called 'toast' before. What's the source for calling this "common"?

[Olek Nowodziński]

Replying to Wim Leers:

I read ​http://ckeditor.com/blog/CKEditor-Weekly-for-November-17-2014 and am pretty puzzled by the following:

Some members of the team are fine with continuing to call it the "Notification" plugin, while others want to call it the "Toast" plugin, since that's the common term used for such notifications.

I have 'never' seen a notification or a notification system be called 'toast' before. What's the source for calling this "common"?

Just few examples

• ​http://en.wikipedia.org/wiki/Pop-up_notification
• ​http://developer.android.com/guide/topics/ui/notifiers/toasts.html

I just feel that "toast" is a name common among app developers but not quite popular in Web.

[Piotr Jasiun]

Replying to a.nowodzinski:

Replying to Wim Leers:

I read ​http://ckeditor.com/blog/CKEditor-Weekly-for-November-17-2014 and am pretty puzzled by the following:

Some members of the team are fine with continuing to call it the "Notification" plugin, while others want to call it the "Toast" plugin, since that's the common term used for such notifications.

I have 'never' seen a notification or a notification system be called 'toast' before. What's the source for calling this "common"?

Just few examples

• ​http://en.wikipedia.org/wiki/Pop-up_notification
• ​http://developer.android.com/guide/topics/ui/notifiers/toasts.html

I just feel that "toast" is a name common among app developers but not quite popular in Web.

One more: ​http://msdn.microsoft.com/en-us/library/windows/apps/hh779727.aspx

But we decided yesterday that 'notification' is better and I will change the name in the code as soon as we finish testing 4.4.6.

[Wim Leers]

Thanks for that. I've used notifications in Windows, Linux, Growl in older OS X versions, the native one in OS X in later versions, iOS and Qt and I've never ever seen it being called "toast". I think you did well going with just "notifications" :)

[Piotr Jasiun]

Notifications are done are ready to review. They have full test coverage, manual tests and docs.

Working on notifications I found some issues in the floating space plugin which will be reported soon.

The two changes in the API are:

• there is no icon,
• duration may be defined in the editor config (notification_duration) instead of methods parameter.

Changes in ​t/11580.

[Piotr Jasiun]

Events should be moved from editor to notificationArea.

[Piotr Jasiun]

Changes in events done. I rebased branch on the newest major. Changes in ​t/11580.

[Piotr Jasiun]

After consideration I moved notifications events back to editor, made notification area private and revert part of changes in floating space plugin. Changes in ​t/11580b.

[Piotrek Koszuliński]

I made many small changes in the plugin and its tests and we're ready to close it. During review I reported three minor issues:

• #12865,
• #12866,
• #12867.

[Piotrek Koszuliński]

Merged to major with ​git:ab14440.