Source code: ref/use.htp

<block syntax>
<use macroname [parameters ...] [noexpand]>
<... $macroname ...>
<... ${macroname} ...>
</block>

<block synopsis>

<strong>USE</strong> will expand macros that have been previously
declared with either <A HREF="set.html">SET</A> or <A
HREF="block.html">BLOCK</A>.  USE can only be used outside of other
markup tags.

<p> If you USE a block macro the value of expanded block macros will
be further parsed by htp.  This is maybe not what you want, for
example, if the use is inside a block which <a
href="expand.html">expands</a> itself. You can use the noexpand
attribute to prevent further expansion.  </p>

<p> USE will accept additional parameters, which are "local" macros
for the expanded macro.  This is only valid for <A
HREF="block.html">BLOCK</A> macros.  Macros created using <A
HREF="set.html">SET</A> cannot have parameters passed.  For
example:</p>

<htpcode option="-n">
<block stuff>
  <a href=$email>send email</a>
</block>

<set morestuff=$email>

This works:     <use stuff email="jnelson@crl.com">
But this fails: <use email>
And this fails: <use morestuff email="jnelson@crl.com">
</htpcode>

<P>
(See below for a description of the '$' operator.)  The example on
line 7 works because "stuff" has been declared as a block macro, and
the tag is passing the "email" macro to the "stuff" macro.  Line 8
fails because the "email" macro is unavailable once the block macro is
completely expanded, and cannot be passed to a SET macro.
<P>
Note that the "email" macro is available to other macros or included
files called within the "stuff" block.
<P>
Inside a markup tag, like <a href="img.html">IMG</a>, A (anchor), or
any other standard HTML or htp tag, the '$' operator must be used.
The '$' should be immediately followed by the macro name, which may or
may not be surrounded by curly braces.  When htp encounters this it
replaces the macro name by the contents of the macro without further
processing the contents.

<htpcode option="-n">
<a href="mailto:$email">mailto hyperlink</a>
<a href="http://$domain/~${username}/">another hyperlink</a>
</htpcode>
<P>
The use of curly braces is encouraged, since it is more robust and
should never cause confusion with surrounding text.  If no curly
braces are used the macro name consists either of a single punctuation
character or the maximum sequence of letters, digits, &quot;-&quot;
and &quot;_&quot; that follows it.
<P>
If a '$' character needs to be kept in the final output, and not
interpreted as a macro name, it must be escaped by another '$'
character.  This is especially true for PHP code.
<P>
If the '$' macro is the only text in the attribute's value, htp will
automatically surround it with quotation marks to prevent spaces from
delimiting the text as if it were additional markup attributes.
If the '$' macro is surrounded by other text (as in the two examples above),
quotation marks are not automatically supplied.
<P>
Note that a '$' macro can be placed anywhere in a markup tag and can
be nested.  This is valid:

<htpcode>
    <${tagName} ${attrName}=${value$ctr}>
</htpcode>

<P> The tagName macro can contain any tag name, even a self-defined
metatag.  Note that <code>$ctr</code> is expanded before the valueX
macro is expanded, so assuming that ctr was set to 1 it will expand
value1.

</BLOCK>