Listeners

Listeners

A listener can be any cfc instance that subscribe to be invoked when an event fires.

Properties

Subscribing a listener require some properties to be provided:

• Event : String – Required : The event name of want to subscribe to.
• Listener : Any – Required : The listener itself. This can be full qualified cfc name ( Es: com.myapp.mylistener ) or an object instance. In case you provide a qualified path CFEM will create the listener instance for you. Please note that if you provide 100 times the same path CFEM will create 100 instance of the same listener. In this case passing on object can be a better solution.
• Method : String : When an event is fired CFEM will invoke a specific method on the listener. If you do not provide a method CFEM will look for a method that has the same name as the event that is fired. Example: if you subscribe to an event called ‘onMyEvent’ and you do not provide a method CFEM will invoke listener.onMyMethod(event).
• InitMethod : String – Default:init : If you subscribe a listener using the the full qualified path CFEM will create the instance calling the init method. If your listener has a different constructor you can set this here.
• Id : String : In some occasion you will need to remove a listener. This can be easily done if you provide to any listener a custom ID. If you do not provide it CFEM will generate a unique id based on the full qualified listener instance name + the method. Example : com.myapp.listener.mymethod.
• Priority : Numeric – Default:5 : When more listener subscribed to the same event can be very important to manipulate the order in that CFEM will follow invoking the listener. A higher number means higher priority. If 2 listener has the same priority CFEM will follow the order of subscription. By default any listener takes a priority of 5. Is good practice to follow a scale from 1 to 10.

Register a listener

Please look at the XML reference if you like to use the xml notation for configuring CFEM.

You can add listeners in more ways. With an exception that will be outlined soon a listener cannot subscribe to an event that is not yet registered; en exception will be thrown:

On init

//Provide an array of listeners to the init method:
var myListener = new com.myapp.listener(); 
var listeners = [
	{ 
	  event = 'eventName',
	  listener= myListener
	},{
	  event = 'eventName',
	  listener = 'com.myapp.listener',
	  method = 'myListenerMethod',
	  priority = 10,
	  initMethod = 'setup',
	  id = 'myListenerID'	
	}  
]
application.CFEM.init(events,listeners);

Using the addEventListenr()

//add listeners one by one
application.CFEM.addEventListener(
      event = 'eventName', 
	  listener = 'com.myapp.listener',
	  method = 'myListenerMethod',
	  priority = 10,
	  initMethod = 'setup',
	  id = 'myListenerID'
);

Register a listener via function metadata

P. This is maybe the most handy way to register listener and provide also an implicit event creation ( if event is not yet registered ).

All the properties specified for the listener can be added as metadata to a cffunction statement. CFEM will scan your app and will add listeners accordingly. CFEM will also register a new event if this is not yet known.

<cfcomponent>
	<cffunction name="onMyEvent" returntype="void" event="onMyEvent" type="com.events.myCustomEvent" priority="10">
		<cfargument name="event">
		.........................	
	</cffunction>
</cfcomponent>

You have now to Ssay to CFEM to scan for listeners. This cannot be done via the init method but is a process that must be manually invoked. Note that yoiu can provide a dir ( realtive path ) as an array od dirs to scan.

// Say to CFEM to scan for listeners
application.CFEM = new EventManager(.......);
application..CFEM.parseDirectory(dir = '/RelativePath/to/dir/to/scan', recurse = true);
//scan an array of dirs
application.CFEM = new EventManager(.......);
dirs = ['/mysppa/listeners1','/mysppa/listeners2'];
application..CFEM.parseDirectory(dirs);

The method parseDirectory takes and extra method recurse ( default to false) that say to CFEM if the provided directory has to be scan also in subfolders.

Some tips

• Do no ask CFEM to scan your full app. If it is big can be a very long proceed. Try to locate your listeners in a more organic way so that you can ask CFEM to scan just few dirs.
• Using the implicit listener subscription will not allow you to create an event flow control ( see Event Flows); you must use the XML syntax for achieving that kind of configuration.