htp on-line reference : USE, $

syntax

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



synopsis

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 expands itself. You can use the noexpand attribute to prevent further expansion.

USE will accept additional parameters, which are "local" macros for the expanded macro. This is only valid for BLOCK macros. Macros created using SET cannot have parameters passed. For example:

 1. <block stuff>
 2.   <a href=$email>send email</a>
 3. </block>
 4.
 5. <set morestuff=$email>
 6.
 7. This works:     <use stuff email="jnelson@crl.com">
 8. But this fails: <use email>
 9. And this fails: <use morestuff email="jnelson@crl.com">


(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.

Note that the "email" macro is available to other macros or included files called within the "stuff" block.

Inside a markup tag, like IMG, 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.

 1. <a href="mailto:$email">mailto hyperlink</a>
 2. <a href="http://$domain/~${username}/">another hyperlink</a>


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, "-" and "_" that follows it.

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.

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.

Note that a '$' macro can be placed anywhere in a markup tag and can be nested. This is valid:

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


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