Node:Edit controls, Next:Named query definitions, Previous:Field datatypes, Up:dbconfig file
The on-change
subsection of a fields
section specifies one
or more actions to be performed when the field value is edited by the
user. It has the general form
on-change [ "query-expression" ] { [ add-audit-trail ] [ audit-trail-format { format "formatstring" [ fields { "fieldname" ... } ] } ] [ require-change-reason ] [ set-field | append-to-field "fieldname" { "format-string" [ fieldlist ] } ] [ require { "fieldname" ... } ] }
The optional query-expression
controls whether or not the actions
in the on-change
section are taken. If the expression fails to
match, the actions are skipped.
The add-audit-trail
option indicates that an entry should be
appended to the PR's audit-trail when this field is changed. The format
of the entry is controlled by the optional audit-trail-format
section within the field, or by the global audit-trail-format
section. See Audit-trail formats and Outgoing email formats.
The require-change-reason
option specifies that a change reason
must be present in the PR when this field is edited. This option only
makes sense if an audit-trail entry is required, as the change reason is
otherwise unused.
The set-field
and append-to-field
options are used to
change the value of the field fieldname
in the PR. The supplied
format is used to format the value that will be placed in the field.
append-to-field
appends the resulting formatted string to the
existing, while set-field
completely replaces the contents.
Any field may be edited by the set-field
or
append-to-field
option (the read-only
option on a field is
ignored). However, the changes are subject to the usual field content
checks.
The require
option specifies that one or more fields must have
a (non-blank) value when this field is changed.
A field may be enforced to have a (non-blank) value at all times by including it in the set of fields required for the initial PR, see Initial PR input fields, as well as in the set of fields required on change of the field itself.
There is also a global on-change
section that is executed once
for each PR edit. A typical use for such a section is to set the
last-modified date of the PR.