WebMake Documentation (version 1.1)

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.

Defining Content Tags

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, $perlcode);

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.

$perlcode 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 content tag with a start and end

define_tag()

define a standalone content tag

Defining WebMake Tags

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

define_empty_wmk_tag()

define a WebMake tag with a start and end

define_wmk_tag()

define a standalone WebMake tag

Example

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 came 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', $perlcode);

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

$perlcode is a reference to the PerlCode interpreter which called it, allowing you to use the object-oriented style of WebMake perl code, which is required for safe use under mod_perl or other multithreaded environments.

WebMake Documentation (version 1.1)