 | w i z a r d 4 j |
| w i z a r d 4 j |
| Overview |
| Flowcharts |
| Xml Language |
| Reference |
| Dia |
| Examples |
| Try It |
| Engine |
| Getting Started |
| Tuning |
| JavaDoc |
| Mailing Lists |
| Download |
| License |
This section contains a detailed description of the flowchart xml language.
Before describing each of the flowchart elements, their attributes and child elements, we provide an overview of which element can contain which element. Grey cells indicate that there is no containment possible.
| contains | flowchart | root | fragment | branch | info | input | switch | loop | fragmentPointer | value | option |
|---|---|---|---|---|---|---|---|---|---|---|---|
| flowchart | 1 | 0-N | |||||||||
| root | 0-N | 0-N | 0-N | 0-N | 0-N | ||||||
| fragment | 0-N | 0-N | 0-N | 0-N | 0-N | ||||||
| branch | 0-N | 0-N | 0-N | 0-N | 0-N | ||||||
| info | |||||||||||
| input | 0-N | 0-N | |||||||||
| switch | 2-N | ||||||||||
| loop | 0-N | 0-N | 0-N | 0-N | 0-N | ||||||
| fragmentPointer | |||||||||||
| value | |||||||||||
| option |
The <flowchart> element is the root element of the flowchart description. It contains exactly one <root> element and 0 or more <fragment> elements. A <fragment> is a piece of a flowchart that is used multiple times and that can be pointed at by a <fragmentPointer> element. One can compare a <fragment> with a subroutine or a function.
This element has no attributes.
The <root> element is the starting point of the flowchart. It has a number of attributes that specify the default attribute values of other flowchart elements. If these defaults are not explicitly set, the defaults of the xsd file are used (cfr. column Default).
| Attribute | Mandatory | Default | Description |
|---|---|---|---|
| defaultMinNbrOfChars | N | 0 | If the min attribute of an input element of type string or stringArray is not specified, the value in this attribute will be used for the minimum number of characters in the string. |
| defaultMaxNbrOfChars | N | 30 | If the max attribute of an input element of type string or stringArray is not specified, the value in this attribute will be used for the maximum number of characters in the string. |
| defaultMinNbrOfElements | N | 1 | If the minNbrOfElements attribute of an input element of type stringArray is not specified, the value in this attribute will be used for the minimum number of elements in the stringArray. |
| defaultMaxNbrOfElements | N | 1 | If the maxNbrOfElements attribute of an input element of type stringArray is not specified, the value in this attribute will be used for the maximum number of elements in the stringArray. |
| defaultMinIntValue | N | 0 | If the min attribute of an input element of type integer is not specified, the value in this attribute will be used for the minimum value of the integer. |
| defaultMaxIntValue | N | 100 | If the max attribute of an input element of type integer is not specified, the value in this attribute will be used for the maximum value of the integer. |
| defaultMinDecValue | N | 0.00 | If the min attribute of an input element of type decimal is not specified, the value in this attribute will be used for the minimum value of the decimal. |
| defaultMaxDecValue | N | 100.00 | If the max attribute of an input element of type decimal is not specified, the value in this attribute will be used for the maximum value of the decimal. |
| defaultMinYear | N | 0 | If the min attribute of an input element of type date or dateTime is not specified, the value in this attribute will be used for the minimum value of the year in date or dateTime. |
| defaultMaxYear | N | 10 | If the max attribute of an input element of type date or dateTime is not specified, the value in this attribute will be used for the maximum value of the year in date or dateTime. |
| defaultIncrement | N | 1 | If the increment attribute of an input element of type integer or decimal is not specified, the value in this attribute will be used as the increment of the integer or decimal (to understand the use of increment with the decimal type, see the increment description). |
| defaultNbrOfDecimals | N | 2 | If the nbrOfDecimals attribute of an input element of type decimal is not specified, the value in this attribute will be used as the number of decimals. |
| defaultRelativeToCurrentYear | N | true | If the relativeToCurrentYear attribute of an input element of type date or dateTime is not specified, the value in this attribute will be used as the value for the relativeToCurrentYear attribute. |
| defaultMinNbrOfIterations | N | 1 | If the minNbrOfIterations attribute of a loop element of type nbrOfIterations is not specified, the value in this attribute will be used for the minimum number of iterations in the loop. |
| defaultMaxNbrOfIterations | N | 3 | If the maxNbrOfIterations attribute of a loop element of type nbrOfIterations is not specified, the value in this attribute will be used for the maximum number of iterations in the loop (its maximum value is 100). |
It is not uncommon that a flowchart contains the same sequence of elements in various locations. To avoid duplication in a flowchart tree, one can extract a subtree of this flowchart tree and put it aside in a fragment. The <fragment> element is the root of this subtree. It has a single attribute 'name'. The removed subtree is replaced by a <fragmentPointer> element that refers to the fragment by its name.
A fragment itself can contain fragmentPointers referring to other fragments. To avoid loops of fragments pointing to each other, the fragments must be ordered: a fragment must be listed after the fragment(s) which have a fragmentPointer to the fragment.
| Attribute | Mandatory | Default | Description |
|---|---|---|---|
| name | Y | The name of this element instance. The name must be unique in the flowchart. It is only used internally. It is not visible to the user. |
This element allows to present an 'informational' screen to the user. The user is not asked for any input. This type of element is useful for e.g. indicating the progress of the flowchart, giving introductory information on the questions that will follow, etc.
| Attribute | Mandatory | Default | Description |
|---|---|---|---|
| name | Y | The name of this element instance. The name must be unique on its branch. It is only used internally. It is not visible to the user. | |
| label | Y | This is the text that a user will see. | |
| help | N | This is the content of the help function. Html formatting is allowed, but the html tags must be xml escaped. |
This element will prompt the user for input. Several input types are defined. Each input element can have a number of optional attributes that describe the constraints for this input. A detailed description of all input types and their attributes is given below.
| Attribute | Mandatory | Default | Description |
|---|---|---|---|
| name | Y | The name of this element instance. The name must be unique on its branch. It can be used to refer to user input when constructing the output. It is not visible to the user. | |
| label | Y | This is the text that a user will see and that should describe the requested input. | |
| help | N | This is the content of the help function. Html formatting is allowed, but the html tags must be xml escaped. | |
| type | Y | At the moment following input types are supported: string, stringArray, integer, decimal, boolean, date, time and dateTime. | |
| type specific attributes | |||
| min | N |
This attribute contains an integer value of which the semantics depend on the input type:
If this attribute is not specified, the corresponding attribute of the root element is used to set the value. | |
| max | N | Similar to the min attribute. | |
| minNbrOfElements | N | This attribute specifies the minimum number of elements for the stringArray type. | |
| maxNbrOfElements | N | This attribute specifies the maximum number of elements for the stringArray type. | |
| increment | N | This attribute is only relevant for the integer
and decimal types.
| |
| nbrOfDecimals | N | The number of decimals for an input of type decimal. | |
| relativeToCurrentYear | N | This attribute is only relevant for the date and dateTime types. Indicates whether min/max are absolute or an offset relative to the current year. | |
| regExp | N | This attribute allows to specify a regular expression to which the input must match (only for types string and stringArray).
The syntax of the regular expressions is described here. There are also a number of predefined values
one can use. These are taken from the regular expression library, so all credits should go to the people contributing at that site:
| |
This <value> element can be used to store a default value(s) for the input element. The value element has no attributes. The formatting of the default values for the various types is described in the next table.
| InputType | Example | Description |
|---|---|---|
| string | some input string | |
| integer | 123 | |
| decimal | 12.87 | two integers separated by a '.' |
| boolean | false | true or false |
| date | 2006-09-28 | formatted as yyyy-MM-dd |
| time | 14:34:42 | formatted as HH:mm:ss |
| dateTime | 2006-09-28T14:34:42 | formatted as yyyy-MM-dd'T'HH:mm:ss |
For type stringArray multiple value elements can be specified.
If the number of allowed values for string or stringArray is limited, one can use the <option> element. The types string and stringArray can contain multiple option elements to store the allowed values as well as the default value(s). Option elements can not be combined with value elements within a single input element.
| Attribute | Mandatory | Default | Description |
|---|---|---|---|
| value | Y | A possible value for the parent input element. | |
| label | Y | The string that will be used to present this option to the user. | |
| selected | N | false | To indicate whether this option is a/the default. |
The <switch> element will also prompt the user for input, but the difference with the input element is that the provided input will determine the branch that will be followed in the flowchart. This element is also more flexible than the binary decisions in traditional flowcharts. It is possible to select one out of multiple branches or even to select a subset of branches. In the latter case the branches will be executed in the order in which they are listed in the flowchart description.
| Attribute | Mandatory | Default | Description |
|---|---|---|---|
| name | Y | The name of this element instance. The name must be unique on its branch. It is not visible to the user. | |
| label | Y | This is the text that a user will see and that describes the decision to be taken. | |
| help | N | This is the content of the help function. Html formatting is allowed, but the html tags must be xml escaped. | |
| minNbrOfBranches | N | 1 | The minimum number of branches that need to be selected by the user. |
| maxNbrOfBranches | N | 1 | The maximum number of branches that can be selected by the user. |
The <branch> element is introduced to explicitly define a branch of a <switch> element.
| Attribute | Mandatory | Default | Description |
|---|---|---|---|
| name | Y | The name of this element instance. The name must be unique within the switch. It is not visible to the user. | |
| label | Y | The string that will be used to present this switch option (branch) to the user. | |
| selected | N | false | To indicate whether this branch is selected by default. |
This element allows to execute a 'flowchart section' multiple times. The number of iterations can be fixed or the user can be queried to specify the (number of) iterations.
| Attribute | Mandatory | Default | Description | |||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| name | Y | The name of this element instance. The name must be unique on its branch. It will also be used in the user interaction to announce the next iteration. | ||||||||||||||||||||||||||||||||||
| label | Y | This is the text that a user will see at the start of a loop and that should guide the user when a decision on the number of iterations or the subset of iterations needs to be taken. | ||||||||||||||||||||||||||||||||||
| help | N | This is the content of the help function. Html formatting is allowed, but the html tags must be xml escaped. | ||||||||||||||||||||||||||||||||||
| mode | Y |
At the moment there are three main loop modes:
When the attributes minNbrOfIterations and maxNbrOfIterations are specified in the list mode, the user will be asked to select an appropriate subset of the list (if only one attribute is present, the other one will be set to either min=0 or max=nbrOfListElements. When both attributes are absent the loop will iterate over all elements in the list. When the attributes minNbrOfIterations and maxNbrOfIterations are not specified in the nbrOfIterations mode, the corresponding root attributes will be used. If minNbrOfIterations equals maxNbrOfIterations, the number of iterations is fixed and there will be no user interaction. If minNbrOfIterations < maxNbrOfIterations: the user will be prompted to select the number of iterations. When the attributes minNbrOfIterations and maxNbrOfIterations are not specified in the userInterrupted mode, the corresponding root attributes will be used. If minNbrOfIterations equals maxNbrOfIterations, the number of iterations is fixed and there will be no user interaction. If minNbrOfIterations < maxNbrOfIterations: the user will be prompted whether he/she wants to execute another iteration (for iterations minNbrOfIterations to maxNbrOfIterations-1). When the attribute maxNbrOfIterations is not specified in the doWhile mode, the corresponding root attribute will be used. | ||||||||||||||||||||||||||||||||||
| list | N | Only used in the list mode. It is a ',' separated list of strings, each specifying an iteration, e.g. "red,blue,yellow". | ||||||||||||||||||||||||||||||||||
| minNbrOfIterations | N | See description mode attribute. | ||||||||||||||||||||||||||||||||||
| maxNbrOfIterations | N | See the description of the mode attribute (its maximum value is 100). | ||||||||||||||||||||||||||||||||||
| anotherIterationQuestion | N | Only for mode 'userInterrupted'. | ||||||||||||||||||||||||||||||||||
| condition | N | Only for mode 'doWhile'. It must contain a wizard4j boolean expression. The boolean expression can be simple or composed. For
composed expressions the traditional precedence rules apply and precedence can also be specified by the use of
parentheses: '(' and ')'. Operators, operands and parentheses MUST be separated by whitespace. A literal operand
that contains whitespaces or parentheses or that equals an operator name, must be enclosed by single quotes (') to indicate that it is a (single)
operand (note that a single quote is a special character in xml, but it can be used safely in an attribute when the
attribute delimitors are double quotes (")). Note that traditional
names of operators (e.g. '&&', '<=') are not used since they contain characters that are special in xml. The
operands can be parameters (input or branch elements specified by their full path) or literals.
The next table gives an overview of the supported operators and their use.
Example: ( /branch1/name != 'Joe Smith' ) AND ( /loop/*/age LTE 40 ) |
The <fragmentPointer> element points to a <fragment>.
| Attribute | Mandatory | Default | Description |
|---|---|---|---|
| name | Y | The name of the element instance. | |
| ref | Y | The reference to the name of the fragment. |