Source code: ref/expand.htp


<block body>

<h2> The <a name="global"><code>global</code></a> attribute</h2>

<p>Normally when you define a macro it is only defined in the current
scope.  A scope is for example the definition of a metatag.  Once the
definition is expanded and the metatag has finished the macro is
automatically removed.  In some cases you want to define a macro
inside a metatag and use it later.  You can do this with the
<strong><code>global</code></strong> attribute that you can add to
<manlink>set</manlink>,
<manlink>inc</manlink>,
<manlink>block</manlink>,
<manlink>def</manlink>, and
<manlink>blockdef</manlink> tags.</p>

<h2> The <a name="expand"><code>expand</code></a> attribute</h2> <p>The
<strong><code>expand</code></strong> attribute is not a tag of its own
but is an attribute of all block tags even metatags defined with
the <code>blockdef</code> macro.  Normally htp uses a lazy evaluation
strategy, i.e. it expands htp tags, metatags and macros when the HTML
document is written not when they're stored into block macros.  When
you use a macro defined with the <code>blockdef</code> tag the html
code between the tags is just copied literally into the macro named
<code>block</code>, without any expansion going on.</p>

<p>However, if the block tag is marked with the <code>expand</code>
modifier it is expanded immediately.  This is useful if you want to
store something in a block macro, that depends on the current value of
another macro.  This other macro may no longer have the correct value
when the macro is expanded.  Here is some code that demonstrate when
the htp tags are expanded: </P>

<htpcode option="-n">
  <set time="0">
  <block name=a>
    a is expanded at time <use time>.
  </block>
  <block name=b expand>
    b is expanded at time <use time>.
  </block>
  <set time="1">
  <use a>
  <use b>
  contents of a: <use a noexpand>
  contents of b: <use b noexpand>
  <block name=c expand>
    c is expanded at time <use time>; <use a>
  </block>
  <block name=d expand>
    d is expanded at time <use time>; <use a noexpand>
  </block>
  <block name=e>
    e is expanded at time <use time>; <use a noexpand>
  </block>
  <set time="2">
  <block name=a>
    a is defined for the 2nd time <use time>.
  </block>
  <use c>
  <use d>
  <use e>
</htpcode>

This produces the following:
<htpcode>
    a is expanded at time 1.
    b is expanded at time 0.
  contents of a:   a is expanded at time <use time>.
  contents of b:   b is expanded at time 0.
    c is expanded at time 1;   a is expanded at time 1.
    d is expanded at time 1;   a is expanded at time 2.
    e is expanded at time 2;   a is defined for the 2nd time <use time>.
</htpcode>

<P>
When block a and block b are defined in lines 2-7 the contents of a
are taken literally, however, the contents for b are already expanded
so the macro <code>time</code> is evaluated.  So a is expanded when it
is used, while the contents of b are already expanded.
</P>

<P>In line 10 and 12 the <manlink
href="use.html"><code>use</code></manlink> tag is used with the
<code>noexpand</code> attribute which prevents the expansion of the
macro value.  Here it is used to show you what the value of the block
macros really is.
</P>

<p>A more important reason to use the <code>noexpand</code> attribute
is to prevent double expansion and to restore the original lazy
expansion policy when you have to use the <code>expand</code>
attribute as for block <code>d</code> in the example above.  See the
section example in the <manlink href="metatag.html">metatag
tutorial</manlink>. <strong>Rule of thumb:</strong> The
<code>use</code> tags in an <code>expand</code>ed block should be
tagged with <code>noexpand</code>. </p>

</block>