htp on-line reference : Metatags

Programming your own tags

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

Metatags are defined with the def and blockdef tags and undefined with the undef tag.

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

 1.  <def name="imghr">
 2.    <table border="0" cellspacing="0" cellpadding="0">
 3.    <tr>
 4.     <td width=10><img src="leftsep.png"></td>
 5.     <td width="95%" background="midsep.png">&nbsp;</td>
 6.     <td width=10><img src="rightsep.png"></td>
 7.    </tr>
 8.    </table>
 9.  </def>
10.
11.  paragraph
12.  <imghr>
13.  paragraph


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 def and /def 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 <imghr> 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 include file.

Often you want to define tags that have an opening and a closing variant. For this purpose you should use the blockdef 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 block. Here is an example for this.

 1.   <blockdef name="bolditalic">
 2.     <b><i>
 3.     <use block>
 4.     </i></b>
 5.   </blockdef>
 6.
 7.   This is <bolditalic>bold and italic</bolditalic>


Using parameters

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

 1.   <def name="sharedimg" option="name alt">
 2.     <img src="/home/sharedimages/${name}" alt="${alt}">;
 3.   </def>
 4.
 5.   <sharedimg name="bubble.gif" alt="Bubble image">


Saving blocks for later

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:

 1.   <set sect-ctr="0">
 2.   <blockdef name="section">
 3.     <inc sect-ctr>
 4.     <block name="sect-${sect-ctr}" expand global>
 5.       <use block noexpand>
 6.     </block>
 7.   </blockdef>


This defines a block macro named section. This macro uses a counter sect-ctr 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 global 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.

The tricky part is the expand and noexpand 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 <use block> 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.

The noexpand attribute of the use 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.

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

 1. <file include="header.hti">
 2.   <set sect-ctr="1">
 3.   <while sect-${sect-ctr}>
 4.     <use sect-${sect-ctr}>
 5.     <inc sect-ctr>
 6.   </while>
 7. <file include="footer.hti">


The while 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.

Conclusions

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?

There is more documentation in this manual, see the Usage 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.