Mate Flex Framework

(This tag must be placed inside an <EventHandlers> tag, and Injectors tag or a <MessageHandlers> tag)

EventAnnouncer allows you to dispatch events from an EventHandlers block. When the list of handlers is executed, it will create an event of the class specified in the "generator" attribute. It will then add any properties to the newly created event and dispatch it. You can pass properties to the event that come from a variety of sources, such as the original event that triggered the list execution, a server result object, or any other value.

Example:

<EventAnnouncer generator="MyEventClass" type="myEventType">
   
   <Properties myProperty="myValue" myProperty2="100"/>

</EventAnnouncer>

The above example would be the same as doing the following in ActionScript code:

var myEvent:MyEventClass = new MyEventClass("myEventType", true);
myEvent.myProperty = "myValue";
myEvent.myProperty2 = 100;
dispatchEvent(myEvent);

The main difference is that in the case of the EventAnnouncer, the event is dispatched whenever the event handlers list is run and in the order specified in the list.

Attributes

generator

required

The generator attributes specifies what class of event should be instantiated and dispatched. If this attribute is not specified, then a DynamicEvent will be generated.

Suppose you have a custom event called "MyEvent" in the package com.yourdomain.events. You can specify a complete path to com.yourdomain.events.MyEvent:

<EventAnnouncer
   generator="com.yourdomain.events.MyEvent"
   type="myEventType" />

Generally, you may want to use a binding to specify the class name. Assuming you have an import statement like this in your Event Map:

import com.yourdomain.events.MyEvent;

or simply:

import com.yourdomain.events.*;

You can then declare your event class using bindings:

<EventAnnouncer

	generator="{MyEvent}" 
	type="myEventType" />

The advantage of using this syntax is that if you use Flex Builder, it will allow you to navigate to your MyEvent.as file by pressing Command and clicking on the class name (MyEvent) inside the generator attribute.

type

required

The type attribute specifies the event type you want to dispatch. Suppose you have an event class definition as follows:

public class MyEvent extends Event {
   public static const MY_EVENT_TYPE:String = "myEventType";
   public var myProperty:String;
   public var myProperty2:uint;
}

You can then specify the type attribute with the event type literal string:

<EventAnnouncer
	generator="{MyEvent}"
	type="myEventType" />

Or you can use the binding syntax again:

<EventAnnouncer
	generator="{MyEvent}"
	type="{MyEvent.MY_EVENT_TYPE}" />

This will allow the compiler to check that the type you specified exists.

constructorArguments

Object or Array

If your event has a constructor signature that differs from the default Flash Event constructor, you need to specify the parameters with this attribute.

See Passing Arguments for more information.

bubbles

Although you can specify the event's bubbles property, whether you set it to true or false will have little effect, as the event will be dispatched from the Mate Dispatcher itself (the Application by default).

cancelable

Boolean

Default value: true

Indicates whether the behavior associated with the event can be prevented.

Inner tags

Properties

You can add properties to your event by using the SmartProperty tag inside the EventAnnouncer tag. The properties to set in your event must be public.

As attributes of the Properties tag, you can specify the names of your properties and set the values of those properties by setting the value of those attributes.

Suppose you are creating an event of the class shown previously (MyEvent) and assigning values for its two properties (myProperty and myProperty2):

<EventAnnouncer generator="{MyEvent}" type="{MyEvent.MY_EVENT_TYPE}">
	<Properties
		myProperty="myValue" 
		myProperty2="100" />
</EventAnnouncer>

Besides specifying literal values, you can assign values coming from the event that triggered the event handlers list execution:

<EventAnnouncer generator="{MyEvent}" type="{MyEvent.MY_EVENT_TYPE}">
	<Properties
		myProperty="{event.userName}" 
		myProperty2="{event.age}" />
</EventAnnouncer>

This assumes that the original event contained a userName property and an age property.

If this event announcer tag is inside a <resultHandlers> block that originated from any service tag (RemoteObjectInvoker, WebServiceInvoker, HTTPServiceInvoker), you can also pass values coming from the server result:

<RemoteObjectInvoker .....service attributes....>
	<resultHandlers>
		<EventAnnouncer generator="{MyEvent}" 
			type="{MyEvent.MY_EVENT_TYPE}">

			<Properties
				myProperty="{resultObject.userName}" 
				myProperty2="{resultObject.age}" />
		</EventAnnouncer>
	
	</resultHandlers>
</RemoteObjectInvoker>

This assumes the server returned an object that contained a userName property and an age property.

If this event builder tag is inside an <faultSequence> tag that originated from a Service builder tag, you can also pass values coming from the server fault. This comes in handy when you want to handle possible server errors.

<RemoteObjectInvoker .....service attributes....>
	<faultHandlers>
		<EventAnnouncer generator="{MyEvent}" 
			type="{MyEvent.MY_EVENT_TYPE}">

			<Properties
				myProperty="{fault.faultDetail}" 
				myProperty2="{fault.errorID}" />
		</EventAnnouncer>
	
	</faultHandlers>
</RemoteObjectInvoker>

You can also use the complete resultObject, fault or data as a property depending on what your event properties are.

For example, if the server returned a string, you would be able to set the event property "myProperty" with the server result:

<RemoteObjectInvoker .....service attributes....>
	<resultHandlers>
		<EventAnnouncer generator="{MyEvent}" 
			type="{MyEvent.MY_EVENT_TYPE}">

			<Properties
				myProperty="{resultObject}" 
		</EventAnnouncer>
	
	</resultHandlers>
</RemoteObjectInvoker>

You can also use the service fault or the sequence data.

<RemoteObjectInvoker .....service attributes....>
	<faultHandlers>
		<EventAnnouncer generator="{MyEvent}" 
			type="{MyEvent.MY_EVENT_TYPE}">

			<Properties
				myProperty="{fault}" 
		</EventAnnouncer>
	
	</faultHandlers>
</RemoteObjectInvoker>

<EventAnnouncer generator="{MyEvent}" type="{MyEvent.MY_EVENT_TYPE}">

	<Properties myProperty="{data}" 
</EventAnnouncer>