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

<emit></emit>

Provided by module: Tags: RXML 2 tags

<emit> is a generic tag used to fetch data from a provided source, loop over it and assign it to RXML variables accessible through entities.

Occasionally an <emit> operation fails to produce output. This might happen when <emit> can't find any matches or if the developer has made an error. When this happens the truth value of that page is set to false. By using <else> afterwards it's possible to detect when an <emit> operation fails.

Note!

This tag is cache static (see the <cache> tag) if the compatibility level is set to 2.5 or higher.


Attributes

source="plugin"

The source from which the data should be fetched.


scope="name" (The emit source)

The name of the scope within the emit tag.


maxrows="number"

Limits the number of rows to this maximum. Note that it is often better to restrict the number of rows emitted by modifying the arguments to the emit plugin, if possible. E.g. when quering a MySQL database the data can be restricted to the first 100 entries by adding "LIMIT 100".


skiprows="number"

Makes it possible to skip the first rows of the result. Negative numbers means to skip everything execept the last n rows. Note that it is often better to make the plugin skip initial rows, if possible.


rowinfo="variable"

The number of rows in the result, after it has been filtered and limited by maxrows and skiprows, will be put in this variable, if given. Note that this may not be the same value as the number of emit iterations that the emit tag will perform, since it will always make one iteration when the attribute do-once is set.


remainderinfo="variable"

The number of rows left to output, when the emit is restricted by the maxrows attribute. Rows excluded by other means such as skiprows or filter are not included in hte remainderinfo value. The rows counted in the remainderinfo are also filtered if the filter attribute is used, so the value represents the actual number of rows that should have been outputed, had emit not been restriced.


do-once

Indicate that at least one loop should be made. All variables in the emit scope will be empty, except for the counter variable.


filter="list"

The filter attribute is used to block certain 'rows' from the source from being emitted. The filter attribute should be set to a list with variable names in the emitted scope and glob patterns the variable value must match in order to not get filtered. A list might look like name=a*,id=??3?45. Note that it is often better to perform the filtering in the plugin, by modifying its arguments, if possible. E.g. when querying an SQL database the use of where statements is recommended, e.g. "WHERE name LIKE 'a%' AND id LIKE '__3_45'" will perform the same filtering as above.


<emit source='values' values='foo,bar,baz' split=',' filter='value=b*'>
&_.value;
</emit>
bar baz

sort="list"

The emit result can be sorted by the emit tag before being output. Just list the variable names in the scope that the result should be sorted on, in prioritized order, e.g. "lastname,firstname". By adding a "-" sign in front of a name, that entry will be sorted in the reversed order.

The sort algorithm will treat numbers as complete numbers and not digits in a string, hence "foo8bar" will be sorted before "foo11bar". If a variable name is prefixed by "*", then a stricter sort algorithm is used which will compare fields containing floats and integers numerically and all other values as strings, without trying to detecting numbers etc inside them.

Compatibility notes: In 2.1 compatibility mode the default sort algorithm is the stricter one. In 2.2 compatibility mode the "*" flag is disabled.


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

Gives the current number of loops inside the <emit> tag.