[Bese-devel] Re: Meaning of <param:contents> ?

Thu Apr 20 12:43:33 UTC 2006

Friedrich Dominicus <frido at q-software-solutions.de> writes:

> Ok, what's the task of this tag?

it's part of the tal:include mechanism, it provides one mechanism
(there are two) to pass data from the including page to the included
page.

example:

let's pretend we have template.tal (this is very similar to an actual
tal file of mine):

------------------------------------------------------------------------
<html>
  <head>
    <title tal:content="$title">title goes here</title>
  </head>
</html>
------------------------------------------------------------------------

notice how the template access the title variable. param: tags and
attributes are the means to extend the included pages'
environement. here's index.tal which uses this template:

------------------------------------------------------------------------
<tal:include tal:name="template.tal">
  <param:title><b>home</b> page</param:title>
</tal:include>
------------------------------------------------------------------------

when calling template.tal the current environemnt (whetever was used
for index.tal) will be extended with the symbol title (the string
"TITLE" will be interned in index.tal's package) bound to the content
of the param:title tag. (nb: had the tag param:foobar been used we
would be binding the symbol foobar and not title). for param: tags the
content of the tag is 'evaluated' immediatly and the resulting string
is used as the value. in this case title would be bound to the string
"<b>home</b> page".

so, that's the first mechanism, the problem is that it's limited to
pasing text to the included template. it often happens that we want to
pass lisp objects. if we use a param: _attribute_, like this:

------------------------------------------------------------------------
<tal:include tal:name="template.tal" param:foo="(slot-value $component 'foo)">
  <param:title><b>home</b> page</param:title>
</tal:include>
------------------------------------------------------------------------

then the symbol foo will be bound to the value returned by the form
(slot-value $component 'foo). i use this mechanism with tal:dolist
when i have three tables on different pages which show the same data
but on different objects.

while i'm on the subject:

tal:name worked great for a really long time (about 2 years) but
recently i needed to include different files depending on user
input. i've recently added a tal:name-expression attribute. it has the
same effect as tal:name (chooses which template to include) but
'evaluates' its value:

<tal:include tal:name-expression="details/${ (class-name (class-of (datum $component))) }"
             param:datum="(datum $component)"/>

this will include a different file in the details directory, depending
on the class of the datum slot, and pass the datum object itself to
the included file.

hth.
-- 
-Marco
Ring the bells that still can ring.
Forget the perfect offering.
There is a crack in everything.
That's how the light gets in.
	-Leonard Cohen