Expertsystemen

 

Custom error messages for questions

The Publisher tries to create error messages that are as helpful as can be. However, there is only so much it can do. So, in order to get really accessible messages, there is some more stuff needed.

Compare the sentence:

This field is required.

with

Last name, which is required, had not been filled in. Please do so.

The most important part here is «last name». The Publisher has to get that quotable name from somewhere. Now there are two obvious candidates for that:

  1. The variable name
  2. The label text

The problem with (1) the variable name is that an author might use names that they do not want to be presented to an end-user, and even might confuse them. Plus the variable names are limited to a-z, numbers and the underscore (_) character, so you’re out of luck when using a non-Latin script or any diacritic. Let’s throw this one out the window!

The problem with (2) the label text is that it might have extra text in there besides the bare identifying words.

Most of the time though, the label text does suffice, and it will be used if you ask our consultants to include this feature for you (adding the plugins called control-filter and hacks:label-quotable). The feature will fall back to using the generic terms* (‘this field’ etc.) whenever the label text exceeds 80 characters.

*The generic terms are as ‘this value’ (number), ‘this date’ (date), ‘this field’ (any) and ‘these options’ (a list or grid), according to type.

Meet: quotable (introduced mid-2023)

An author may provide a quotable representation with the metadata quotable. This quotable value supersedes label texts or the generic terms in error messages.

It is advised to use the mid-sentence version in the quotable metadata, so not “Colour”, but “colour”, and not “Family name” but “family name”. Care will be taken to uppercase the first letter when used at the start of the error message.

Providing custom, per question, messages

Sometimes even providing a quotable metadata does not suffice. In that case, it is good to know that any message can be customised per question, by setting a metadata field.

Most often, the only constraint on a field is that it be filled in.

For required, but not filled in, messages, one can use the metadata key errrequired.

Then there is the error arising from a datatype mask. This will throw either the error message defined in the datatype definition, or the one defined in an action using setproperty(^question, 'error', 'my custom error text');

Besides those generic ones, there are special error messages for Number and Date fields that may be overwritten with metadata:

Text:

  • errtexttoolong - for text that exceeds a maximum of characters

Numbers:

  • errnuminvalid - for an invalid number
  • errnumnotinrange - if it is outside the given minimum and maximum range
  • errnumnotnegativeorzero - number has a max of 0; the value is higher than that
  • errnumnotnegative - number has a max of -1; the value is higher than that
  • errnumabovemaximum - number exceeds set maximum
  • errnumnotpositiveorzero - number has minimum of 0; the value is lower than that
  • errnumnotpositive - number has minimum of 1; the value is lower than that
  • errnumbelowminimum - number is lower than set minimum

Dates:

  • errdateinvalid
  • errdatebeforemimimum
  • errdatenotinrange
  • errdateaftermaximum

The messages can be either static text or use variable values.

The following values are made available to all messages:

  • quotable - either the value of quotable in metadata or the generic field reference.
  • quotable--init - the value of quotable above with the first character capitalised. Use this at the start of a sentence.
  • quotable--lower - the value of quotable above in all lowercase.
  • quotable--upper - the value of quotable above in all caps.
  • quoted - the value of st. like the field "<quotable>" OR this field (if there is no special quotable in metadata).
  • quoted--init - quoted, with the first character in uppercase.
  • value - the value given by the user, if any.

String error message may use:

  • maxlength - for texts exceeding a certain length

Number error messages may use the following values:

  • minimum
  • minimum-1 - for messages such as ‘Number X should be higher than 6 (not including, i.e.)’
  • maximum
  • maximum+1 - see minimum-1

Date error messages may use the following values:

  • minimum
  • maximum

You can interpolate these values with {value}, e.g. Did you forget to fill in {quoted}?'.

Custom generic messages

If your organisation has different needs in general, a plugin can provide its own custom generic messages, with interpolation of values such as described above.

A note on languages using inflection and/or gender

In languages that use inflection and/or noun gender (German, French etc), it may be advised to either circumvent back-references and adjectives requiring the text to account for case and or gender, or to write out the possible messages in full, if this leads to very awkward sentences.

We have no system in place accounting for gender and or case as this would get pretty complex quite soon.