Chapter 5 - Validation and errors

First draft. This chapter has not been reviewed yet and may contain mistakes. Please read it with that in mind, and tell us about anything that does not match what you see.

On this page5.1 GetErrorCount 5.2 GetErrors 5.3 ClearErrors 5.4 SetValidationMode 5.5 WriteLog

These five commands work with the form's validation: count the current validation errors, list them as text or in a dialog, clear them, choose how often the form validates, and write messages to the log. The typical use is a Submit button that validates first and refuses to submit while errors remain. Chapter 1 explains the command syntax, dynamic parameter values and where results go; this chapter assumes you know it.

The examples use this main data source:

my:myFields
  my:RequesterName      (validation rule: cannot be blank)
  my:RequesterEmail     (validation rule: must contain @)
  my:Amount
  my:ErrorCount
  my:ErrorMessage

5.1 GetErrorCount

Returns the number of validation errors the form currently has. By default it validates the form first, so the count reflects the current data. Use it before submitting, or to show an error summary.

Syntax

GetErrorCount [/novalidate=true]

Parameter	Required	Description
`/novalidate`	No	`true` returns the errors already recorded, without validating the form again. Default `false`.

Result: the number of errors, for example 0 or 2.

Example

GetErrorCount /resultxpath=/my:myFields/my:ErrorCount

Validates the form and writes the number of errors into ErrorCount.

Notes

With the default /novalidate=false, the validation pass includes schema-required fields, so "cannot be blank" errors on required fields are counted too.
/novalidate=true is faster but can return a stale count: errors on fields changed since the last validation are not refreshed. Leave it out before a submit.
A count of 0 is a normal result; Success is true whether or not there are errors. Test the Result, not Success.

Related: GetErrors, ClearErrors.

5.2 GetErrors

Returns the form's current validation errors as text, one error per line. It can also open a dialog that lists them for the user. Like GetErrorCount, it validates the form first unless told not to.

Syntax

GetErrors [/format=message|fieldAndMessage] [/novalidate=true] [/usepopup=true]

Parameter	Required	Description
`/format`	No	`message` (default) returns only each error's message. `fieldAndMessage` returns `<field name> - <message>`. Case-sensitive.
`/novalidate`	No	`true` returns the errors already recorded, without validating the form again. Default `false`.
`/usepopup`	No	`true` also shows a validation error dialog listing all current errors. Default `false`. No dialog is shown when there are no errors.

Result: the errors, separated by line breaks. Empty when the form has no errors.

Examples

GetErrors /resultxpath=/my:myFields/my:ErrorMessage
GetErrors /format=fieldAndMessage /usepopup=true

The first writes the error messages into ErrorMessage. The second shows the error dialog and returns lines such as RequesterEmail - Enter a valid e-mail address, where the message is the one your validation rule defines.

A validate-before-submit button, with the stop rule above the submit rule:

Rule "Run Validation":
  Run a qRules Command   "GetErrorCount /resultxpath=/my:myFields/my:ErrorCount"
  Run a qRules Command   "GetErrors /format=fieldAndMessage /resultxpath=/my:myFields/my:ErrorMessage"
Rule "Stop if errors" (condition: ErrorMessage is not blank, Stop after this rule runs)
Rule "Submit":
  Submit data

Because GetErrors writes an empty Result when there are no errors, ErrorMessage is cleared on a clean attempt and the stop rule lets the submit through.

Notes

The field name in fieldAndMessage is the field's local name without its prefix (RequesterName, not my:RequesterName). For several errors on fields of the same name, such as rows of a repeating table, the lines look the same; the dialog (/usepopup=true) is clearer for the user.
An unknown /format value fails with Invalid format value: value, but only when there is at least one error. With no errors the command returns an empty Result and Success true.
A count of zero errors is a normal outcome: Success is true whether or not there are errors.

Related: GetErrorCount, ClearErrors.

5.3 ClearErrors

Clears all current validation errors in the form. Use it to remove error markers after you reset the form's data, for example on a Clear or New request button.

Syntax

ClearErrors

This command has no parameters.

Result: empty on success.

Example

ClearErrors

Notes

It does not turn validation off. The next validation pass (a GetErrorCount or GetErrors without /novalidate=true, or the form's validation mode) finds again every error that still applies. To change when the form validates, use SetValidationMode.

Related: GetErrors, SetValidationMode.

5.4 SetValidationMode

Sets how often the form validates while the user works, and whether schema-required fields are included in each validation pass. Run it on QdabraRules > finishedLoading to set the behavior for the whole session, or from a rule to change it later (for example, validate more strictly after the first failed submit).

Syntax

SetValidationMode [/mode=none|auto|afterChange|afterChangeCurrentField|afterErrorChange] [/validaterequiredfields=true|false]

Parameter	Required	Description
`/mode`	At least one of the two	How often to validate: `none` does not validate. `auto` validates everything after every user action (field change, button click and so on). `afterChange` validates everything when the user changes a field. `afterChangeCurrentField` validates only the field the user changes. `afterErrorChange` validates everything when the user changes a field that has a validation error. The default mode of a form is `afterErrorChange`.
`/validaterequiredfields`	At least one of the two	`true` includes schema-required (cannot be blank) fields in validation passes; `false` leaves them out. The default of a form is `false`.

Result: empty on success.

Examples

SetValidationMode /mode=afterChangeCurrentField
SetValidationMode /mode=auto /validaterequiredfields=true
SetValidationMode /validaterequiredfields=false

The first gives immediate feedback on each field as the user fills it in. The second validates everything, including required fields, after every action. The third changes only the required-field setting and keeps the current mode.

Notes

You must give /mode, /validaterequiredfields or both; otherwise the command fails with SetValidationMode requires at least one parameter (/mode or /validaterequiredfields).
Write the mode values exactly as listed (for example afterChange).
A parameter you leave out keeps its current setting.
GetErrorCount and GetErrors validate the form themselves (unless /novalidate=true), whatever the mode. A common setup is /mode=none while the user types and a validate-before-submit button.

Related: GetErrorCount, ClearErrors.

5.5 WriteLog

Writes a message to the Qdabra Forms logging system, at information level. Use it to trace what your rules do while you test a form, for example the value of a field before a submit.

Syntax

WriteLog /message=<text>

Parameter	Required	Description
`/message`	Yes	The text to log.

Result: the message with a UTC timestamp in front, in the form [2026-10-09T17:30:00.000Z] message.

Examples

WriteLog /message=Submit started
WriteLog /message-xpath=/my:myFields/my:Amount

The second logs the current value of Amount, using a dynamic parameter (see Chapter 1).

Notes

The message cannot be empty. An empty /message= fails with Required parameter unspecified: message.
To log a label together with a value, build the message with concat() in the rule, for example concat("WriteLog /message=Amount is ", my:Amount).
The Result is handy with an ExecutionHistory group in QdabraRules (Chapter 1), where each logged message appears with its time.

Related: GetErrors.

Back to the Command Index.

← Dates and numbersForm, view and UI →