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.

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