Conditional Custom Fields

Custom fields can show or hide themselves based on the values of other fields, the current user’s context, or any evaluable condition. This lets you build smart forms that ask only the relevant questions.

The Rendered Rule

Every custom field has a Rendered Rule — an EL expression that controls whether the field is shown. When the expression evaluates to "true" (or is blank), the field is visible. When it evaluates to "false", the field is hidden.

The Rendered Rule is re-evaluated every time the form re-renders. It runs server-side, so it has access to all DonorPoint context variables.

Syntax

The Rendered Rule is a JSF EL expression without the #{...} wrapper:

contact.get('EmploymentStatus') != null and contact.get('EmploymentStatus').value eq 'EMPLOYED'

This shows the field only when the EmploymentStatus custom field is set to EMPLOYED.

Common Patterns

Show based on another field’s value:

contact.get('GivingLevel') != null and contact.get('GivingLevel').value eq 'MAJOR'

Show only to logged-in users:

user != null and user.id != null

Show only to staff (not donors on a public form):

user != null and user.account != null and user.account.admin

Show when a checkbox is checked:

contact.get('IsVolunteer') != null and contact.get('IsVolunteer').checked

Show when a field is empty (prompt to fill in):

contact.get('Department') == null or contact.get('Department').value == ''

Always show (blank rule = always visible): (Leave the Rendered Rule empty)

Never show (use for integration codes): (Set Hidden = true instead of using a Rendered Rule)

ReRender Panel

The ReRender Panel checkbox on a custom field controls whether changing this field’s value triggers a re-evaluation of all fields’ Rendered Rules across the form.

  • When checked: changing this field sends an AJAX request to the server, which re-evaluates every field’s Rendered Rule and updates the form in place. Fields appear and disappear instantly in response to changes.
  • When unchecked: the field’s value is sent to the server on change (for Action scripts) but the form layout does not refresh.

Rule of thumb: Check ReRender Panel on any field whose value determines whether other fields are visible. The Dropdown, Radio Button, and Checkbox types are the most common candidates.

The Action Script

The Action property on a custom field is an EL script that runs on the server when the field’s value changes. Use it to:

  • Set the value of another field based on this field’s value
  • Perform a server-side calculation
  • Trigger a lookup in the database
#{elProcessor.set('calculatedAmount', contact.get('AnnualSalary').value * 0.01)}

The OnComplete JavaScript

OnComplete is JavaScript that runs in the browser after the AJAX call triggered by a field change completes. Use it for client-side UI effects:

// Scroll to a newly visible section:
document.getElementById('additionalFields').scrollIntoView({behavior: 'smooth'});

// Update a display element:
document.getElementById('salaryDisplay').textContent = '$' + this.value;

Required Fields — Dynamic and Static

The Required checkbox makes a field unconditionally required for all transactions. For conditional requirements (required only under certain conditions), use the Required Rule — an account property that follows the naming convention:

{EntityName}{ENTITYNAME}{fieldName}_required

For example, to make the DepartmentCode field required only for employees of a specific organization, set on your Account:

ContactCONTACTDepartmentCode_required=#{contact.getEmployer() != null and contact.getEmployer().get('RequiresDept').checked}

When this evaluates to "true", the field becomes required on the form.

Cascading Fields Example

A complete example: show a “Manager Name” field only when the “Is Manager” checkbox is checked, and show a “Department” dropdown only for employed contacts.

Field 1: Is Employed (Checkbox, ReRender Panel = checked)

  • Rendered Rule: (empty — always show)

Field 2: Department (Dropdown)

  • Rendered Rule: contact.get('IsEmployed') != null and contact.get('IsEmployed').checked

Field 3: Is Manager (Checkbox, ReRender Panel = checked)

  • Rendered Rule: contact.get('IsEmployed') != null and contact.get('IsEmployed').checked

Field 4: Manager Name (Text Field)

  • Rendered Rule: contact.get('IsManager') != null and contact.get('IsManager').checked

When a donor checks “Is Employed,” the Department and Is Manager fields appear. If they then check “Is Manager,” the Manager Name field appears. Unchecking “Is Employed” hides all three dependent fields.

Tips

  • Always test Rendered Rules with the Test Script feature on the custom field edit page before deploying to a live form.
  • Rendered Rules run on every form re-render — keep them lightweight. Avoid database queries in Rendered Rules; use the Action script or Event Handlers for data lookups.
  • Hidden fields (integration codes) do not need Rendered Rules — set Hidden = true instead.