What the %*#@ is an Exit Handler?

Let’s talk about exit handlers. When I first came across the mention of exit handlers in the Model Glue docs, I thought, huh?

Joe illustrates with this example:

<cfset submit = viewstate.getValue(“myself”) & viewstate.getValue(“xe.translate”) />

And explains:

“So what’s with this “xe.translate” value?  ”XE” stands for “eXit Event,” and has emerged as a best practice in Model-Glue applications (because it’s taken from a best practice in Fusebox!).  It lets us reuse this view in multiple places because we determine the action page of the form at runtime, instead of hard coding it into our .CFM template.”

“So where does the value of xe.translate come from?  It’s time to learn a bit of Model-Glue XML.  (Don’t worry!  I just wrote the entire tag reference, and it’s only sixteen tags! And about five of them are just placeholders that contain other tags!)”

<event-handler name=”translationForm”>

<views>

<include name=”body” template=”frmPhrase.cfm”>

<value name=”xe.translate” value=”translationFormAction” />

</include>

</views>

</event-handler>

Let me translate what all of this meant in my mind.

$^#&$%*#*@&$*$%$)#(!@%!@$#*@(##^$><@)$)#)!**##@&@&#

OK, let’s try and spell this out in plain ol’ english.

Let’s imagine we have a standard ol’ form with a few text inputs. Imagine you need to reuse this form in three different views (.cfm pages). Each needs to submit to its own event handler.

Usually, don’t you set your form action IN the form action itself? Yes you do.

So now, we have three forms, in different places, all with different form actions, which points to your handlers that process these forms We’ll call them processSomeAction1, processSomeAction2 , and processSomeAction3).

Why not reuse this form in all three views? It’d be a bit tough! How are you going to use one form (view), and have it submit to three different actions?

EXIT HANDLERS! Damn, sounds nifty to me!

So we set it like this, in the event handler that displays your form:

<value name=”xe.AnyVarNameUDesire” value=”processSomeAction1″ />

That line says, look, we have a handler that’ll be processing this pup. It’s name is processSomeAction1. Make this variable available to any view that uses this form. Allow us to refer to it as xe.AnyVarNameDesire in the view. I could also call it xe.processPHPsucks – it doesn’t matter.

In our view, we grab the value like so:

viewstate.getValue(“xe.AnyVarNameUDesire”)

What’s the value returned? Yep, processSomeAction1.

And for the actual form’s action, you create the entire “index.cfm?event=processThisAction1″ variable like this:

<cfset submitTo = viewstate.getValue(“myself”) & viewstate.getValue(“xe.AnyVarNameUDesire”) >

Then stick it in the form:

<form action=”#submitTo#” etc………>

What does all this mean? Well, let’s go back to our original scenario. We need to reuse this form in two other views.

We know we need an event handler for a view. Here’s #2:

<event-handler name=”user.formPage2″>
<broadcasts />
<views>
<include name=”body” template=”/pages/frmReqUsername.cfm”>
<value name=”xe.AnyVarNameUDesire” value=”user.processSomeAction3″ />
</include>
</views>
</event-handler>

and #3

<event-handler name=”user.formPage3″>
<broadcasts />
<views>
<include name=”body” template=”/pages/frmReqUsername.cfm”>
<value name=”xe.AnyVarNameUDesire” value=”user.processSomeAction3″ />
</include>
</views>
</event-handler>

Wowee! We just used the same form, yet had each form submit to its own handler! That’s what I call “Sexified Code”

Coldbox has the same functionality, just implemented a little differently, since our handlers are written in CFML, not XML.

Here’s Coldbox doing the same exact thing:

<cffunction name=”frmUsername” access=”public” returnType=”void” output=”false”>

<cfargument name=”Event” type=”coldbox.system.beans.requestContext”>

<cfscript>

var rc = event.getCollection();

rc.xehDoit = “Login.processReqUsername”;// <—-exit handler

arguments.event.setView(“frmReqUsername”);

</cfscript>

</cffunction>

Luis just named this one xehDoit – eh stands for exit handler.

Then we output it in the view like so:

<form action=”#getSetting(’sesBaseURL’)#/” method=”post” name=”emailForm”>

<input type=”hidden” name=”event” value=”#rc.xehDoit#”>

Some inputs go here…..

</form>

There you have it. It’s a little more long-winded than I was planning, but I want people to better-understand what I didn’t.