QuackFuzed [ Ramblings of a Con..ColdFuzed Mind ]

ColdBox: Using 'Persist'

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

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

(Comment Moderation is enabled. Your comment will not appear until approved.)

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! :)

On 10/21/09 at 5:47 PM, Jonathan said:

so can a build a struct of event variables and pass the struct into setNextEvent?

<cffunction name="doSomething">
<!--- set the method arguments --->
<cfargument name="Event" type="coldbox.system.beans.requestContext" />

<cfscript>
var persist = structnew();
var foo = "bar";
persist.foome=event.getvalue('foome');
persist.fooyou=event.getvalue('fooyou');
setNextEvent( event="foo/bar2",varStruct="persist");
</cfscript>
</cffunction>

On 10/21/09 at 6:15 PM, Matt Quackenbush said:

@ Jonathan - I believe you'll want to remove the quotes from the varStruct argument and use dot notation for the event, but other than that, everything looks good.

setNextEvent(event="foo.bar2",varStruct=persist);

On 10/21/09 at 7:17 PM, Jonathan said:

Thanks for the response. I did that and still no luck. So I tried to do your example and I can't event get that to work. It just seems like persist doesn't work. My second event is just a cfdump of the variable or struct that I am trying to persist and it never seems to make the move.

On 10/21/09 at 7:32 PM, Matt Quackenbush said:

@ Jonathan - I'm not sure what to tell you, as it definitely "works". Does it work the way you're expecting it to? I don't know, since I don't know exactly what you're doing. I would suggest posting the relevant code to the ColdBox list (http://groups.google.com/group/coldbox).

On 10/21/09 at 9:09 PM, Jonathan said:

I'm trying to replicate your example.

<cffunction name="doThis">
<cfargument name="Event" type="coldbox.system.beans.requestContext" />
   <cfscript>
      var foo = "bar";
      event.setValue("foo", foo);
      setNextEvent(
      event: "league.didit",
      persist: "foo"
      );
   </cfscript>
</cffunction>

<cffunction name="didIt">
<cfargument name="Event" type="coldbox.system.beans.requestContext" />

   <cfscript>
      event.setView("myView");
   </cfscript>
</cffunction>

myView just does a <cfdump var="#session#"> I should see a var named foo that contains bar correct?

On 10/21/09 at 9:16 PM, Matt Quackenbush said:

@ Jonathan - No, that is incorrect. You will *not* see the variable named 'foo' in the session scope. However, if you dump #event.getCollection()# you should see it.

On 10/21/09 at 9:48 PM, Jonathan said:

Ok I tested that and it works. I was also able to pass the struct. I just expected the entire struct to travel over as the struct that I defined.

On 10/21/09 at 9:51 PM, Matt Quackenbush said:

@ Jonathan - Glad you got it figured out. :-)

On 11/4/12 at 9:36 PM, Adam Cameron said:

Hey Matt:
Thanks for this blog post. I was having difficulty getting this working, and your post here put me in the right direction (the problem was me being daft in the end, but going over what you'd said made me spot where I was being daft).

Thanks!

I'm making slow progress with Coldbox so far, but am also pleased with the number of "aha!" moments I am having as I progress, too.

Cool.

--
Adam

[Add Comment]