docs.roxen.comBack to normal mode
DocsRoxenWebServer 3.4Web Developer ManualVariable Tags
Copyright © 2006, Roxen Internet Software
Suggestions, comments & compliments
manuals@roxen.com

<define></define>

Provided by module: Tags: RXML 2 tags

Defines variables, tags, containers and if-callers.

The values of the attributes given to the defined tag are available in the scope created within the define tag.


Attributes

variable="name"

Sets the value of the variable to the contents of the container.


tag="name"

Defines a tag that outputs the contents of the container.


<define tag="hi">Hello &_.name;!</define>
<hi name="Martin"/>
Hello Martin!

container="name"

Defines a container that outputs the contents of the container.


if="name"

Defines an if-caller that compares something with the contents of the container.


trimwhites

Trim all white space characters from the beginning and the end of the contents.


preparse

Sends the definition through the RXML parser when the <define> is executed instead of when the defined tag is used.

Compatibility notes: If the compatibility level is 2.2 or earlier, the result from the RXML parse is parsed again when the defined tag is used, which can be a potential security problem. Also, if the compatibility level is 2.2 or earlier, the <define> tag does not set up a local scope during the preparse pass, which means that the enclosed code will still use the closest surrounding '_' scope.


&_.args; (provided by Tags: RXML 2 tags)

The full list of the attributes, and their arguments, given to the tag.


&_.contents; (provided by Tags: RXML 2 tags)

The unevaluated contents of the container.


&_.rest-args; (provided by Tags: RXML 2 tags)

A list of the attributes, and their arguments, given to the tag, excluding attributes with default values defined.


<attrib></attrib>

Provided by module: Tags: RXML 2 tags

When defining a tag or a container the tag <attrib> can be used to define default values of the attributes that the tag/container can have. The attrib tag must be the first tag(s) in the define tag.


Attributes

name="name"

The name of the attribute which default value is to be set.


<contents/>

Provided by module: Tags: RXML 2 tags

Inserts the whole or some part of the arguments or the contents passed to the defined tag or container.

The passed contents are RXML evaluated in the first encountered <contents>; the later ones reuses the result of that. (However, if it should be compatible with 2.2 or earlier then it's reevaluated each time unless there's a 'copy-of' or 'value-of' attribute.)

Note that when the preparse attribute is used, this tag is converted to a special variable reference on the form '&_.__contents__n;', which is then substituted with the real value when the defined tag is used. It's that way to make the expansion work when the preparsed code puts it in an attribute value. (This is mostly an internal implementation detail, but it can be good to know since the variable name might show up.)


Attributes

scope="scope"

Associate this <contents> tag with the innermost <define> container with the given scope. The default is to associate it with the innermost <define>.


eval

When this attribute exists, the passed content is (re)evaluated unconditionally before being inserted. Normally the evaluated content from the preceding <contents> tag is reused, and it's only evaluated if this is the first encountered <contents>.


copy-of="expression"

Selects a part of the content node tree to copy. As opposed to the value-of attribute, all the selected nodes are copied, with all markup.

The expression is a simplified variant of an XPath location path: It consists of one or more steps delimited by '/'. Each step selects some part(s) of the current node. The first step operates on the defined tag or container itself, and each following one operates on the part(s) selected by the previous step.

A step may be any of the following:

  • 'name' selects all elements (i.e. tags or containers) with the given name in the content. The name can be '*' to select all.

  • '@name' selects the element attribute with the given name. The name can be '*' to select all.

  • 'comment()' selects all comments in the content.

  • 'text()' selects all text pieces in the content.

  • 'processing-instruction(name)' selects all processing instructions with the given name in the content. The name may be left out to select all.

  • 'node()' selects all the different sorts of nodes in the content, i.e. the whole content.

A step may be followed by '[n]' to choose the nth item in the selected set. The index n may be negative to select an element in reverse order, i.e. -1 selects the last element, -2 the second-to-last, etc.

An example: The expression 'p/*[2]/@href' first selects all <p> elements in the content. In the content of each of these, the second element with any name is selected. It's not an error if some of the <p> elements have less than two child elements; those who haven't are simply ignored. Lastly, all 'href' attributes of all those elements are selected. Again it's not an error if some of the elements lack 'href' attributes.

Note that an attribute node is both the name and the value, so in the example above the result might be 'href="index.html"' and not 'index.html'. If you only want the value, use the value-of attribute instead.


value-of="expression"

Selects a part of the content node tree and inserts its text value. As opposed to the copy-of attribute, only the value of the first selected node is inserted. The expression is the same as for the copy-of attribute.

The text value of an element node is all the text in it and all its subelements, without the elements themselves or any processing instructions.