[docs] Re: The mysterious [output] tag ADDENDUM

[Ethan Rowe]

> All the output that went into the top_tabs and second_tabs spaces will 
> get substituted into the corresponding {{TOP_TABS}} and 
> {{SECOND_TABS}} tokens above.  Furthermore, as with the templates used 
> in the mass mailer and other places, you have some conditional logic 
> available to you:
> {{SPACE?}}blah blah{{/SPACE?}} will output "blah blah" if SPACE is 
> populated.  You could embed other tokens within this if you wanted.
> {{SPACE:}}blah blah{{/SPACE:}} will output "blah blah" if SPACE is 
> empty.  You could also embed other tokens in this.
>
> For instance, {{SPACE?}}<div 
> class="happy_space_class">{{SPACE}}</div>{{/SPACE?}}
>
> So, in the admin UI, the footer (UI_STD_FOOTER) includes a file within 
> the [unpack]...[/unpack] call as:
> [unpack]
> [include file="include/templates/ui_[either][scratch 
> display_class][or]type1[/either]"]
> [/unpack]
>
> Then look at your interchange core directory, 
> lib/UI/pages/include/templates and you'll see a bunch of ui_typeX 
> files that provide the template functionality.
>
> If you want to see the code, the critical things are:
> - lib/Vend/Page.pm sub templatize
> - code/SystemTag/unpack.coretag
> - less lib/UI/vars/UI_STD_FOOTER
> - vim lib/Vend/Parse.pm sub destination (which is basically the 
> functionality behind the output tag)
>
Neglected to mention these rather important options in the 
[unpack]...[/unpack] template:
{{:DEFAULT}} -- this substitutes in whatever you have in the default 
output stack space (i.e. the one with no name to which stuff goes when 
you're not using the [output] tag).
{{:REST}} -- this substitutes in whatever is remaining on the output 
stack, across all spaces, in the order in which the spaces were defined.

Note further that when you perform conditionals, it just checks the 
contents of an output space; but when you actually perform a 
substitution (i.e. {{SPACE}} or {{TOP_TABS}}, etc.), it undefines that 
output space.  So it's not like a variable, because you only get to use 
it once.

Finally, there's one operation in there that's just a bit more involved 
It's the {{@SPACE}}...{{/@SPACE}} option.  If you specify the [output] 
tag using the same namespace multiple times (i.e. say I call it with 
[output name=array_space] several times in a single page), each instance 
gets pushed onto the stack separately, but they can all be accessed 
using this {{@...}} option.  In this case, whatever content exists in 
the {{@ARRAY_SPACE}} .... {{/@ARRAY_SPACE}} container tokens gets 
evaluated for substitution against *each* instance of the particular 
output space specified.  This is the only way to use the output 
namespaces that have multiple instances.  So if you're using this, you 
need to keep track of how you use the [output] tag and make sure you're 
consistent in your use of that tag and the template supplied to 
[unpack]...[/unpack].

To illustrate with a truly useless example:
1. Say I have a page with:
[output name=animals]
<div><img src="aardvark.jpg" alt="Pretty little aardvark">Aardvarks are 
awfully cute.  Why not take one home with you?</div>
[output name=""]
....
[output name=animals]
<div><img src="elephant.jpg" alt="Big elephant">Elephants are awfully 
cute.  Touch it's pointy tusks and see if it's friendly.</div>
[output name=""].....

2. Now say later on I call:
[unpack]
<h1>Check out these sassy critters!</h1>
  {{@ANIMALS}}
  <h2> A critter... </h2>
  {{ANIMALS}}
  {{/@ANIMALS}}
   {{:REST}}
[/unpack]

3. This gets evaluated per instance of the "animals" output space on the 
stack.  Thus, the output of the [unpack] would be (not counting 
precision regarding whitespace):
<h1>Check out these sassy critters!</h1>
  <h2> A critter... </h2>
<div><img src="aardvark.jpg" alt="Pretty little aardvark">Aardvarks are 
awfully cute.  Why not take one home with you?</div>
  <h2> A critter .. </h2>
<div><img src="elephant.jpg" alt="Big elephant">Elephants are awfully 
cute.  Touch it's pointy tusks and see if it's friendly.</div>
....all other content would follow from the {{:REST}} substitution

4. This is where you ask "why would you want to do this?"

5. And I answer "beats me, but you can."

-- 
Ethan Rowe
End Point Corporation
ethan at endpoint.com