Visibility Advanced Tool

Introduction

The Visibility Advanced Tool provides a centralized mechanism for controlling the visibility of form elements based on field values. It enhances legacy section-level visibility by introducing named visibility rules, field-level visibility, and support for container elements like Columns and ColumnContainer. This tool ensures consistent evaluation on both server-side (initial render, validation) and client-side (dynamic interactions).

How does it work?

To configure and use the Visibility Advanced Tool, follow these steps:

1. Open your existing form or create a new form containing sections, columns, or elements.
2. Click the eye icon in the Advanced Tools section at the top of the Form Builder.
   s
3. Click Add Rule in the left panel to create a new rule.
   
4. Click the edit icon to name the rule.
5. Click on +Add Condition to add a condition or +Add Group in the condition editor to group multiple conditions together.
   
6. In the condition editor, define the logical criteria that determine when the element should be visible.
7. Once conditions are set, find the target element in the right-hand panel to apply the rules
   1. Select a rule in the left panel.
   2. Locate the section or element in the right panel table.
   3. Click Apply to apply the selected rule. If a section is selected, all child element Apply buttons are disabled and the existing rules applied to them are unapplied.
   4. The Button changes to Apply (highlighted in blue).
      
   5. Click the Apply button again to unapply.
8. After applying rules, click Save in the Form Builder.
9. To delete a condition or a rule, click their respective Delete buttons.

Named Visibility Rules

Named rules are stored in the Form's properties:

{
  "visibility_rules": [
    {
      "visibility_key": "rule_abc123",
      "visibility_name": "Show for Premium Users",
      "visibilityControl": "user_type",
      "visibilityValue": "premium",
      "regex": "",
      "join": "",
      "reverse": ""
    }
  ]
}

Rule Combination Logic

• Multiple named rules on the same element: Combined with OR logic - element is visible if ANY rule evaluates to true.
• Section with legacy + named rules: Combined with OR logic - legacy conditions are wrapped in parentheses, then ORed with named rules.

Example:

Legacy: status = "active" AND category = "premium"
Named Rule: user_type = "admin"

Combined: (status = "active" AND category = "premium") OR user_type = "admin"

Backward Compatibility and Migration

Runtime Compatibility

Forms imported from older versions with legacy Section visibility rules continue to work without modification. The server-side VisibilityControlUtil.parseVisibilityRules() method handles both legacy properties and named rules:

1. Legacy properties (visibilityControl, visibilityValue, etc.) on Sections are parsed first.
2. Named rules from the Form's visibility_rules array are parsed and combined.
3. If both exist, they are combined with OR logic.

This ensures that imported apps function correctly at runtime without requiring any manual migration. Starting in Joget DX 9.1.1 or newer, legacy apps will now display a banner stating "This form has 2 visibility rule(s) from a previous version. They will be converted to named rules when you make a change here or click Migrate now" with a Migrate now button on the right of the banner in Form Builder.

Design-Time Migration

When a Form with legacy Section visibility rules is opened in Form Builder and the Visibility Tool is accessed, the migrateLegacyRules() function automatically migrates legacy rules to named rules:

Migration Process:

1. Scans all Section elements for legacy visibilityControl properties
2. For each Section with legacy visibility:

• • Creates a new named rule in the Form's visibility_rules array
  • Generates a unique visibility_key (GUID)
  • Sets visibility_name based on the first control field (e.g., "status +2 more")
  • Copies all legacy properties (visibilityControl, visibilityValue, regex, join, reverse)
  • Applies the new rule to the Section via visibility_rules mapping
  • Clears the legacy properties from the Section
  • Marks the Section with _visibility_migrated: true flag to prevent re-migration

Before Migration (DX 8 Section):

{
  "className": "org.joget.apps.form.model.Section",
  "properties": {
    "id": "section1",
    "visibilityControl": "status",
    "visibilityValue": "active",
    "regex": "",
    "join": "",
    "reverse": ""
  }
}

After Migration (DX 9 Section):

{
  "className": "org.joget.apps.form.model.Section",
  "properties": {
    "id": "section1",
    "_visibility_migrated": true,
    "visibility_rules": {
      "a1b2c3d4-e5f6-7890-abcd-ef1234567890": true
    }
  }
}

Form's visibility_rules array:

{
  "visibility_rules": [
    {
      "visibility_key": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "visibility_name": "status",
      "visibilityControl": "status",
      "visibilityValue": "active",
      "regex": "",
      "join": "",
      "reverse": ""
    }
  ]
}

Migration Trigger

Migration occurs automatically when:

• A Form is opened in Form Builder
• The Visibility Tool is rendered (user clicks on Advanced Tools > Visibility)
• The migrateLegacyRules() function is called during tool initialization

Understanding Rule Conditions & Condition Editor

The condition editor allows for complex logical branching to control visibility.Interface Reference

Available Operators

Grouping Conditions

Use + Add Group to create parenthesized condition groups for complex logic:

(status = "active" AND category = "premium") OR user_type = "admin"

Single Condition

Show field when status is "active":

• Control Field: status
• Value: active
• Operation: (empty - exact match)

Multiple Conditions (AND)

Show when status is "active" AND user_type is "premium":

status = "active" [AND]
user_type = "premium"

Multiple Conditions (OR)

Show when status is "active" OR user_type is "admin":

status = "active" [OR]
user_type = "admin"

Negation

Show when status is NOT "inactive":

• Click the ! (NOT) icon to toggle negation
• Condition becomes: NOT (status = "inactive")

Parent Container Behavior

If a parent container (Section, Columns, ColumnContainer) has a rule applied

• Legacy: status = "active" AND category = "premium"
• Named Rule: user_type = "admin"
• Combined: (status = "active" AND category = "premium") OR user_type = "admin"

Workflow

Visibility evaluation occurs during both server-side initial rendering and client-side dynamic interactions. The VisibilityControlUtil handles the parsing and evaluation of these rules, ensuring that field visibility logic remains consistent throughout the workflow process.

Expected Outcome

After implementation, form elements will dynamically show or hide based on the user's input in the control fields. The interface provides visual feedback in the Visibility Tool: applied rules are highlighted, and condition counts are displayed under rule names.

Common Issues & Troubleshooting