[[PageOutline]]

= Event API =

When a function in a controller is called as a result of a <message-listener> tag, it is passed an instance of the !ModelGlue.unity.eventrequest.!EventContext CFC.

This CFC contains a series of functions known as the Event API that are useful to getting and setting values in the viewstate as well as event-related utilities.

== !AddResult(name:string) ==

Adds a result by the given name. If a <result> tag exists in the currently executing <event-handler> whose NAME attribute matches the value passed, the <event-handler> declared in its DO attribute will be added to the request.

==== Returns: ====

Void

==== Arguments: ====

Name (Required) - The name of the result to add

== !ArgumentExists(string:name) ==

==== Description: ====

Does a value of the given name exist in the current message tag's arguments block?

==== Returns: ====

Boolean

==== Arguments: ====

Name (required) - The name of the argument to check

== Forward(eventhandler:string [, append:list]) ==

==== Description: ====

Immediately redirects the request to the event handler named. All values in the viewstate are maintained across the redirect if session is enabled.

==== Returns: ====

Void. The function call never completes - a <cflocation> interrupts its execution.

==== Arguments: ====

!EventHandler (Required) - The name of the event handler to redirect to

Append (Optional) - Will append the list of values passed in append to the resultant URL.

==== Example: ====

{{{
<!--- Results in a url with a query string of ?event=article.view&articleId=2 --->
<cfset arguments.event.setValue("articleId", 2) />
<cfset arguments.event.forward("article.view", "articleId") />
}}}

== !GetAllArguments() ==

==== Description: ====

Returns the structure that contains all argument members ''by reference''.

==== Returns: ====

Struct

==== Arguments: ====

None

== !GetAllValues() ==

==== Description: ====

Returns the structure that contains all viewstate members ''by reference''.

==== Returns: ====

Struct

==== Arguments: ====

None

== !GetArgument(name:string [, default:any]) ==

==== Description: ====

Returns a value from the current message tag's arguments block.

==== Returns: ====

Any

==== Arguments: ====

Name (required) - The name of the argument to retrieve

Default (optional) - If the argument does not exist, a default value to return. It is ''not'' set into the argument collection - the collection is read-only.

==== Example: ====

{{{
<!-- ModelGlue.xml --->
<event-handler name="argumentExample">
    <broadcasts>
        <message name="example">
            <argument name="someArgument" value="someValue" />
        </message>
    </broadcasts>
</event-handler>

<!--- In a message listener function --->
<cfset var argumentValue = arguments.event.getArgument("someArgument") />
}}}

== !GetValue(name:string [, default:any]) ==

==== Description: ====

Returns a value from the viewstate, such as a form or url variable.

==== Returns: ====

Any

==== Arguments: ====

Name (required) - The name of the value to retrieve

Default (optional) - If the value does not exist, a default value to set into the viewstate and then return

== !GetView(name:string) ==

==== Description: ====

Returns the rendered content of a view.

==== Returns: ====

String

==== Arguments: ====

Name (required) - The name of the view to retrieve

== !MakeEventBean(type:any, [fields:list]) ==

==== Description: ====

Loops over a CFC instance, looking for any methods whose names start with set.  For any setter methods where a like-named value exists in the viewstate, the setter will be called, passing this value.

==== Returns: ====

CFC Instance

==== Arguments: ====

Type (Required) - If a string is passed, it will instantiate a CFC of the type passed and attempt to call a function named "init" if one exists.  If a CFC instance is passed, it will use the instance.

Fields (Optional) - If a list of fields is passed, it will only attempt to set the properties listed.

== !SetValue(name:string, value:any) ==

==== Description: ====

Sets a value into the viewstate.

==== Returns: ====

Void

==== Arguments: ====

Name (required) - The name of the value to set

Value (required) - The value to store in the viewstate.


== Trace(name:string, value:any) ==

==== Description: ====

Adds the value to the debugging trace and gives it the name passed. If a complex value is passed, the result of its <cfdump> is displayed.

==== Returns: ====

Void

==== Arguments: ====

Name (Required) - A label to identify the value in the debugging trace

Value (Required) - The value to display in the debugging trace. If a complex value is passed, the result of its <cfdump> is displayed.

== !ValueExists(string:name) ==

==== Description: ====

Does a value of the given name exist in the viewstate?

==== Returns: ====

Boolean

==== Arguments: ====

Name (required) - The name of the value to check