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

<define></define>

Provided by module: Tags: RXML 2 tags

Defines new tags, containers and if-callers. Can also be used to set variable values.

The attributes "tag", "container", "if" and "variable" specifies what is being defined. Exactly one of them are required. See the respective attributes below for further information.


Attributes

variable="name"

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


tag="name"

Defines a tag with the given name that doesn't take any content. When the defined tag is used, the content of this <define> is RXML parsed and the result is inserted in place of the defined tag. The arguments to the defined tag are available in the current scope in the <define>. An example: 
<define tag='my-tag'>
  <inc variable='var.counter'/>
  A counter: &var.counter;<br />
  The 'foo' argument is: &_.foo;<br />
</define>
<my-tag/>
<my-tag foo='bar'/>
A counter: 1
The 'foo' argument is:
A counter: 2
The 'foo' argument is: bar


container="name"

Like the 'tag' attribute, but the defined tag may also take content. The unevaluated content is available in &_.contents; inside the <define> (see the scope description below). You can also get the content after RXML evaluation with the <contents> tag - see below for further details.


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.

If the result-set attribute is not used then the selected nodes are returned as a string, otherwise they are returned as an array with one node per element (see the result-set attribute for details).

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

A step preceded by '/' is only matched against the immediate children of the node currently selected by the preceding step. A step preceded by '//' is matched against any node in the tree below that node.

Note: An expression cannot begin with '/' or '//'. Use './' or './/' instead.

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.

  • '.' selects the currently selected element itself.

A step may be followed by '[test]' to filter the selected set in various ways. The test may be any of the following:

  • If test is an integer then the item on that position in the set is selected. 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.

  • If test is a path on the form described above then that path is evaluated for each node in the selected set, and only the nodes where the path finds a match remain in the set.

    E.g. a test on the form '@name' accepts only elements that have an attribute with the given name.

  • If test is on the form 'path=value' then path is evaluated for each node in the selected set, and only the nodes where at least one path result matches value remain in the set. value is a string literal delimited by either " or '.

    E.g. '@name=value' filters out the elements that have an attribute with the given name and value.

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 node values are inserted. The expression is the same as for the copy-of attribute.

If the result-set attribute is not used then only the first node value in the selected set is returned, otherwise all values are returned as an array (see the result-set attribute for details).

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.


result-set

Used together with the copy-of or value-of attributes. Add this attribute to make them return the selected nodes or values as a set instead of a plain string.

The result can not be inserted directly into the page in this case, but it can be assigned to a variable and manipulated further, e.g. fed to <emit> to iterate over the elements in the set. An example:


<define container='sort-items'>
  <set variable='_.item'><contents copy-of='item' result-set=''/></set>
  <emit source='values' variable='_.item' sort='value'>&_.value;</emit>
</define>
<sort-items>
  <item>one</item>
  <item>two</item>
  <item>three</item>
</sort-items>
<item>one</item><item>three</item><item>two</item>

The set is normally an array (in document order), but if used with copy-of and the expression selects an attribute set then that set is returned as a mapping.