Variables, Scopes & Entities

An entity is the collective name for a variable that in RXML 2 has been given an all accessible name, which mean it is available everywhere whenever the module defining it is loaded. A more correct name might be variable-entity, but in RXML 2 it is referred to as an entity.

An entity mostly contains information fetched from within the Roxen WebServer, but it can also be declared by a tag, making it a carrier of website specific information.

A variable always belongs to a scope, i.e. a group of variables providing information about something specific, e.g. a client or a page. A list of variables belonging to a scope can be made available by this RXML code:

<pre>
<insert variables="full" scope="the scope"/>
</pre>

Entity syntax

The syntax that specifies a variable as an entity is "&scope.variable;", e.g. &page.filename;.

Quoting entities

When outputting information from a source that contains entities that should be parsed after the output is parsed, it is necessary to quote these entities else they will be parsed in advance. Quoting entities is done by introducing an extra "." between the scope and the variable, e.g. &scope..variable;

Scopes

The most common scopes that handles variables are the Var and Form scopes. The Var Scope is always empty when the page parsing begins and should be used for temporary variables. The Form Scope contains all returned results from forms.

There is no default scope on the page top level, i.e. outside of all tags that creates scopes, unless you are running in compatibility mode. Then the Form Scope will be your default scope. The scope "_" (underscore) is always the present scope, e.g. in <emit sql> where &sql.x; = &_.x;.

<emit source="sql" query=" ... " scope="outer">
 &_.name; = &outer.name; 
  <emit source="sql" query=" ... " scope="inner">
   &_.name; = &inner.name; != &outer.name; 
  </emit>
</emit>

This is an example on how entities works inside nestled <emit> tags. Notice how the present scope "_" (underscore) changes from the first <emit> to the second.

Entities in RXML 2 are handled like any variable in RXML 1.3. Examples:

RXML	Result
`<set variable="var.foo" value="bar"/>`	&var.foo; = bar
`<set variable="var" scope="foo" value="bar"/>`	&foo.var; = bar
`<if variable="var.foo = bar">`gazonk`</if>`	Returns gazonk if &var.foo; = bar.
`<if match="&var.foo; = *test">`gazonk`</if>`	Returns gazonk if &var.foo; ends in test.

Splice

The splice attribute-operand '::', has a similar function in RXML as in most programming languages. Splice in RXML is used for expanding what is inside a variable, i.e. put what is stored in the variable into for instance a tag before parsing it. It might for instance be a list of attributes stored in the variable or an URL, etc. The splice operand is necessary as the RXML-parser (RXML 2) only will make one pass when parsing a page while the old parser (RXML 1.3) sometimes made several passes while parsing a tag.

<define variable='var.foo'>quant='20' gamma='0.5'</define>
<cimg src='../img/testimage.jpg' ::='&var.foo;'/>

The really useful thing with :: is that it is possible to give attributes, which are unknown, to a tag in advance, which makes it is possible to store an entire list of attributes in a variable.

<sandwich ::="bread='rye' &var.stuffings;" butter="low-fat"/>

In the output source code, this would look like:

<sandwich bread='rye' lettuce="" ham="" tomato="" butter="low-fat"/>

Encoding

An entity can be placed anywhere in a page and will have its content inserted during the parsing. The content is encoded by default so that "<" will be output as "<" in HTML pages. You can choose another scheme by using the &scope.variable:scheme; syntax, e.g. &form.html:none;. [More about encoding]