A REXXTAGS file is a normal HTML file, plus standard Mod_Rexx RSP extensions, plus XML-like tags, in the form:

<prefix:tagname [parms]>[other XML and HTML code here]</prefix:tagname>

or

<prefix:tagname [parms]/>

A tag can occupy multiple lines, if desired, as in

<prefix:tagname 
  parameter1="A very long parameter value for parameter number 1"
  parameter2="A very long parameter value for parameter number 2"
/>

REXXTAGS pages can also use <%=expressions%>. These expressions can appear anywhere in the middle of html code, and as part of the parameter section of an XML tag. Expressions are evaluated by Rexx, and their value is substituted in the corresponding code.

As in Mod_Rexx RSPCOMP, REXX code (scriptlets) can be inserted anywhere in the middle of your HTML page. In addition of supporting lines enclosed between "<?rexx" and "?>" or between "<script type='rexx'>" and "</script>", as Mod_Rexx does, you can also bracket your code between "<%" and "%>". These markers should occur on separate lines:

   <%
   (rexx code goes here)
   %> 
 

The Tag procedure

Every tag must have its associated Rexx routine (the Rexx Tag procedure). These procedures must be placed in one of the "taglib" directories (see the quick installation guide) for the REXXTAGS compiler to find them and the generated code to be able to access them. Here's the skeleton for the simplest possible form of Rexx Tag:

/* This is the Rexx code for tag <prefix:tagname>. The filename must be "prefix.tagname.tag" */
Parse Arg verb

If verb = "START" Then Return "start-tag-expansion"
If verb = "END" Then Return "end-tag expansion"

Return 0

The REXXTAGS compiler generates one call to the Tag procedure in place of the starting tag, with Arg(1) = 'START', and another call to the same procedure in place of the end tag with Arg(1) = 'END'.

Tag results

The return value for a Rexx Tag procedure is the html expansion of the tag. This expansion is inserted as is at the point where the Rexx Tag was present in the XML code. Multiple lines can be returned by separating them with a '00'x character.

Returning Rexx code

A tag may choose to return Rexx code (a scriptlet) to the REXXTAGS page. This code must begin with a single line containing "<%", and end with a single line containing "%>". The resulting code is interpreted by Rexx at page's execution time. A tag result may contain html code mixed with one or more fragments of Rexx code; each fragment will be interpreted in turn, allowing for a limited form of state-sharing between tags.

Tag parameters

XML parameters are passed to a Rexx Tag verbatim (apart from <%=expr%> expression substitution); no syntax checking is done by the REXXTAGS compiler (this corresponds to the Rexx Tag procedure, which, given Rexx's power in the area of string manipulation, can choose to implement more or less strict syntax checking, depending on the project: for rapid prototyping, syntax checking can be minimal; for production environments, it can be as complete as you want. Leaving parameter syntax checking to Rexx has also the advantage that, if needed, you can use non-XML conformant syntax. The only modification the REXXTAGS compiler imposes to a parameter list is to substitute line ends for spaces (a single space). XML parameters are passed to a Rexx Tag as the second argument of the tag. Therefore, if your procedure wants to manipulate the tag parameters, it has to use a parse instruction like:

Parse Arg verb, parms

The parameter list is passed to all code-generating calls (the 'START' call, the 'END' call, and the 'BODY' call, described below).

Body processing

A tag can choose to provide special processing of its body contents. The default is to pass the body to the RSP compiler, and only expand the start tag and the end tag. If a tag wants to process the body contents, it may do so in two ways: verbatim, or after processing of the body by the REXTAGS compiler (i.e., after expanding the inner tags and substituting them for their results, interpreting any Rexx code, etc). A tag indicated which form of body processing it wants to use by returning a value to the 'QUERY BODY CONTENT' call:

Parse Arg verb


If verb = "QUERY BODY CONTENT" Then Return "form-of-body-processing"
...

A "form-of-body-processing" value of "0" (the default) indicates no special body processing; if the return value is "TAGDEPENDENT", all the lines in the body are passed, untouched, to the Rexx Tag procedure (in the form described below); if the return value is "RSP" (for Rexx Server Pages), the body is evaluated by the REXXTAGS compiler, and the result of the evaluation of the body is passed to the Rexx Tag procedure.

A Rexx Tag procedure that has indicated that it wants to process the body of the tag receives a special "BODY" call; the "BODY" call occurs after the "START" call, after the body has been processed, and before the "END" call. When a "BODY" call is made, the body contents are passed to the Rexx Tag procedure as the third parameter, i.e. Arg(3) = "body". This string must be interpreted to obtain the body value, which will then be in the body. stem:

Parse Arg verb, parms, body


If verb = "BODY" Then Signal BodyProcessing

...

BodyProcessing:
  Interpret body /* Now body.1, body.2, ... contain the body of the tag */
  ...

Special calls

The special call "QUERY APACHE REQUEST" will be issued to every tag. If the tag returns 0 (the default), nothing occurs. If the tag returns 1, a special parameter will be added to the tag parameter list by the REXXTAGS compiler, in the form 'request=<apache request>'. This allows that a Rexx Tag can issue some Mod_Rexx calls which need the value of the Apache request. If the tag returns any other value, it is supposed to be the parameter name for the Apache request value.

The special call "QUERY IMPORT" will be issued to every tag. If the tag return 0 (the default), nothing occurs. Otherwise, the returned value should be a blank-separated list of routine names (with or without the associated .rex extension) which will be looked for in turn in each of the TAGLIB directories and imported into the compiled file. See the section about importing code for details.

The special call "VARIABLES" will be issued to every tag. If the tag returns 0 (the default) or "", nothing occurs. Otherwise, the returned value should be a blank-separated list of variables (like "i", "name" or "test.2", stems like "a.", or sub-stems like "x.y.") A string will be passed to the tag routine as the fourth argument; if this string is interpreted, the corresponding variables will be assigned to the tag procedure. See the section about variable passing and sharing for details.

/specs/spec.html Last update: 15/06/03 at 16:52

Comments