Source code: ref/metatag.htp

<BLOCK body>

<H2>Programming your own tags</H2>

<p>
<STRONG>Metatags</STRONG> allow for defining your own HTML-like
tags.  When you define a metatag you have to provide the HTML code
which it abbreviates.  In fact metatags are just like block macros,
but they have a nicer syntax.  With metatags you can expand htp's
functionality.
</p>

<P> Metatags are defined with the <manlink
HREF="def.html"><code>def</code></manlink> and <manlink
HREF="blockdef.html"><code>blockdef</code></manlink> tags and
undefined with the <manlink
HREF="undef.html"><code>undef</code></manlink> tag.  </P>

<P>
As an example we show how to define a tag that builds a
fancy horizontal rule out of several images.
</P>

<htpcode linenr>
 <def name="imghr">
   <table border="0" cellspacing="0" cellpadding="0">
   <tr>
    <td width=10><img src="leftsep.png"></td>
    <td width="95%" background="midsep.png">&nbsp;</td>
    <td width=10><img src="rightsep.png"></td>
   </tr>
   </table>
 </def>

 paragraph
 <imghr>
 paragraph
</htpcode>

<P> In line 1 of the above example a new tag named imghr is defined.
The html code which implements this rule is following in lines 2-8.
between the <manlink href="def.html"><code>def</code> and
<code>/def</code></manlink> tags.  You don't have to understand this
html code, but you should understand that this is just pure html to
draw the fancy rule. Every time you write <code>&lt;imghr&gt;</code>
as in line 12 htp will replace this tag with the corresponding html
code.  To make metatags available to all htp documents in your
project, place them in a common <manlink HREF="file.html">include
file</manlink>.  </p>

<P> Often you want to define tags that have an opening and a closing
variant.  For this purpose you should use the <manlink
href="blockdef.html"><code>blockdef</code></manlink> tag.  When htp
encounters a blockdef tag it will automatically search for the
matching closing tag and put everything between these tags in a block
macro named <code>block</code>.  Here is an example for this.  </P>

<htpcode linenr>
  <blockdef name="bolditalic">
    <b><i>
    <use block>
    </i></b>
  </blockdef>

  This is <bolditalic>bold and italic</bolditalic>
</htpcode>

<h2>Using parameters</h2>

<p> More sophisticated tags accept parameters.  The
<code>option</code> parameter lets multiple metatag parameters be
named and expanded inside the <code>def</code> or
<code>blockdef</code> block: </p>

<htpcode linenr>
  <def name="sharedimg" option="name alt">
    <img src="/home/sharedimages/${name}" alt="${alt}">;
  </def>

  <sharedimg name="bubble.gif" alt="Bubble image">
</htpcode>

<h2>Saving blocks for later</h2>

<p>When you are using templates, the html should only be written by
the template file.  The normal htp files should just define macros
that are used later in the template.  So you may want to write block
tags that just save the block in a macro for later use.  Although this
is possible with htp it is quite tricky, so here we present the way to
do this:</p>

<htpcode linenr>
  <set sect-ctr="0">
  <blockdef name="section">
    <inc sect-ctr>
    <block name="sect-${sect-ctr}" expand global>
      <use block noexpand>
    </block>
  </blockdef>
</htpcode>

<p> This defines a block macro named section.  This macro uses a
counter <code>sect-ctr</code> that enumerates the sections.  It is
increased for every section (line 3) and then the block macro name is
build from this counter.  So the first section is stored in block
sect-1, the second in sect-2 and so on.  The <manlink href="expand.html#global"><code>global</code></manlink> flag
in line 4 tells htp that these macros should be defined globally
for the remaining run.  Otherwise they would be forgotten at the end
of the section macro.  </p>

<p>The tricky part is the <manlink
href="expand.html#expand"><code>expand</code></manlink> and
<code>noexpand</code> flags in line 4 and 5.  Normally when you define
a block macro the code between the start and end tag is literally
copied into the macro value.  The expansion takes place when the macro
is used.  In this case that doesn't make sense; all macros sect-1,
sect-2 and so on would just contain the same value, namely
<code>&lt;use block&gt;</code> and block wouldn't be defined anymore
when the macros are finally expanded.  Therefore we use expand to
expand the use tag already when sect-1 is defined.</p>

<p>The <code>noexpand</code> attribute of the <manlink href="use.html"><code>use</code></manlink> tag is just the opposite and prevents the
contents of block to be expanded twice.  If you omit it, it would be
expanded when defining the sect-1 macro and when using it later in the
template.  Generally it is a good idea to use noexpand whenever you
use expand in a block around it.</p>

<p>To close this example we show how to expand the
<code>sect-${sect-ctr}</code> blocks in the template:</p>

<htpcode linenr>
<file include="header.hti">
  <set sect-ctr="1">
  <while sect-${sect-ctr}>
    <use sect-${sect-ctr}>
    <inc sect-ctr>
  </while>
<file include="footer.hti">
</htpcode>

<p>
The <manlink href="while.html">while</manlink> tag in line 3 checks whether
the macro sect-${sect-ctr} is defined.  If it is defined the body is
evaluated, which expands the macro and increases sect-ctr.  Afterwards
the while condition is checked again to check for sect-2 macro.  This
repeats until sect-${sect-ctr} is not defined.
</p>

<h2>Conclusions</h2>

<p>This closes our short htp tutorial.  I hope you did enjoy it and
see the advantages of using htp for your own projects.  Please give us
some feedback about this tutorial. What can be improved?</p>

<p>There is more documentation in this manual, see the <manlink
href="usage.html">Usage</manlink> chapter or browse the documentations
for the htp tags.  If you're looking for examples, in case you haven't
already noticed yourself, there is a link to the source code on the
left, where you can get the source code for every page on this
site.</p>

</block>