[[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.gesture.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

----
== !AddTraceStatement(name:string, value:any [, tag:string, traceType:string]) ==

==== 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.

Tag (optional) - A string value that is displayed underneath the Value. Model Glue will write different values here depending on the stage of the request. For example when a event handler is executed and written to the log the value that is displayed in the tag is the event handler name.

!TraceType (optional) - If present the traceType will change the background color of the row in the debugging output. This value can be any string, but the default logRenderer will only colorize the log line if the value is either 'USER' or 'WARNING'. 

----
== !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

----
== !CopyToScope(scope:struct, listOfEventKeys:string [,arrayOfDefaults:array]) ==

==== Description: ====

Populates the scope with event values matched in the listOfEventKeys, and uses an optional array to set default values according to position. This method can replace many Event.getValue() statements with a single line of code.


==== Returns: ====

Void

==== Arguments: ====

Scope: (required) - A struct or component instance to be populated.

ListOfEventKeys: (required) - a comma delimited list of keys to look for in the event. Any key not found will be defaulted with an empty string, or if the arrayOfDefaults was passed, the value of the array position matching the position of the current list item.

ArrayOfDefaults: (optional) - An array of values used as defaults. The first position in the array is the default for the first position in the listOfEventKeys list. This array does not have to have the same length as the listOfEventKeys and if no array item is found the empty string will be used as the default.

==== Example: ====

{{{
<!-- Someview.cfm --->

<cfset defaultArray = ["DefaultForFoot", "DefaultForHand"] />
<cfset event.copyToScope(variables, "foot,hand,xe.nested", defaultArray) />

<!--- the variables scope now contains foot:DefaultForFoot, hand:DefaultForHand, xe.nested:"" --->
}}}

----
== Forward(eventName:string [, append:list, preserveState:boolean, anchor:string, addToken:boolean]) ==

==== Description: ====

Immediately redirects the request to the event handler named. All values in the viewstate are maintained if preserveState is set to true.

==== Returns: ====

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

==== Arguments: ====

!EventName (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.

!PreserveState (optional) - Preserves the event state across the redirect to the new event.

Anchor (optional) - The anchor literal for the resultant URL.

!AddToken (optional) - If true will add session tokens to the 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 event context, 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 event context 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

----
== !LinkTo(eventName:string, [append:list], [anchor:string]) ==

==== Description: ====

Creates a link with information from Model-Glue such as the event name, any desired parameters along with respective values. The Link Manager is designed to abstract URL formatting so that SES URLS and other custom linking strategies can be handled by ModelGlue. You can define your own LinkManager by providing a component definition in your application specific ColdSpring.xml confguration by using the Bean ID: 'modelglue.urlManager'. At a minimum, your component must meet the method definitions of /ModelGlue/gesture/eventrequest/url/UrlManager.cfc.

==== Returns: ====

A link. This replaces the following construct from the Pre-MG:3 application architecture.
{{{
<cfset someLink = myself & "SomeEvent" /> 
}}}


==== Arguments: ====

EventName (Required) - Name of the event to forward to.

Append (Optional) A list of event values to append to the link.

Anchor (Optional) Any anchor text for the link.

==== Example: ====

For a given URL: 
{{{
model-glue.com?event=EntryDisplay&entryID=75
}}}
and a given linking statement: 
{{{
<cfset handleEntryClicked = event.linkTo( "Entry.Form", "entryID" )/>
}}}

The value of handleEntryClicked after processing will be:

http://model-glue.com/index.cfm?event=Entry.Form&EntryID=75

----
== !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.


----
== !ValueExists(name:string) ==

==== Description: ====

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

==== Returns: ====

Boolean

==== Arguments: ====

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