Field conditions in Studio

In Studio, a field can behave differently depending on the record it sits in. A condition looks at another field of the same record and decides whether the field is shown, required, or read only. Conditions work on built in modules and on custom modules you built.

Studio enforces conditions twice: the form applies them as a person types, and the server applies the same rule every time a record is created or edited. A condition is therefore a real rule, not only a screen effect.

#The three conditions

Click a field on the form in Studio to open Field properties. Under the usual settings (Required, Read only, Invisible, Help text, Placeholder, Default value, and Width) are three condition rows.

To set one:

1. Choose the field to read in the first list. It lists the other fields of the same record.
2. Choose a comparison.
3. Enter or choose a value, when the comparison needs one.

Until a condition is complete, Studio says Choose a value to finish this condition and does not hand half a rule to the page. To remove a condition, choose Always or No condition again.

#Comparisons

The comparisons depend on the type of the field being read.

For a field with fixed choices, the value is picked from the choices. is one of on a field without choices takes values separated by commas.

For example, a custom module for equipment could make Reason for return required only when Status is Returned, and make Serial number read only once Checked out is set.

#How each condition is enforced

#Show only when

Hiding is presentation only. A hidden field keeps its value and its access rules, so a value already saved is not erased and field level permissions still apply. A field also disappears when the field that controls it is itself hidden, so a chain of conditions collapses together.

#Required when

While the condition holds, saving the record without a value in the field is refused, and the field shows its name followed by is required. The server judges this on the values the record will have after the save, for every create and every edit. On an edit it checks what the edit touches: the field itself, or the field its condition reads. Setting a status that makes another field required, with that field still empty, is refused.

A field that the person cannot fill in is not demanded. That includes a field a condition hides, a field the person has no right to write, and, when the person is below the Manager role, a field a condition locks for them.

#Read only when

While the condition holds, the form shows the field locked. On save, the server refuses a change to a locked field made by anyone below the Manager role, with the message {field} is read only here, so it cannot be changed. A value sent back as it is stored is accepted, and so is an empty or default value on a new record. Studio refuses the change on that field rather than quietly dropping it.

Managers and Super Admins are not stopped by this server check. The plain Read only switch follows the same role line: for people below Manager, the server keeps the stored value, and Managers and Super Admins can still change the field.

If the server cannot tell whether a condition holds, because the value it needs was not loaded for this save or the person may not read it, it refuses with Studio could not check {field} against its rule. Reload the record and try again. Reload the record and save again.

#What a condition cannot do

Studio shows a setting as off, with the reason, instead of hiding it.

• A field that Agaro fills in, such as a formula, a running number, or a list of child records, is always read only. It shows Agaro fills this field in, so it is always read only. and takes no Required when or Read only when.
• A field that is always required shows This field is always required. and has no Required when.
• A field that cannot be hidden shows This field always shows. and has no Show only when. In a custom module, a required field always shows.
• A system field can be relabeled, moved, or hidden, but never changed in how it is filled in, so it takes no Required when or Read only when.
• A condition can read only a field people fill in. Studio refuses one that reads anything else with {field} is not a field people fill in here, so a condition cannot read it.
• A field that moves only by its stage buttons cannot be locked by a condition.
• On some built in modules whose records Agaro's own engine writes, for example Payslips, Payroll runs, Attendance, Loans, Budgets, and Documents, Studio adds your custom fields to the record. There a condition reads only those custom fields.

#Review and publish

Changing a condition changes the draft only. The page redraws at once, and nothing is published until you review the change and apply it. The review lists each condition in words, for example "Equipment: Reason for return is required when Status is Returned". Applying publishes a new version for everyone in the workspace, and Undo brings the previous one back. See Studio: change modules and build your own.

#Troubleshooting

#A condition does not appear on the form

Check that the controlling field is itself shown. A field is shown by a condition only while the field it reads is visible.

#A person can still edit a field I made read only

The server check applies below the Manager role. A Manager or Super Admin is not stopped by it.

#Save says a field is required but the person cannot see it

A hidden field is not demanded. Check whether the field is hidden by a condition, by the Invisible switch, or by an access rule, and whether the record's values match what the condition expects.