REXXTAGS - XML tags: tag procedures and tag results

REXXTAGS.org ::

XML tags: tag procedures and tag results

Tags

REXXTAGS is a REXX Server Pages compiler. REXX Server Pages (RSP) are normal HTML pages extended with features similar to those found in Java Server Pages (JSP) or Active Server Pages: scriptlets, expressions, directives, and XML tags. XML tags are described in this document; other features are described elsewhere.

RSP Tags are XML-like tags, in the form:

<prefix:tagname [optional parameters]>
tag body
</prefix:tagname>

If needed, parameters may span multiple lines:

<prefix:tagname
parameters
more parms
>
tag body
</prefix:tagname>

If the tag has no body, the short form can also be used:

<prefix:tagname [optional parameters] />

RSP Tags should, in principle, conform to the XML syntax. The REXXTAGS compiler, however, does not enforce strict XML syntax compliance, and allows arbitrary parameter lists, like in the following example:

<math:calc (1+1/2^8) printresults />

Tag parameters are passed verbatim (after substituting line feeds for single blanks) to the tag procedure (see below); a tag procedure may implement XML syntax compliance for the parameter list, if needed.

The tag procedure

RSP tag semantics are implemented by REXXTAGS tag procedures. A tag procedure is a particular form of REXX procedure which conforms to the REXXTAGS API. Here's the simplest form of a tag procedure:

  1:Parse Arg verb
  2:
  3: If verb == 'START' Then Return "[HTML expansion for the START call]"
  4: If verb == 'END'   Then Return "[HTML expansion for the END call]"
  5:
  6:Return 0
  7:

Another form, to be preferred if the tag procedure needs to do calculations, if the following:

  1:Parse Arg verb
  2:
  3: If verb == 'START' Then Signal StartTag
  4: If verb == 'END'   Then Signal EndTag
  5:
  6:Return 0
  7:
  8:StartTag:
  9: /* some REXX code */
10:Return "[HTML code]"
11:
12:EndTag:
13: /* some REXX code */
14:Return "[HTML code]"
15:

The tag procedure is called once with Arg(1) = 'START' at the point where the start tag is encountered, and once with Arg(1) = 'END' when the end tag is encountered. If the short form <prefix:tag [parms]> is used, two calls are generated, one with Arg(1) = 'START' and one with Arg(1) = 'END'.

The more general form of a tag procedure is as follows:

  1:Parse Arg verb, parms, body, variables
  2:
  3: If verb == 'QUERY BODY CONTENTS' Then Return "[form-of-body-processing]"
  4: If verb == 'QUERY IMPORT' Then Return "[list-of-shared-variables]"
  5: If verb == 'VARIABLES'    Then Return "[list-of-imported-routines]"
  6: If verb == 'START'    Then Signal StartTag
  7: If verb == 'BODY' Then Signal Body
  8: If verb == 'END'    Then Signal EndTag
  9: /* Other special calls go here */
10:
11:Return 0
12:
13:StartTag:
14: Interpret variables /* Optional */
15: /* some REXX code */
16:Return "[HTML code + returned REXX code]"
17:
18:EndTag:
19: Interpret variables /* Optional */
20: /* some REXX code */
21:Return "[HTML code + returned REXX code]"
22:
23:Body:
24: Interpret body /* Mandatory if body processing is desired */
25: Interpret variables /* Optional */
26: /* some REXX code */
27:Return "[HTML code + returned REXX code]"
28:

Tag results

A tag procedure may return HTML code and/or REXX code as the result of the 'START', 'BODY' and 'END' calls. HTML code will be substituted for the start tag (resp. tag body, end tag) in the HTML file sent to the user. If a tag wants to return multiple HTML lines, it may do so by separating lines with a '00'x character:

  1:StartTag:
  2: nl = '00'x
  3:Return "line 1 of HTML",
  4: nl"line 2 of HTML",
  5: ...
  6: nl"line n of HTML"
  7:

A tag procedure may also return one or more REXX code blocks (returned scriptlets), which will be interpreted by the REXXTAGS compiler at the point of the page where the corresponding call is made. REXX code must be delimited between a single line which contains the separator '<%' and a single line which contains the separator '%>':

  1:EndTag:
  2: nl = '00'x
  3:Return "[some optional lines of HTML]",
  4: nl"<%", /* REXX code block 1 starts here */
  5: nl"Line 1 of REXX code between quotes",
  6: ...
  7: nl"Line n of REXX code between quotes",
  8: nl"%>", /* REXX code block 1 ends here */
  9: nl"[optionally more lines of HTML]",
10: ...
11: nl"<%", /* REXX code block n starts here */
12: nl"Line 1 of REXX code between quotes",
13: ...
14: nl"Line n of REXX code between quotes",
15: nl"%>" /* REXX code block n ends here */
16:

Please note that returned scriptlets are interpreted by REXX, and consequently they can not contain labels or procedures. A tag may return HTML code only, REXX code only, HTML code and REXX code, or nothing (Return "").

Parameter passing, body processing, variable sharing and special calls

TBD; see also the preliminary specs.

/specs/tags.html
Last update: 16/06/03 at 12:40

Comments