# 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. <OPT (IMGXY|NOIMGXY)>
2. <OPT (QUIET|VERBOSE)>
3. <OPT (DEPEND|NODEPEND)>
4. <OPT (PRECIOUS|NOPRECIOUS)>
5. <OPT (CONDENSE|SEMICONDENSE|NOCONDENSE)>
6. <OPT DELIM=(HTML|SQUARE|CURLY)>
7. <OPT (XML|XML=FALSE)>
8.
`

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. <SET macroname1="macrovalue1" [macroname2="macrovalue2" ...] [GLOBAL]>
2.
`

## 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. <SET emailaddr="jnelson@crl.com">
`

## 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. <unset macroname>
2. <unset macroname1 macroname2 ... >
3.
`

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.

hosted by Sourceforge HTML coding

Copyright © 1995–96 Jim Nelson. Copyright © 2001–2014 Jochen Hoenicke. Permission to reproduce and distribute this hypertext document granted according to terms described in the License section. last updated Sat May 16, 2015