Elements to be used in the XML description of the plugin

Properties held by the elements are listed in a separate section.

General elements

<document>

Needs to be present in each description.xml-file as the root-node. No special function. No attributes

<about>

Information about this plugin (author, licence, etc.). This element is allowed in both an individual plugin's .xml file, and in .pluginmap files. Refer to the .pluginmap file reference for reference details, the chapter on 'about' information for an introduction.

<code>

Defines where to look for the JS template to the plugin. Use only once per file, as a direct child of the document-tag. Attributes:

file: Filename of the JS template, relative to the directory the plugin-xml is in

<help>

Defines where to look for the help file for the plugin. Use only once per file, as a direct child of the document-tag. Attributes:

file: Filename of the help file, relative to the directory the plugin-xml is in

<copy>

Can be used as a child (direct or indirect) of the main layout elements, i.e. <dialog> and <wizard>. This is used to copy an entire block a XML elements 1:1. Attributes:

id: The ID to look for. The <copy> tag will look for a previous XML element that has been given the same ID, and copy it including all descendant elements.
copy_element_tag_name: In some few cases, you will want an almost literal copy, but change the tag-name of the element to copy. The most important example of this is, when you want to copy an entire <tab> from a dialog interface to the <page> of a wizard interface. In this case, you would set copy_element_tag_name="page" to do this conversion automatically.

Interface definitions

<dialog>

Defines a dialog-type interface. Place the GUI definition inside this tag. Use only once per file, as a direct child of the document-tag. At least one of "dialog" or "wizard" tags is required for a plugin. Attributes:

label: Caption for the dialog
recommended: Should the dialog be used as the "recommended" interface (i.e. the interface that will be shown by default, unless the user has configured RKWard to default to a specific interface)? This attribute does not currently have an effect, as it is implicitly "true", unless the wizard is recommended.

<wizard>

Defines a wizard-type interface. Place the GUI definition inside this tag. Use only once per file, as a direct child of the document-tag. At least one of "dialog" or "wizard" tags is required for a plugin. Accepts only <page> or <embed>-tags as direct children. Attributes:

label: Caption for the wizard
recommended: Should the wizard be used as the "recommended" interface (i.e. the interface that will be shown by default, unless the user has configured RKWard to default to a specific interface)? Optional, defaults to "false".

Layout elements

All elements in this section accept an attribute id="identifierstring". This attribute is optional for all elements. It can be used, for example, to hide/disable the entire layout element and all the elements contained therein (see chapter GUI logic). The id-string may not contain "." (dot) or ";" (semicolon), and should generally be limited to alphanumeric characters and the underscore ("_"). Only the additional attributes are listed.

<page>

Defines a new page inside a wizard. Only allowed as a direct child of a <wizard> element.

<row>

All direct children of a "row" tag will be placed left-to-right.

<column>

All direct children of a "column" tag will be placed top-to-bottom.

<stretch>

By default, elements in the GUI take up all the space that is available. For instance, if you have two columns side by side, the left one is packed with elements, but the right one only contains a lonely <radio>, the <radio> control will expand vertically, even though it does not really need the available space, and it will look ugly. In this case you really want to add a "blank" below the <radio>. For this, use the <stretch> element. It will simply use up some space. Do not overuse this element, usually it is a good idea for GUI elements to get all the available space, only sometimes will the layout become spaced out. The <stretch> element does not take any arguments, not even an "id". Also you can place no children inside the <stretch> element (in other words, you will only ever use it as "<stretch/>")

<frame>

Draws a frame/box around its direct children. Can be used to visually group related options. Layout inside a frame is top-to-bottom, unless you place a <row> inside. Attributes:

label: Caption for the frame (optional)
checkable: Frames can be made checkable. In this case, all contained elements will be disabled when the frame is unchecked, and enabled, when it is checked. (optional, defaults to "false")
checked: For checkable frames only: Should the frame be checked by default? Defaults to "true". Not interpreted for non-checkable frames.

<tabbook>

Organizes elements in a tabbook. Accepts only <tab>-tags as direct children.

<tab>

Defines a page in a tabbook. Place the GUI definition for the tab inside this tag. May be used only as a direct child of a <tabbook> tag. A <tabbook> should have at least two defined tabs. Attributes:

label: Caption for the tab page (required)

<text>

Shows the text enclosed in this tag in the GUI. Some simple HTML style markup is supported (notably <b>, <i>, <p>, and <br/>). Please keep formatting to a minimum, however. Inserting a completely empty line adds a hard line break. Attributes:

type: Type of the text. One of "normal", "warning" or "error". This influences the look of the text (optional, defaults to normal)

Active elements

All elements in this section accept an attribute id="identifierstring". This attribute is required for all elements. Only the additional attributes are listed. The id-string may not contain "." (dots).

<varselector>

Provides a list of available objects from which the user can select one or more. Requires one or more <varslot>s as a counterpart to be useful. Attributes:

label: Label for the varselector (optional, defaults to "Select variable(s)")

<varslot>

Used in conjunction with a "varselector" to allow the user to select one or more variables. Attributes:

label: Label for the varslot (recommended, defaults to "Variable:")
source: The varselector to fetch the selection from (required, unless you connect manually or using source_property)
source_property: An arbitrary property to copy values from, when the select button is clicked. If specified, this overrides the "source"-attribute.
required: Whether - for submitting the code - it is required that this varslot holds a valid value. See required-property (optional, defaults to false)
multi: Whether the varslot holds only one (default, "false"), or several objects
allow_duplicates: Whether the varslot may accept only unique objects (default, "false"), or if the same object may be added several times.
min_vars: Only meaningful if multi="true": Minimum number of vars to be selected for the selection to be considered valid (optional, defaults to "1")
min_vars_if_any: Only meaningful if multi="true": Some varslots may be considered valid, if, for instance, the varslot is either empty, or holds at least two values. This specifies how many variables have to be selected if any at all (2 in the example). (optional, defaults to "1")
max_vars: Only meaningful if multi="true": Maximum number of variables to select (optional, defaults to "0", which means no maximum)
classes: If you specify one or more R classnames (separated by spaces (" ")), here, the varslot will only accept objects belonging to those classes (optional, use with great care, the user should not be prevented from making valid choices, and R has a lot of different classes)
types: If you specify one or more variables types (separated by spaces (" ")), here, the varslot will only accept objects of those types. Valid types are "unknown", "number", "string", "factor", "invalid". (Optional, use with great care, the user should not be prevented from making valid choices, and RKWard does not always know the type of a variable)
num_dimensions: The number of dimensions, an object needs to have. "0" (the default) means, any number of dimensions is acceptable. (optional, defaults to "0")
min_length: The minimum length, an object needs to have in order to be acceptable. (optional, defaults to "0")
max_length: The maximum length, an object needs to have in order to be acceptable. (optional, defaults to the largest integer number representable on the system)

<valueselector>

Provides a list of available strings (not R objects) to be selected in one or more accompanying <valueslot>s. String options can be defined using <option>-tags as direct children (see below), or set using dynamic properties. Attributes:

label: Label for the valueselector (optional, defaults to no label)

<valueslot>

Used in conjunction with a <valueselector> to allow the user to select one or more string items. This element is mostly identical to <varslot>, and shares the same attributes, except for those which refer to properties of the acceptable items (i.e. classes, types, num_dimensions, min_length, max_length).

<radio>

Defines a group of radio-exclusive buttons (only one can be selected at a time). Requires at least two <option>-tags as direct children. No other tags are allowed as children. Attributes:

label: Label for the radio control (recommended, defaults to "Select one:")

<dropdown>

Defines a group of options of which one and only one can be selected at the same time, using a dropdown list. This is functionally equivalent to a <radio>, but looks different. Requires at least two <option>-tags as direct children. No other tags are allowed as children. Attributes:

label: Label for the dropdown list (recommended, defaults to "Select one:")

<select>

Provides a list of available strings from which the user can select an arbitrary number. String options can be defined using <option>-tags as direct children (see below), or set using dynamic properties. Attributes:

label: Label for the <select> (optional, defaults to no label)
single: If set to true, only a single value will be selectable, instead of multiple values at once (boolean, defaults to false)

<option>

Can only be used as a direct child of a <radio>, <dropdown>, <valueselector> or <select> element. Represents one selectable option in a radio control or dropdown list. As <option> elements are always part of one of the selection elements, they do not normally have an "id" of their own, but see below. Attributes:

label: Label for the option (required)
value: The string value the parent element will return if this option is checked/selected (required)
checked: Whether the option should be checked/selected by default "true" or "false". In a <radio> or <dropdown>, only one option may be set to checked="true", and if no option is set to checked, the first option in the parent element will be checked/selected automatically. In a <select>, any number of options may be set to checked. (optional, default to "false")
id: Specifying the "id" parameter for the <option> elements is optional (and in fact it is recommended, not to set an "id", unless you really need one). However, specifying an "id" will allow you to enable/disable <option>s, dynamically, by connecting to the boolean property id_of_radio.id_of_optionX.enabled. Currently this works for options inside <radio> or <dropdown> elements, only; <valueselector> and <select> options do not currently support ids.

<checkbox>

Defines a check box, i.e. a single option that can either be set to on or off. Attributes:

label: Label for the check box (required)
value: The value the check box will return if checked (required)
value_unchecked: The value that will be returned if the check box is not checked (optional, defaults to "", i.e. an empty string)
checked: Whether the option should be checked by default "true" or "false" (optional, default to "false")

<frame>

The frame element is generally used as a pure layout element, and is listed in the section on layout elements. However, it can also be made checkable, thus acting like a simple check box at the same time.

<input>

Defines a free text input field. Attributes:

label: Label for the input field (required)
initial: Initial text of the text field (optional, defaults to "", i.e. an empty string)
size: One of "small", "medium", or "large". "large" defines a multi-line input field, "small", and "medium" are single line fields (optional, defaults to "medium")
required: Whether - for submitting the code - it is required that this input is not empty. See required-property (optional, defaults to false)

<matrix>

A table for entering matrix data (or vectors) in the GUI.

Note

This input element is not optimized for entering/editing large amounts of data. While there is no strict limit on the size of a <matrix>, in general it should not exceed around ten rows / columns. If you expect larger data, allow users to select it as an R object (which may be a good idea as an alternative option, in almost every instance where you use a matrix element).

Attributes:

label

Label for the table (required)

mode

One of "integer", "real", or "string". The type of data that will be accepted in the table (required)

min

Minimum acceptable value (for matrices of type "integer" or "real") (optional, defaults to the smallest representable value)

max

Maximum acceptable value (for matrices of type "integer" or "real") (optional, defaults to the largest representable value)

allow_missings

Whether missing (empty) values are allowed in the matrix. This is implied for matrices or mode "string" (optional, defaults to false).

allow_user_resize_columns

When set to true, the user can add columns by typing on the rightmost (inactive) cells (optional, defaults to true).

allow_user_resize_rows

When set to true, the user can add rows by typing on the bottommost (inactive) cells (optional, defaults to true).

rows

Number of rows in the matrix. Has no effect for allow_user_resize_rows="true".

Note

This can also be controlled by setting the "rows" property.

(optional, defaults to 2).

columns

Number of columns in the matrix. Has no effect for allow_user_resize_columns="true".

Note

This can also be controlled by setting the "columns" property.

(optional, defaults to 2).

min_rows

Minimum number of rows in the matrix. The matrix will refuse shrink below this size. (optional, defaults to 0; see also: allow_missings.).

min_columns

Minimum number of columns in the matrix. The matrix will refuse shrink below this size. (optional, defaults to 0; see also: allow_missings.).

fixed_height

Force the GUI element to stay at its initial height. Do not use in combination with matrices, where the number of rows may change in any way. Useful, esp. when creating a vector input element (columns="1"). With this option set to true, no horizontal scroll bar will be shown, even in the matrix exceeds the available width (as this would affect the height). (optional, defaults to false).

fixed_width

Slightly misnamed: Assume the column count will not change. The last (or typically only) column will be stretched to take up the available width. Do not use in combination with matrices, where the number of columns may change in any way. Useful, esp. when creating a vector input element (rows="1"). (optional, defaults to false).

horiz_headers

Strings to use for the horizontal header, separated by ";". The header will be hidden, if set to "". (optional, defaults to column number).

vert_headers

Strings to use for the vertical header, separated by ";". The header will be hidden, if set to "". (optional, defaults to row number).

<optionset>

A UI for repeating a set of options for an arbitrary number of items (introduction to optionsets). Attributes:

min_rows: If specified, the set will be marked invalid, unless it has at least this number of rows (optional, integer).
min_rows_if_any: Like min_rows, but will only be tested, if there is at least one row (optional, integer).
max_rows: If specified, the set will be marked invalid, unless it has at most this number of rows (optional, integer).
keycolumn: Id of the column to act as keycolumn. An optionset with a (valid) keycolumn will act as a "driven" optionset. An optionset with no keycolumn will allow manual insertion / removal of items. The keycolumn must be marked as external. (optional, defaults to no keycolumn).

Child-elements:

<optioncolumn>

Declares one optioncolumn of the set. For each value that you want to fetch from the optionset, you must declare a separate <optioncolumn>. Attributes:

id: The id of the optioncolumn (required, string).
external: Set to true, if the optioncolumn is controlled from outside the optionset (optional, boolean, defaults to false).
label: If given, the optioncolumn will be displayed in a column by that label (optional, string, defaults to not displayed).
connect: The property to connect this optioncolumn to, given as id inside the <content>-area. For external <optioncolumn>s, the corresponding value will be set to the externally set value. For regular (non-external) <optioncolumn>s, the corresponding row of the <optioncolumn>-property, will be set when the property changes inside the content-area. (optional, string, defaults to not connected).
default: Only for external columns: The value to assume for this column, if no value is known for an entry. Rarely useful. (Optional, defaults to empty string)

<content>

Declare the content / UI of the set. No attributes. All usual active, passive, and layout elements are allowed as childname elements. In addition, in earlier versions of RKWard (up to 0.6.3), the special child-element <optiondisplay> was allowed. This is obsolete in RKWard 0.6.4, and should simply be removed from existing plugins.

<logic>

Optional specification of UI logic to apply inside the contents region the optionset. See the reference on <logic>

<browser>

An element designed to select a single filename (or directory name). Note that this field will take any string, even though it is meant to be used for files, only:

label: Label for the browser (optional, defaults to "Enter filename")
initial: Initial text of the browser (optional, defaults to "", i.e. an empty string)
type: One of "file", "dir", or "savefile". To select an existing file, existing directory, or non-existing file, respectively (optional, defaults to "file")
allow_urls: Whether (non-local) URLs can be selected (optional, defaults to "false")
filter: File type filter, e.g. ("*.txt *.csv" for .txt and .csv files). A separate entry for "All files" is added, automatically (optional, defaults to "", i.e. All files)
required: Whether - for submitting the code - it is required that the field is not empty. Note that this does not necessarily mean that the selected filename is valid. See required-property (optional, defaults to true)

<saveobject>

An element designed to select the name of an R object to save to (i.e. generally not already existing, in contrast to a varslot):

label: Label for the input (optional, defaults to "Save to:")
initial: Initial text of the input (optional, defaults to "my.data")
required: Whether - for submitting the code - it is required that the field holds a permissible object name. See required-property (optional, defaults to true)
checkable: In many use cases, saving to an R object is optional. In these cases, a check box can be integrated into the saveobject-element using this attribute. When set to true, the saveobject will be activated / deactivated by the check box. See the active-property of saveobject (optional, defaults to false)
checked: For checkable saveobject-elements, only: Whether the control is checked/enabled by default (optional, defaults to false)

<spinbox>

A spinbox in which the user can select a numeric value, using either direct keyboard input or small up/down arrows. Attributes:

label: Label for the spinbox (recommend, default to "Enter value:")
min: The lowest value the user is allowed to enter in the spinbox (optional, defaults to the lowest value technically representable in the spinbox)
max: The largest value the user is allowed to enter in the spinbox (optional, defaults to the highest value technically representable in the spinbox)
initial: The initial value shown in the spinbox (optional, defaults to "0")
type: One of "real" or "integer". Whether the spinbox will accept real numbers or only integers (optional, defaults to "real")
default_precision: Only meaningful if the spinbox is of type="real". Specifies the default number of decimal places shown in the spinbox (only this many trailing zeros will be shown). When the user presses the up/down arrows, this decimal place will be changed. The user may still be able to enter values with a higher precision, however (see below) (optional, defaults to "2")
max_precision: The maximum number of digits that can be meaningfully represented (optional, defaults to "8")

<formula>

This advanced element allows the user to select a formula/set of interactions from selected variables. For instance for a GLM, this element can be used to allow the user to specify the interaction-terms in the model. Attributes:

fixed_factors: The ID of the varslot holding the selected fixed factors (required)
dependent: The ID of the varslot holding the selected dependent variable (required)

<embed>

Embed a different plugin into this one (see chapter on embedding). Attributes:

component: The registered name of the component to embed (see chapter on registering components) (required)
as_button: If set to "true", only a pushbutton will be placed in the embedding GUI, the embedded GUI will only be shown (in a separate window) when the pushbutton is pressed (optional, default is "false")
label: Only meaningful if as_button="true": The label of the button (recommend, default is "Options")

<preview>

Checkbox to toggle preview functionality. Note that starting with version 0.6.5 of RKWard <preview> preview elements are special- cased in plugin dialogs (not wizards): They will be placed in the button-column, irrespective of where exactly they are defined in the UI. It is still a good idea to define them at a sensible place in the layout, for backwards compatibility. Attributes:

label: Label of the box (optional, default is "Preview")
mode: Type of preview. Supported types are "plot" (see chapter on graph previews), "output" (see chapter on (HTML) output previews), "data" (see data previews), and "custom" (see custom previews). (optional, default is "plot")
placement: Placement of the preview: "attached" (to the main workplace), "detached" (standalone window), "docked" (attached to the plugin dialog) and "default" (currently this is the same as "docked", but might become user-configurable at some point). In general, it is recommended to leave this as the default setting for best UI-consistency (optional, default is "default")
active: Whether the preview is active by default. In general, only docked previews should be made active by default, and even for these, there is a reason why the default is in-active previews (optional, default is "false")

Logic section

<logic>

The containing element for the logic section. All elements below are allowed only inside the <logic> element. The <logic> element is allowed only as a direct child of the <document> element (at most once per document), or of <optionset> elements (at most once per optionset). The document's logic section applies to both <dialog> and <wizard> GUIs in the same way.

<external>

Creates a new (string) property that is supposed to be connected to an outside property if the plugin gets embedded. See section on "incomplete" plugins. Attributes:

id: The ID of the new property (required)
default: The default string value of the new property, i.e. the value used, if the property is not connected to an outside property (optional, defaults to an empty string)

<i18n>

Creates a new (string) property that is supposed to be provide an i18n'ed label. Attributes:

id: The ID of the new property (required)
label: The label. This will be translated. (required)

<set>

Set a property to a fixed value (of course, if you additionally connect the property to some other property, the value does not remain fixed). For instance, if you embed a plugin, but want to hide some of its elements, you might set the visibility property of those elements to false. Useful esp. for embedded/embedding plugins. Note: If there are several <set> elements for a single id, the latest one to be defined takes precedence. This will sometimes be useful to rely on when using <include>d parts. Attributes:

id: The ID of the property to set (required)
to: The string value to set the property to (required). Note: For boolean properties such as visibility, enabledness, you will typically set the to attribute to either to="true" or to="false".

<convert>

Create a new boolean properties that depends on the state of one or more different properties. Attributes:

id: The ID of the new property (required)
sources: The ids of the properties this property will depend on. One or more properties may be specified, separated by ";" (required)
mode: The mode of conversion/operation. One of "equals", "notequals", "range", "and", "or". If in mode equals, the property will only be true, if the value of all of its sources equals the attribute standard (see below). If in at mode notequals, the property will only be true, if the value of all of its sources are different from the attribute standard (see below). If in mode range, the sources have to be numeric (integer or real). The property will only be true, if all sources are in the range specified by the attributes min and max (see below). If in mode and, the sources have to be boolean properties. The property will only be true, if all the sources are true simultaneously. If in mode or, the sources have to be boolean properties. The property will only be true, if at least one of the sources is true. (required)
standard: Only meaningful in modes equals or notequals: the string value to compare against (required if in one of these modes)
min: Only meaningful in mode range: the minimum value to compare against (optional, defaults to the lowest floating point number representable on the machine)
max: Only meaningful in mode range: the maximum value to compare against (optional, defaults to the largest floating point number representable on the machine)
require_true: If set to "true", the property will become required, and will only be considered valid, if its state is true/on. Hence, if the property is false, it will block the Submit button (optional, defaults to "false").
Caution
If you use this, make sure the user can easily detect what is wrong, such as by showing an explanatory <text>.

<switch>

Create a new property that will relay to different target properties (or fixed strings) based on the value of a condition property. This allows to create logic similar to if() or switch() constructs. Attributes:

id: The ID of the new property (required)
condition: The id of the condition property (required)

Child elements:

<true>: If the condition property is boolean, you can specify the two child elements <true> and <false> (and only these). (Required, if <false> is also given)
<false>: If the condition property is boolean, you can specify the two child elements <true> and <false> (and only these). (Required, if <true> is also given)
<case>: If the condition property is not boolean, you can supply an arbitrary number of <case>-elements, one for each value of the condition property that you want to match (at least one such element is required, if the condition property is not boolean)
<default>: If the condition property is not boolean, the optional <default>-element, allows to specify the behavior, if no <case> element is matches the value of the condition property (optional, allowed only once, in combination with one or more <case> elements).

Child elements <true>, <false>, <case>, and <default> take the following attributes:

standard: Only for <case>-elements: The value to match the condition property against (required, string).
fixed_value: A fixed string that should be supplied as the value of the <switch> property, if the current condition matches (required, if dynamic_value is not supplied).
dynamic_value: The id of the target property that should be supplied as the value of the <switch> property, if the current condition matches (required, if fixed_value is not supplied).

<connect>

Connects two properties. The client property will be changed whenever the governor property changes (but not the other way around). Attributes:

client: The ID of the client property, i.e. the property that will be adjusted (required)
governor: The ID of the governor property, i.e. the property that will adjusts the client property. This may include a modifier (required)
reconcile: If "true", the client property will make adjust the governor property on connection in such a way that the governor property will only accept values that are also acceptable by the client (e.g. suppose the governor is a numeric property with min value "0", and the client is a numeric property with min value "100". The min of both properties will be adjusted to 100, if reconcile="true"). Generally works only for properties of the same basic type (optional, default to "false")

<dependency_check>

Creates a boolean property that is true, if the specified dependencies are met, false otherwise. The XML syntax of the element is the same as that of the <dependencies> element, described in the .pluginmap reference. As of RKWard 0.6.1, only the RKWard and R version specifications are taken into account, not dependencies on packages or pluginmaps.

<script>

Define script code to control UI logic. See the section on scripted GUJI logic for details. The script code to run can be given either using the "file" attribute, or as a (commented) text of the element. The <script> element is not allowed in the <logic> section of an optionset. Attributes:

file: File name of the script file. (required)

Prev	Contents	Next
General purpose elements to be used in any XML file (`.xml`, `.rkh`, `.pluginmap`)	Up	Properties of plugin elements

Elements to be used in the XML description of the plugin