4.3.4 Edit controls

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.

This document was generated by Chad Walstrom on March 3, 2015 using texi2html 1.82.