Roxen Interactive RXML Help

<emit></emit>

<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.

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

Attributes

source

source=plugin
This attribute is required.

The source from which the data should be fetched.

scope

scope=name (The emit source)

The name of the scope within the emit tag.

maxrows

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

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

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

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

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

filter-exclude

filter-exclude=list

The filter exclude attribute is used to filter out unwanted rows that would otherwise be emitted. Uses the same syntax as the filter attribute.

sort

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 order is case sensitive, but by adding "^" in front of the variable name the order will be case insensitive.

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.

reverse

The results will be output in reverse order.

<emit source='path' path='/path/to/file' reverse=''> &_.path;<br/> </emit>

/path/to/file /path/to /path /

Defined in content

&_.counter;

Gives the current number of loops inside the <emit> tag, starting from zero.

<delimiter></delimiter>

The content is inserted in the result except in the last iteration through the <emit> tag. It's therefore useful to insert stuff that only should delimit the entries, i.e. not occur before the first one or after the last.

Emit plugin cimg

Entitybased version of <cimg>. Takes the same attributes as <cimg>.

Attributes

nodata

nodata={yes , no}

Controls suppression of &_.data; in the output. Useful for reducing memory consumption in cached emit tags. The default value is 'no'.

Defined in content

&_.data;

Returns the imagedata given through other sources, like databases through entities.

&_.file-size;

Returns the image's file size.

&_.src;

Returns the path to the indata file.

&_.type;

Returns the image's content-type.

&_.xsize;

Returns the width of the image.

&_.ysize;

Returns the height of the image.

No documentation available for "plugin csv".

Emit plugin dir

This plugin is used to generate directory listings. The directory module must be added to use these entities. This plugin is only available in the directory template.

Attributes

directory

directory=path

List this directory. The default is to list the directory containing the currently requested page.

thumbnail-size

thumbnail-size=number

Sets the size of the thumbnail. Defaultsize is 60 pixels. The size is set in proportion to the image's longest side, e.g. if the height of the image is longer than it's width, then the thumbnail will be 60 pixels high. The shortest side will be shown in proportion to the longest side.

thumbnail-format

thumbnail-format=imageformat

Set the output format for the thumbnail. Default is png. All imageformats that <cimg> handles can be used to produce thumbnails.

strftime

strftime=strftime string (%Y-%m-%d)

Format the date according to this string. Default is the isotime format (%Y-%m-%d), which will return (Year(four characters)-month(two characters)-day(two characters)), e.g. 2000-11-22. See the attribute strftime in <date> for a full listing of available formats.

glob

glob=glob-pattern1[,glob-pattern2,...]

Only show files matching the glob-pattern.

type

type=glob-pattern1[,glob-pattern2,...]

Only show files which content-type matches the glob-pattern.

sort-order

sort-order={alpha, dwim, modified, size, type} (dwim)

Sort the files and directories by this method.

alpha	Sort files and directories alphabetically.
dwim	Sort files and directories by "Do What I (want) Method". In many methods numeriacal sorts fail as the number '10' often appears before '2'. This method sorts numerical characters first then alphabetically, e.g. 1foo.html, 2foo.html, 10foo.html, foo1.html, foo2.html, foo10.html.
modified	Sort files by modification date.
size	Sort files by size.
type	Sort files by content-type.

sort-reverse

Reverse the sort order.

Defined in content

&_.atime-iso;

Returns the date when the file was last accessed. Uses isotime (%Y-%m-%d).

&_.atime-unix;

Returns the date when the file was last accessed. Uses unixtime.

&_.atime;

Returns the date when the file was last accessed.

&_.dirname;

Returns the directoryname.

&_.filename;

Returns the filename.

&_.filesize;

Returns a file's size in bytes. Directories get the size "-2".

&_.mode-int;

Returns file permission rights represented by integers. When encoded to binary this represents what is shown when using the Unix command "ls -l" or as shown using &_.mode;, e.g. "16749".

&_.mode;

Returns file permission rights represented binary, e.g. "r-xr-xr-x".

&_.mtime-iso;

Returns the date when the file was last modified. Uses isotime (%Y-%m-%d).

&_.mtime-unix;

Returns the date when the file was last modified. Uses unixtime.

&_.mtime;

Returns the date when the file was last modified.

&_.name;

Returns the name of the file or directory.

&_.path;

Returns the path to the file or directory.

&_.real-dirname;

Returns the directory of the real file in the filesystem.

&_.real-filename;

Returns the path to the real file in the filesystem.

&_.size;

Returns a file's size in kb(kilobytes).

&_.thumbnail;

Returns the image associated with the file's content-type or directory.

&_.type-img;

Returns the internal Roxen name of the icon representating the directory or the file's content-type, e.g. internal-gopher-menu for a directory-folder or internal-gopher-text for a HTML-file.

&_.type;

Returns the file's content-type.

&_.vfs-root;

Returns the root directory of the virtual filesystem that keeps the file.

&_.vfs;

Returns the name of the virtual filesystem that keeps the file.

&_.x-size;

Returns the width of the image.

&_.y-size;

Returns the height of the image.

No documentation available for "plugin fonts".

No documentation available for "plugin imgs".

No documentation available for "plugin license-warnings".

No documentation available for "plugin path".

No documentation available for "plugin scopes".

No documentation available for "plugin sources".

Emit plugin sql

Use this source to connect to and query SQL databases for information. The result will be available in variables named as the SQL columns.

NULL values in the SQL result are mapped to the special null value, &roxen.null;. That value expands to the empty string if inserted, and tests as false with <if variable> and true with <if variable-exists>.

Compatibility note: If the compatibility level is 4.5 or lower, an SQL NULL value instead maps to an undefined value in RXML, which is similar to that the RXML variable doesn't exist at all. That makes both <if variable> and <if variable-exists> return false for it, among other things.

Attributes

db

db=database

Which database to connect to, among the list of databases configured under the "DBs" tab in the administrator interface. If omitted then the default database will be used.

host

host=url

A database URL to specify the database to connect to, if permitted by the module settings. If omitted then the default database will be used.

The database URL is on this format:

driver://[username[:password]@]host[:port][/database]

where driver is the database protocol, e.g. "odbc", "mysql", "oracle", "postgres", etc.

For compatibility this can also be a database name as given to the "db" attribute.

module

module=string

Access the local database for the specified Roxen module, if permitted by the module settings. This attribute is deprecated.

query

query=SQL statement

The actual SQL-statement.

bindings

bindings=name=variable,name=variable,...

Specifies binding variables to use with this query. This is comma separated list of binding variable names and RXML variables to assign to those binding variables.

Note: For some databases it is necessary to use binding variables when inserting large datas. Oracle, for instance, limits the query to 4000 bytes.

<set variable='var.foo' value='texttexttext'/> <sqlquery query='insert into mytable VALUES (4,:foo,:bar)' bindings='foo=var.foo,bar=form.bar'/>

charset

charset=string

Use the specified charset for the sent SQL statement and returned text values.

This will cause all SQL queries to be encoded with this charset. It will also normally cause all string results to be decoded with this charset, but there are exceptions as explained later. If the database connection supports it, the connection will be configured to use this charset too (at least MySQL 4.1 and later has such support).

In many cases, it is difficult for the SQL interface to tell text and binary data apart in results. That is a problem since a text string should be decoded according to the charset while a binary octet string must not be decoded.

If the connection supports it, using the special value unicode as charset is guaranteed to handle both text and binary result strings correctly so you don't have to worry about it. In that case you can assume the SQL query and text results covers the full Unicode range, and the connection will handle the charset issues internally. This is known to be supported with MySQL 4.1 and later. An RXML run error is thrown if it isn't supported.

Otherwise, all string values are assumed to be text and are therefore decoded using the given charset. You can turn it off for specific columns through the "binary-result" attribute.

If you use none as charset in this attribute then the charset handling described here is disabled for this query. That is useful to override a charset in the "Default charset" module setting.

The charset specification in this attribute can optionally be a list like this:

charset="recode-charset, connection-charset"

In this form, the recode-charset is used by Roxen to recode the query and results, and connection-charset is sent to the database driver to use for the connection. This is useful if the database server uses nonstandard names for its character sets. E.g. MySQL spells cp1252 as "latin1" (which is the closest you get to iso-8859-1 there), so to use that you'd say "cp1252,latin1" in this attribute. This list form is not applicable for the unicode case.

Compatibility note: In Roxen 4.5 this attribute only configured the charset for the connection; it didn't do any conversion of the query nor the results. This behavior still remains if the compatibility level is 4.5 or lower. You can also achieve the same effect by specifying "none,whatever" as charset.

binary-result

binary-result=column names

A comma separated list of columns in the result to not treat as text and decode according to the "charset" attribute or the "Default charset" module setting. As a special case, no result column is decoded if the value is empty.

This is only applicable if a charset is being used and it isn't "unicode" (or "broken-unicode").

Emit plugin values

Iterates over the component values of a string or a compound value. If it's a string, it's split into pieces using a separator string, and the plugin then iterates over the pieces. If it's a compound value like an array then the plugin iterates over its elements.

Attributes

values

values=mixed

The value to iterate over. This attribute is required unless the "variable" or "from-scope" attribute is used.

variable

variable=name

Name of a variable from which the value are taken.

split

split=string (NULL)

The string to split a string value with. Supplying an empty string results in the string being split between every single character. This has no effect if the value isn't a string.

nosplit

If specified then the value isn't split, even when it is a string. Instead the plugin only evaluates its contents once using the whole string.

This is useful if a value might either be a single string or multiple strings as an array, and you want to iterate over each full string.

advanced

advanced={lines, words, csv, chars}

If the value is a string it can be split into multiple fields by using this attribute:

lines

The input is split on individual line-feed and carriage-return characters and in combination. Note that the separator characters are not kept in the output values.

words

The input is split on the common white-space characters (line-feed, carriage-return, space and tab). White-space is not retained in the fields. Note that if a field ends with one of the punctuation marks '.', ',', ':', ';', '!' or '?', the punctuation mark will be removed.

chars

(Characters) The input is split into individual characters.

csv

(Comma-separated values) This input is first split into lines, and the lines then split into fields on ',' and ';' according to CSV quoting rules. Note that this results in a two-dimensional result.

case

case={upper, lower}

Change the case of each returned value.

trimwhites

Trim away all leading and trailing white space charachters from each returned value.

randomize

randomize={yes, no}

Outputs the values in random order if it has the value 'yes'.

distinct

If specified, values are only output once even if they occur several times.

from-scope

from-scope=name

Iterate over a scope like a mapping. &_.index; gets the name of each variable in it and &_.value; gets the corresponding value.

Defined in content

&_.index;

The index of one element. This is set if the value being iterated over is a mapping/scope or a multiset.

&_.value;

The value of one element or substring if a string is being split.

Emit plugin ws-dir

Alias for the "dir" emit source that lists directories. This can be used in case the WebServer "dir" plugin has been overridden. See <emit dir> for full documentation.