FCKeditor 3.x/Design and Architecture/Event Driven - Revision history

Fredck at 22:19, 2 June 2008

2008-06-02T22:19:55Z

Fredck at 23:45, 26 February 2008

2008-02-26T23:45:42Z

Fredck at 23:37, 26 February 2008

2008-02-26T23:37:49Z

Fredck at 23:36, 26 February 2008

2008-02-26T23:36:39Z

Fredck at 21:30, 17 February 2008

2008-02-17T21:30:34Z

Fredck at 20:37, 17 February 2008

2008-02-17T20:37:07Z

Fredck at 23:46, 16 February 2008

2008-02-16T23:46:01Z

Fredck: New page: One of the strongest aspects of the V3 core and API is that it will be strongly event driven. The main motivation for it is the fact that V3 is also plugin based, and the best way to creat...

2008-02-16T23:44:02Z

New page: One of the strongest aspects of the V3 core and API is that it will be strongly event driven. The main motivation for it is the fact that V3 is also plugin based, and the best way to creat...

New page

One of the strongest aspects of the V3 core and API is that it will be strongly event driven. The main motivation for it is the fact that V3 is also plugin based, and the best way to create less dependency is by providing a large set of events that can easily manipulate the behavior of the components.

== Common Events ==

There are some common patterns that can helps us identifying potential events to be implemented:

* '''Interface behavior''': whenever an important UI interaction is to be taken, an event should be fired before and after it.
* '''Data manipulation''': whenever data is to be handled, an event should be called, making it possible to manipulate the data before committing its usage.

== Naming Conventions ==

Event names should reflect the following conventions:

* it must not start with "on".
* it must be lowercased.
* it must be an action (verb) in the present tense, like "click", "open", etc.
* composed names should use the "camelCase" format, like "clickTop".
* in the normal form, it is related to an event "before" it happens. For example, the "close" event in a dialog is fired when it is to be closed, so it could be canceled and no close action is taken.
* the "after" prefix can be used for events fired after an action is taken. For example, in a dialog, the "afterClose" event could be fired after the dialog has been effectively closed. It would not be cancelable in that case.

== Event Data ==

Event listeners will receive one and only parameter, the "Event" object. This object contains the following properties:

* '''name''': the event name.
* '''sender''': the object which is publishing the event.
* '''data''': any kind of additional data. Its format and usage is event dependent.

Methods:

* '''stop()''': indicates that no further listeners are to be called.
* '''cancel()''': indicates that the event is to be cancelled (if cancelable).

== Listener Calling Scope ==

By default, listener function will be called under the scope (the "this" reference) of the event publisher.

When registering listeners, it is possible to assign a specific object to used as the scope in the listener

== Order and Priority ==

When registering an event listener, it is possible to set its priority inside the listeners queue. The priority is simply a numeric value. By default, listeners have priority level 10. Lower priority values are executed first.

Listeners that share the same priority level are executed in the registration order, so those registered first are called first.

== Event Related Functions ==

=== Event Listener Registration ===
<pre><object>.addListener( eventName, listenerFunction [,scopeObj] [,priority] )</pre>
* eventName: the event being listed.
* listenerFunction: the function to be called on event.
* scopeObj: (optional) the object to be used as the scope when calling listenerFunction. If null or not defined, "object" is the scope.
* priority: (optional) the priority level value. If not defined, it is set to 10.

=== Event Firing ===
<pre>canceled = <object>.fire( eventName [,data] )</pre>
* eventName: the event being fired.
* data: (optional) data to be passed to event listeners. It may suffer manipulation.
* canceled: a boolean indicating that a listener marked the event to be canceled.

=== Event Listeners Calling ===
<pre>listenerFunction( event )</pre>
* event: the Event object.

@@ Line 50: / Line 50: @@
 == Event Related Functions ==
-=== Event Listener Registration ===
+=== Event Listener Registration  ===
-<pre>subscription = &lt;object&gt;.addListener( eventName, listenerFunction [,scopeObj] [,listenerData] [,priority] )</pre>
+<pre>subscription = &lt;object&gt;.on( eventName, listenerFunction [,scopeObj] [,listenerData] [,priority] )</pre>
-* eventName: the event being listed.
+*eventName: the event being listed.
-* listenerFunction: the function to be called on event.
+*listenerFunction: the function to be called on event.
-* scopeObj: (optional) the object to be used as the scope when calling listenerFunction. If null or not defined, "object" is the scope.
+*scopeObj: (optional) the object to be used as the scope when calling listenerFunction. If null or not defined, "object" is the scope.
-* listenerData: (optional) extra data to be passed to the listener function in the Event object.
+*listenerData: (optional) extra data to be passed to the listener function in the Event object.
-* priority: (optional) the priority level value. If not defined, it is set to 10.
+*priority: (optional) the priority level value. If not defined, it is set to 10.
-* subscription: an opaque, read only value that can be used to remove the listener.
+*subscription: an opaque, read only value that can be used to remove the listener.
 === Event Listener Removal ===

← Older revision		Revision as of 23:46, 16 February 2008
Line 1:		Line 1:
		+	(Draft)
		+
	One of the strongest aspects of the V3 core and API is that it will be strongly event driven. The main motivation for it is the fact that V3 is also plugin based, and the best way to create less dependency is by providing a large set of events that can easily manipulate the behavior of the components.		One of the strongest aspects of the V3 core and API is that it will be strongly event driven. The main motivation for it is the fact that V3 is also plugin based, and the best way to create less dependency is by providing a large set of events that can easily manipulate the behavior of the components.

@@ Line 29: / Line 29: @@
 * '''editor''': the editor instance that holds the sender. May be the same as sender. May be null if the sender is not part of an editor instance, like a component running in standalone mode.
 * '''data''': any kind of additional data. Its format and usage is event dependent.
 Methods:

@@ Line 17: / Line 17: @@
 * it must be lowercased.
 * it must be an action (verb) in the present tense, like "click", "open", etc.
-* composed names should use the "camelCase" format, like "clickTop".
+* composed names must still be fully lowercased, like "clicktop".
 * in the normal form, it is related to an event "before" it happens. For example, the "close" event in a dialog is fired when it is to be closed, so it could be canceled and no close action is taken.
 * the "after" prefix can be used for events fired after an action is taken. For example, in a dialog, the "afterClose" event could be fired after the dialog has been effectively closed. It would not be cancelable in that case.

@@ Line 27: / Line 27: @@
 * '''name''': the event name.
 * '''sender''': the object which is publishing the event.
 * '''data''': any kind of additional data. Its format and usage is event dependent.