QuackFuzed [ Ramblings of a Con..ColdFuzed Mind ]

ColdBox: Using 'Persist'

Posted on June 10, 2008 at 5:48 PM in ColdFusion, ColdBox

Back in the ColdBox 2.5.1 release, a new feature was added: persist. Think of it as a sort of "flash memory", allowing your application to "remember" event variables when moving the user to the next event. I was recently asked about this feature, so I figured I would make a quick post about it in an effort to help more people.

In your event handlers (controllers), it is often necessary to send the request along to another event. ColdBox provides two methods for doing this in your handlers:

1. setNextEvent() - for use with standard URLs
2. setNextRoute() - for use with SES URLs

In the docs, you'll see that there is an optional argument for these methods named 'persist'. Providing a comma-delimited list of variable names to this argument will assure you that the variables are carried over to the next event. It's very simple...

1. // for standard URLs
2. setNextEvent(
3. event: "my.event",
4. persist: "variable1,variable2,variable3"
5. );
6. //
7. // for SES URLs
8. setNextRoute(
9. route: "my/event",
10. persist: "variable1,variable2,variable3"
11. );

In this example, variable1, variable2, and variable3 will still exist in my.event when the request gets there. Schweeeeet!! But, there is one MAJOR point to make, so pay really close attention here...

In order to persist variables between events, they *must* exist in the event object, or request collection.

In other words, these are *not* var'd variables within the event method.

1. <cffunction name="doSomething">
2. <!--- set the method arguments --->
3. <cfargument name="Event" type="coldbox.system.beans.requestContext" />
5. <cfscript>
6. var foo = "bar";
7. setNextRoute(
8. route: "foo/bar2",
9. persist: "foo"
10. );
11. </cfscript>
12. </cffunction>

In the example above, we're telling setNextRoute() to persist an event variable named 'foo'. As you can see, 'foo' is a var'd variable within the event method. This example will not result in 'foo' existing when the request gets to the next event.

The 'persist' argument is valid for event variables only, as shown in the next example.

1. <cffunction name="doSomething">
2. <!--- set the method arguments --->
3. <cfargument name="Event" type="coldbox.system.beans.requestContext" />
5. <cfscript>
6. var foo = "bar";
7. event.setValue("foo", foo);
8. setNextRoute(
9. route: "foo/bar2",
10. persist: "foo"
11. );
12. </cfscript>
13. </cffunction>

As you can see in this example, 'foo' exists in the event itself, so it will be passed along to the next event.

Just wanted to pass that along, since it seems to be a common misconception.

Comments

On 6/10/08 at 7:33 PM, Sana said:

@Matt really great explanation , event variables can persist in session/client scope. Client scope for clustered environment applications.
just one setting to change then framework will manage every thing for you.

<Setting name="FlashURLPersistScope" value="client" />

more info on coldbox wiki
http://ortus.svnrepository.com/coldbox/trac.cgi/wi...

On 6/17/08 at 9:23 AM, Dave Shuck said:

It is good to see that ColdBox has added this. It appears to be an implementation of one of my favorite features to come out of the Mach-II 1.5 release last year. Being able to easily have complex data waiting for you on the other side of a redirect comes is quite useful.

On 6/17/08 at 9:30 AM, Dave Shuck said:

Wow... convergence of two thoughts before my first cup of coffee. Let me try that again:

'...it comes in handy' OR '...is quite useful'

Your choice! :)

[Add Comment]