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:
The syntax that specifies a variable as an entity is "&scope.variable;", e.g. &page.filename;.
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;
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;.
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:
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.
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.
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]