Passing values up from an include

following dialog from irc (names changed..) shows how to trick the system to pass values from an include to the calling page. This trick needs to be turned into real documentation.

dave: you can't pass stuff up from an include
dave: you have to use upvar
dave: ie: something like this works
michael: but, yes, the order is important. i.e., if i pass a reference to an include and hope to get/use a modified value, the value will be there *after* the <include>
dave: here is what works :)
dave: if you pass a property to a master template
dave: like this
dave: <property name="foo">@foo</property>
dave: <include src="myinclude">
dave: you can upvar #[template::adp_level] foo myfoo
dave: set myfoo "something"
dave: and something will be passed up to the master
dave: but since the code is just one big script
dave: you can't modify code that happens before
dave: we discussed quite a few times a way to work around that
dave: you could upvar something which would be available AFTER the include in the script
michael: i can do the same thing by passing in a reference
dave: yeah
dave: i just though of tha t:)
dave: cool.
michael: and the value will be there after the include
michael: so i just have to move my <property> tags to the bottom of the adp
dave: although that should be documented somehow that an include is modifying stuff in the caller
dave: i don't think you do. I can't remember. did that ages ago for gp and that code is hopefully long gone :)
michael: yeah, i tried it dave:
dave: cool.
tektubby: aha! one of the 7 mysteries of OpenACS solved.
dave: putting property at the bottom works? pretty clever
michael: when referencing the variable (set to "") before the include, i get "" on the calling page
michael: after the include, i get the modified value