Source code: ref/def.htp



<block syntax>
<def name="tagname" [option="option1 [option2 ...]"] [global] [expand]>
</def>
</block>

<block synopsis>

<p>
<strong>DEF</strong> creates <a href="metatag.html">metatags</a>, which is a
fancy way of saying it creates new tags.  The mechanism is very similar to
<a href="block.html">BLOCK</a> macros, except that the <a href="use.html">USE</a>
tag is not used to expand them.  Instead, they are expanded by their own name.
For example:
</p>

<htpcode>
    <def name="centered">
    <p align=center>
    </def>

    <centered>
    This text is centered.
</htpcode>

<P>
Some metatags will require an opening and closing tag (comparable to
<TITLE> and </TITLE>).  In this case, you should use the <A
HREF="blockdef.html">BLOCKDEF</A> macro.  Another slightly faster
alternative is to use two metatags, the opening tag and the closing
tag with a preceding slash. For example:
</P>

<htpcode>
  <def name="bigfont">
    <font size="+4">
  </def>

  <def name="/bigfont">
    </font>
  </def>

  <bigfont>Some large text</bigfont>
</htpcode>

<p> You should really use <a href="blockdef.html">BLOCKDEF</a>, though,
as it will check for matching end tag. It is not that slower.  </p>

<P>
Options can be passed to a metatag, which can then expand as if it were
a <A HREF="set.html">SET</A> macro.  Option names are parameterized with
the OPTION attribute.  Multiple options can be listed by separating their
name with a space (which therefore requires they be surrounded by quotes.)
</P>

<htpcode>
  <DEF NAME="HEADERIMG" OPTION="SRC TITLE SIZE">
    <IF size>
        <FONT SIZE=${size}>
    </IF>
    <IMG SRC=pics/${src}>
    <USE title>
    <IF size>
        </FONT>
    </IF>
  </DEF>

  <HEADERIMG SRC="logo.gif" SIZE="+2" TITLE="A title">

  <HEADERIMG SRC="logo.gif" TITLE="Normal sized title">

  This will fail:
  <HEADERIMG SRC="logo.gif" ALT="Our logo" TITLE="Another title">

  Instead, use * like this:
  <DEF NAME="MYIMG" OPTION="SRC *">
    <IMG SRC="pics/${src}" $*>
  </DEF>
   
  <MYIMG SRC="logo.gif" ALT="Our logo">
</htpcode>

<P>
htp will do very specific checking of parameters when a metatag is
invoked.  htp assumes that all parameter options to the metatag are
optional.  This is why the HEADERIMG definition uses IF to verify the
SIZE option is defined before expanding it in the block.  If a
parameter is required, simply expand it without first checking.  When
htp expands the metatag and the macro is not defined, it will halt
processing and complain with an error message and the required macro
name.  Normally htp will not allow parameters not listed in the OPTION
attribute to be added to the tag.  This is why the third invocation of
HEADERIMG will fail.  There is no ALT parameter specified in the
OPTION attribute.  However, there is the special option *, which
matches every other parameter.  It should be used to pass all other
options to another tag.
</P>

<P>
Metatags can be removed by using the <A HREF="undef.html">UNDEF</A> tag.
Note that both open and close tags must be removed with UNDEF.  Removing one
will not remove both.
</P>

<P>

<STRONG>Warning:</STRONG> 

Although possible, <code>def</code> should not be used to override
standard HTML and htp tag names, as this can cause much confusion and
unexpected results.  The <code>def</code> tag can even be used to
override its own tag name.  Because of the problems this can cause,
its highly recommended to <EM>not</EM> override known tag names.  </P>

<P> You can find some other examples in the <manlink
HREF="metatag.html">metatag</manlink> section of the tutorial.  </P>

</BLOCK>