The Labs.Com Programmer HTML The DEF Tag

The Labs - Design & Functionality For The Net

How to use the DEF Tag

1. Macros
2. Inline Plugin
3. Perl Inline Plugin
4. ModPerl Inline Plugin
5. JavaScript Inline Plugin
6. C-Inline Plugin
7. External plugin
8. Design Hints
9. Resources

The most simplest use is as replacement or macro:

Sample source-code:

<def name=test><font size=1>${test}=${full}</font></def>

<test full=50>This is a test</test>

becomes

<font size=1>This is a test=50</font>

This is is the easiest way to use <def>-tag, it functions as macro replacement.

The DEF Tag 2. Inline Plugin

You can write in Perl, JavaScript or C any source-code to handle the tag. In general:

• The command-argument list contains all arguments within the starting tag. In example <test level=18>.....</test>, then the argument list is 'level', '18'.
• Empty args in tag: <myhr size=1 noshade width=50%>, then the argument list is 'size', '1', 'noshade', 'set', 'width', '50%'.
• STDIN you receive the text between the tags (unless you defined container=no)
• STDOUT you print any HTML code to be rendered for the tag.
• The Environment-variables:
  • SOURCE_FILENAME (path of the source-filename .phtml)
  • REVERSE_PATH (reverse path using ../, used for referencing images)
  • PLUGIN_NAME (name of the plugin)
  • PLUGIN_CALLS (number counting from 1)
• Special features and considerations with inline-usage:
  • Perl: The arguments are also filled into the associative array %arg, ie. $arg{level} would return 18, if you used <test level=18>...</test>.
  • ModPerl: The same as with Perl, but the body between the tags does not come via STDIN, but is in $arg{body}, and you print the output via out(); function (not via printf). Also, you have %in which contains all CGI parameters. See details in ProgrammerHTML: Handler.
  • JavaScript: Since inline javascript tag descriptions use argument list to fill the arguments of the tags, you must take care to use the same order for each use.
  • C: nothing special

The DEF Tag 3. Perl Inline Plugin

If you want to make something more sophisticated, you can right away enter some perl, javascript or c-code.

Some source-code:

<def name=test plugin=inline language=javascript>

# --- variable presets:

@ARGV();  # this contains then ('a','another variable');

%arg;     # this contains $arg{'a'} = 'another variable';

#               $arg{'b'} = 'foo';

while(<STDIN>) {

# here you get the "Some sample text ..."

}

</def>

<test a="another variable" b="foo">

Some sample text ...

</test>

The DEF Tag 4. ModPerl Inline Plugin

Some source-code using language=modperl:

<def name=test plugin=inline language=modperl>

# --- variable presets:

%arg;     # this contains $arg{'a'} = 'another variable';

#               $arg{'b'} = 'foo';

# and $arg{body} contains "Some sample text ..."

</def>

<test a="another variable" b="foo">

Some sample text ...

</test>

Please Note: for output use out(); and not printf(). Through this simplification phtml can be used as content-handler with Apache-HTTPD to convert fiules "on-the-fly". More details follow (this is a new feature just added).

The DEF Tag 5. JavaScript Inline Plugin

<def name=test plugin=inline language=perl>

// the first use of <test> defines the sequence of the

//   arguments: text, a, b

document.write("text="+text+"<p>"); // text will hold ..

document.write("a="+a+"<p>");    // a has "another var..

document.write("b="+b+"<p>");    // b has "foo"

</def>

<test a="another variable" b=foo>

Some sample text ...

</test>

Note: the def definition will become a JavaScript-function, when used first time, be sure to call it with the same order of arguments: if you used

<test a="Hi" b="Goodbye">Sample Text</test>

and at later time

<test b="Greetings" a="Handshake">Sample Text</test>

so you will get mixed up. Use the same order as the first use of <test>-tag.

The DEF Tag 6. C-Inline Plugin

<def name=test plugin=inline language=c>

#include <stdio.h>

main(int argc, char *argv[]) {

/*

* argc = 3

* argv[1] = "a"

* argv[2] = "another variable"

* follow environment vars are set:

*    SOURCE_FILENAME

*    REVERSE_PATH

*    PLUGIN_NAME

*    PLUGIN_CALLS

*/

char buff[4096];

while(fgets(buff,sizeof(buff),stdin)) {

/* buff[] contains the "Some sample text ..." */

}

}

</def>

<test a="another variable">

Some sample text ...

</test>

Note: The source-code will be compiled if required, and the executable is held in a cache of ProgrammerHTML.

The DEF Tag 7. External plugin

Instead to enclose the source-code within the <def> tags, you can reference the plugin as external program (which must be executable). The same conditions apply as inline, with the few excepection of the special features.

<def name=test plugin=testtag></def>

<test a="another variable">

Some sample text ...

</test>

With plugin=program-name where you reference the external plug-in, where you can handle the tag:

• STDIN you receive the text between the tags (unless you defined container=no)
• STDOUT you print any HTML code to be rendered for the tag.
• The environent-variables (SOURCE_FILENAME, REVERSE_PATH, PLUGIN_NAME, PLUGIN_CALLS)

The DEF Tag 8. Design Hints

To structure your documents with your own defined tags:

• use .phtml as extension, .html will be created automatically.
• define a new <page> tag, enclose the entire document with it.
• define <section> tag, use to enclose sections, use arguments to title the sections like <section name="Test">
• define the look outside of the phtml-file for sake of flexibility
• anything repeating such as tables or list of sites, define a new tag.

The DEF Tag 9. Resources

ProgrammerHTML Cookbook Further examples of how to use ProgrammerHTML in real life

ProgrammerHTML Plugins Collection of plugins

                                                                                                                                   

Programmer HTML

Handler