Tag Modules

The module type constant for tag modules is MODULE_TAG.

Extending RXML with your own tags is done by implementing tag modules. There are two methods of writing tags; simpletags being by far the easier one, RXML.pmod class style being the more powerful of the two.

Writing simpletags is mostly a matter of naming your module's methods; methods with a leading "simpletag_" will be caught as tag definitions, and the tag name constructed from the function name (after underscores having been changed into dashes).

A tag definition such as

string simpletag_my_test_tag(string name, mapping arg, string contents, RequestID id)

will generate a tag <my-test-tag>, and when encountered in an RXML parsed document (for example, <my-test-tag testing='yes'>hi.</my-test-tag>), the function will be called with the arguments filled with, in turn, the name of the tag ("my-test-tag"), a mapping of its arguments (([ "testing":"yes" ])), its contents ("hi.") and the RequestID object. The string returned by the function will be inserted in the document, replacing the tag and its contents.

By providing an integer

int simpletag_my_test_tag_flags = RXML.FLAG_DEBUG

you can alter how the RXML parser calls and treats your tag, by oring together the flags of your choice from the list below.

RXML Tag Flags

FLAG_DEBUG

Write a lot of debug during the execution of the tag, showing what type conversions are done, what callbacks are being called etc. Note that DEBUG must be defined for the debug printouts to be compiled in (normally enabled with the --debug flag to Roxen).

FLAG_PROC_INSTR

Flags this as a processing instruction tag (i.e. one parsed with the <?name ... ?> syntax in XML). The string after the tag name to the ending separator constitutes the content of the tag. Arguments are not used.

A still easier way of making processing instruction tags is by calling your tag function simple_pi_tag_my_tag_name right away. the argument template for the tag is the same, but the argument mapping sent is always empty, for obvious reasons.

FLAG_EMPTY_ELEMENT

If set, the tag does not use any content. E.g. with an HTML parser this defines whether the tag is a container or not, and in XML parsing it simply causes the content (if any) to be thrown away.

FLAG_COMPAT_PARSE

Makes the PXml parser parse the tag in an HTML compatible way: If FLAG_EMPTY_ELEMENT is set and the tag doesn't end with '/>', it will be parsed as an empty element. The effect of this flag in other parsers is currently undefined.

FLAG_NO_PREFIX

Never apply any prefix to this tag.

FLAG_DONT_PREPARSE

Don't preparse the content with the PXml parser. This is always the case for PI tags, so this flag doesn't have any effect for those. This is only used in the simple tag wrapper. Defined here as placeholder.

FLAG_POSTPARSE

Postparse the result with the PXml parser. This is only used in the simple tag wrapper. Defined here as placeholder.

Class-based Tag API

To be continued...

		Tag Modules The module type constant for tag modules is MODULE_TAG. Extending RXML with your own tags is done by implementing tag modules. There are two methods of writing tags; simpletags being by far the easier one, RXML.pmod class style being the more powerful of the two. Writing simpletags is mostly a matter of naming your module's methods; methods with a leading "simpletag_" will be caught as tag definitions, and the tag name constructed from the function name (after underscores having been changed into dashes). A tag definition such as `string simpletag_my_test_tag(string name, mapping arg, string contents, RequestID id)` will generate a tag `<my-test-tag>`, and when encountered in an RXML parsed document (for example, `<my-test-tag testing='yes'>hi.</my-test-tag>`), the function will be called with the arguments filled with, in turn, the name of the tag (`"my-test-tag"`), a mapping of its arguments (`([ "testing":"yes" ])`), its contents (`"hi."`) and the RequestID object. The string returned by the function will be inserted in the document, replacing the tag and its contents. By providing an integer `int simpletag_my_test_tag_flags = RXML.FLAG_DEBUG` you can alter how the RXML parser calls and treats your tag, by oring together the flags of your choice from the list below. RXML Tag Flags FLAG_DEBUG Write a lot of debug during the execution of the tag, showing what type conversions are done, what callbacks are being called etc. Note that DEBUG must be defined for the debug printouts to be compiled in (normally enabled with the --debug flag to Roxen). FLAG_PROC_INSTR Flags this as a processing instruction tag (i.e. one parsed with the <?name ... ?> syntax in XML). The string after the tag name to the ending separator constitutes the content of the tag. Arguments are not used. A still easier way of making processing instruction tags is by calling your tag function simple_pi_tag_my_tag_name right away. the argument template for the tag is the same, but the argument mapping sent is always empty, for obvious reasons. FLAG_EMPTY_ELEMENT If set, the tag does not use any content. E.g. with an HTML parser this defines whether the tag is a container or not, and in XML parsing it simply causes the content (if any) to be thrown away. FLAG_COMPAT_PARSE Makes the PXml parser parse the tag in an HTML compatible way: If FLAG_EMPTY_ELEMENT is set and the tag doesn't end with '/>', it will be parsed as an empty element. The effect of this flag in other parsers is currently undefined. FLAG_NO_PREFIX Never apply any prefix to this tag. FLAG_DONT_PREPARSE Don't preparse the content with the PXml parser. This is always the case for PI tags, so this flag doesn't have any effect for those. This is only used in the simple tag wrapper. Defined here as placeholder. FLAG_POSTPARSE Postparse the result with the PXml parser. This is only used in the simple tag wrapper. Defined here as placeholder. Class-based Tag API To be continued...