Defining Tags

Like Roxen or Java Server Pages, WebMake allows you to define your own tags; these cause a perl function to be called whenever they are encountered in either content text, or inside the WebMake file itself.

You do this by calling the define_tag() function from within a <{perl}> section in the WebMake file. This will set up a tag, and indicates a reference to the handler function to call when that tag is encountered, and the list of attributes that are required to use that tag.

Any occurrences of this tag, with at least the set of attributes defined in the define_tag() call, will cause the handler function to be called.

Handler functions are called as fcllows:

        handler ($tagname, $attrs, $text, $perlcodeself);

Where $tagname is the name of the tag, $attrs is a reference to a hash containing the attribute names and the values used in the tag, and $text is the text between the start and end tags.

$perlcodeself is the PerlCode object, allowing you to write proper object-oriented code that can be run in a threaded environment or from mod_perl. This can be ignored if you like.

Note that there are two variations, one for conventional tag pairs with a start and end tag, the other for stand-alone empty tags with no end tag. The latter variation is called define_empty_tag().

define_empty_tag()

define a standalone content tag

define_tag()

define a content tag with a start and end

This is identical to using content tags, above, but the functions are as follows:

define_empty_wmk_tag()

define a standalone WebMake tag

define_wmk_tag()

define a WebMake tag with a start and end

Let's say you've got the following in your WebMake file.

  <{perl
   define_tag ("thumb", \&make_thumbnail, qw(img thumb));
  }>

  <content name="foo">
    <thumb img="big.jpg" thumb="big_thumb.jpg">
      Picture of a big thing
    </thumb>
  </content>

When the foo content item comes to be included in an output file, the tag will be replaced with a call to a perl function, as follows:

  make_thumbnail ("thumb",
     { img => 'big.jpg', thumb => 'big_thumb.jpg' },
     'Picture of a big thing', $perlcodeself);

Note that if the tag omitted one of the 2 required attributes, img or thumb, it would result in an error message.

For more serious examples of tag definition, the WebMake distribution comes with several plugins, such as safe_tag.wmk which define their own tags.