Conditional Logic - Joyfill Documentation

Conditional logic allows you to show or hide fields and pages based on the values of other fields. This enables dynamic forms that adapt based on user input, creating a more intuitive and streamlined user experience.

Overview

Conditional logic in JoyDoc uses a rule-based system where you define conditions that determine when fields or pages should be shown or hidden. The logic is evaluated in real-time as users interact with the form, automatically showing or hiding elements based on the current field values.

How Conditional Logic Works

Conditional logic consists of three main components:

Action - What should happen when conditions are met (show or hide)
Evaluation - How conditions should be combined (and or or)
Conditions - The actual rules to check (field values, comparisons, etc.)

Logic Structure

Basic Structure

{
  action: 'show' | 'hide',  // Action to take when conditions match
  eval: 'and' | 'or',       // How to combine conditions
  conditions: [             // Array of conditions to check
    {
      file: 'file_id',      // File ID containing the field
      page: 'page_id',      // Page ID containing the field
      field: 'field_id',    // Field ID to check
      condition: '=',       // Comparison operator
      value: 'some_value'   // Value to compare against
    }
  ]
}

Actions

The action property determines what happens when the conditions are met:

show - Show the field/page when conditions match (field/page starts hidden)
hide - Hide the field/page when conditions match (field/page starts visible)

Evaluation Types

The eval property determines how multiple conditions are combined:

and - All conditions must be true for the action to trigger
or - Any condition must be true for the action to trigger

Condition Operators

The condition property supports different comparison operators depending on the field type:

Text and Textarea Fields

*= - is filled - Field has any value
null= - is empty - Field is empty or null
= - is - Field value equals the specified value
!= - is not - Field value does not equal the specified value
?= - contains - Field value contains the specified substring (case-insensitive)

Number Fields

*= - is filled - Field has a numeric value
null= - is empty - Field is empty or null
= - is - Field value equals the specified number
!= - is not - Field value does not equal the specified number
> - is greater than - Field value is greater than the specified number
< - is less than - Field value is less than the specified number

*= - is filled - Field has at least one option selected
null= - is empty - Field has no options selected
= - is - Field value equals the specified option
!= - is not - Field value does not equal the specified option

Field-Level Conditional Logic

Fields can have conditional logic applied to show or hide themselves based on other field values.

Example: Show Field When Another Field Has Value

{
  _id: 'conditional_field',
  type: 'text',
  title: 'Additional Information',
  value: '',
  hidden: true,  // Start hidden
  logic: {
    action: 'show',
    eval: 'and',
    conditions: [
      {
        file: 'file1',
        page: 'page1',
        field: 'main_field',
        condition: '*=',  // is filled
        value: null        // Not needed for "is filled"
      }
    ]
  }
}

Example: Hide Field Based on Number Comparison

{
  _id: 'discount_field',
  type: 'number',
  title: 'Discount Amount',
  value: 0,
  logic: {
    action: 'hide',
    eval: 'and',
    conditions: [
      {
        file: 'file1',
        page: 'page1',
        field: 'total_amount',
        condition: '<',
        value: 100
      }
    ]
  }
}

Example: Multiple Conditions with AND

{
  _id: 'premium_field',
  type: 'text',
  title: 'Premium Feature',
  value: '',
  hidden: true,
  logic: {
    action: 'show',
    eval: 'and',  // All conditions must be true
    conditions: [
      {
        file: 'file1',
        page: 'page1',
        field: 'user_type',
        condition: '=',
        value: 'premium'
      },
      {
        file: 'file1',
        page: 'page1',
        field: 'account_status',
        condition: '=',
        value: 'active'
      }
    ]
  }
}

Example: Multiple Conditions with OR

{
  _id: 'notification_field',
  type: 'text',
  title: 'Notification',
  value: '',
  hidden: true,
  logic: {
    action: 'show',
    eval: 'or',  // Any condition can be true
    conditions: [
      {
        file: 'file1',
        page: 'page1',
        field: 'priority',
        condition: '=',
        value: 'high'
      },
      {
        file: 'file1',
        page: 'page1',
        field: 'status',
        condition: '=',
        value: 'urgent'
      }
    ]
  }
}

Example: Text Contains Condition

{
  _id: 'follow_up_field',
  type: 'textarea',
  title: 'Follow-up Details',
  value: '',
  hidden: true,
  logic: {
    action: 'show',
    eval: 'and',
    conditions: [
      {
        file: 'file1',
        page: 'page1',
        field: 'main_description',
        condition: '?=',  // contains
        value: 'issue'     // Case-insensitive substring match
      }
    ]
  }
}

Page-Level Conditional Logic

Pages can also have conditional logic applied to show or hide entire pages based on field values.

Example: Show Page When Condition Met

{
  _id: 'conditional_page',
  name: 'Additional Details',
  hidden: true,  // Start hidden
  logic: {
    action: 'show',
    eval: 'and',
    conditions: [
      {
        file: 'file1',
        page: 'page1',  // Reference to the page with the condition field
        field: 'show_details',
        condition: '=',
        value: 'yes'
      }
    ]
  },
  fieldPositions: [
    // ... field positions
  ]
}

Example: Hide Page Based on Number Range

{
  _id: 'summary_page',
  name: 'Summary',
  logic: {
    action: 'hide',
    eval: 'and',
    conditions: [
      {
        file: 'file1',
        page: 'page1',
        field: 'total_score',
        condition: '<',
        value: 50
      }
    ]
  },
  fieldPositions: [
    // ... field positions
  ]
}

Supported Field Types

Conditional logic can reference the following field types in conditions:

Text (text) - Supports all text operators
Textarea (textarea) - Supports all text operators
Number (number) - Supports all number operators
Dropdown (dropdown) - Supports dropdown operators
MultiSelect (multiSelect) - Supports dropdown operators

Note: Fields used in conditions must be on a different page than the field/page being controlled (you cannot reference a field from the same page).

Complete Example

{
  fields: [
    {
      _id: 'customer_type',
      type: 'dropdown',
      title: 'Customer Type',
      value: '',
      options: [
        { _id: 'opt1', value: 'individual' },
        { _id: 'opt2', value: 'business' }
      ]
    },
    {
      _id: 'business_name',
      type: 'text',
      title: 'Business Name',
      value: '',
      hidden: true,  // Hidden by default
      logic: {
        action: 'show',
        eval: 'and',
        conditions: [
          {
            file: 'file1',
            page: 'page1',
            field: 'customer_type',
            condition: '=',
            value: 'business'
          }
        ]
      }
    },
    {
      _id: 'individual_ssn',
      type: 'text',
      title: 'Social Security Number',
      value: '',
      hidden: true,  // Hidden by default
      logic: {
        action: 'show',
        eval: 'and',
        conditions: [
          {
            file: 'file1',
            page: 'page1',
            field: 'customer_type',
            condition: '=',
            value: 'individual'
          }
        ]
      }
    },
    {
      _id: 'total_amount',
      type: 'number',
      title: 'Total Amount',
      value: 0
    },
    {
      _id: 'discount_field',
      type: 'number',
      title: 'Discount',
      value: 0,
      logic: {
        action: 'hide',
        eval: 'and',
        conditions: [
          {
            file: 'file1',
            page: 'page1',
            field: 'total_amount',
            condition: '<',
            value: 1000
          }
        ]
      }
    }
  ],
  files: [
    {
      _id: 'file1',
      pages: [
        {
          _id: 'page1',
          name: 'Customer Information',
          fieldPositions: [
            // ... field positions
          ]
        },
        {
          _id: 'page2',
          name: 'Additional Details',
          hidden: true,
          logic: {
            action: 'show',
            eval: 'and',
            conditions: [
              {
                file: 'file1',
                page: 'page1',
                field: 'total_amount',
                condition: '>',
                value: 5000
              }
            ]
          },
          fieldPositions: [
            // ... field positions
          ]
        }
      ]
    }
  ]
}

Best Practices

Start with Hidden State - When using show action, set hidden: true initially so the field/page starts hidden
Use Specific Field IDs - Always reference fields by their _id property
Cross-Page References - Conditions must reference fields from different pages
Test Edge Cases - Test with empty values, null values, and boundary conditions
Keep Conditions Simple - Complex logic with many conditions can be harder to maintain
Use AND for Required Conditions - Use and when all conditions must be met
Use OR for Optional Conditions - Use or when any condition can trigger the action

Common Patterns

// Show field when dropdown equals specific value
logic: {
  action: 'show',
  eval: 'and',
  conditions: [
    {
      file: 'file1',
      page: 'page1',
      field: 'dropdown_field',
      condition: '=',
      value: 'selected_option'
    }
  ]
}

Pattern 2: Show/Hide Based on Text Contains

// Show field when text contains specific substring
logic: {
  action: 'show',
  eval: 'and',
  conditions: [
    {
      file: 'file1',
      page: 'page1',
      field: 'text_field',
      condition: '?=',
      value: 'keyword'
    }
  ]
}

Pattern 3: Show/Hide Based on Number Range

// Show field when number is greater than threshold
logic: {
  action: 'show',
  eval: 'and',
  conditions: [
    {
      file: 'file1',
      page: 'page1',
      field: 'number_field',
      condition: '>',
      value: 100
    }
  ]
}

Pattern 4: Multiple Required Conditions

// Show field when multiple conditions are all true
logic: {
  action: 'show',
  eval: 'and',
  conditions: [
    {
      file: 'file1',
      page: 'page1',
      field: 'field1',
      condition: '=',
      value: 'value1'
    },
    {
      file: 'file1',
      page: 'page1',
      field: 'field2',
      condition: '>',
      value: 50
    }
  ]
}

Pattern 5: Any Condition Can Trigger

// Show field when any condition is true
logic: {
  action: 'show',
  eval: 'or',
  conditions: [
    {
      file: 'file1',
      page: 'page1',
      field: 'status',
      condition: '=',
      value: 'pending'
    },
    {
      file: 'file1',
      page: 'page1',
      field: 'priority',
      condition: '=',
      value: 'high'
    }
  ]
}

Troubleshooting

Field Not Showing/Hiding

Check hidden property - Ensure hidden: true when using show action
Verify field references - Ensure field IDs in conditions match actual field IDs
Check page references - Ensure page IDs are correct
Verify condition syntax - Check that condition operators match field types
Test condition values - Ensure comparison values match actual field values

Condition Not Working

Field type compatibility - Verify the condition operator is supported for the field type
Value matching - For dropdown/multiSelect, ensure the value matches exactly
Empty vs null - Check if field is empty (null=) or filled (*=)
Case sensitivity - Text contains (?=) is case-insensitive, but equals (=) is case-sensitive

Bonus Tip:

Checkout the github repo here - https://github.com/joyfill/conditional-logic

​Overview

​How Conditional Logic Works

​Logic Structure

​Basic Structure

​Actions

​Evaluation Types

​Condition Operators

​Text and Textarea Fields

​Number Fields

​Dropdown and MultiSelect Fields

​Field-Level Conditional Logic

​Example: Show Field When Another Field Has Value

​Example: Hide Field Based on Number Comparison

​Example: Multiple Conditions with AND

​Example: Multiple Conditions with OR

​Example: Text Contains Condition

​Page-Level Conditional Logic

​Example: Show Page When Condition Met

​Example: Hide Page Based on Number Range

​Supported Field Types

​Complete Example

​Best Practices

​Common Patterns

​Pattern 1: Show/Hide Based on Dropdown Selection

​Pattern 2: Show/Hide Based on Text Contains

​Pattern 3: Show/Hide Based on Number Range

​Pattern 4: Multiple Required Conditions

​Pattern 5: Any Condition Can Trigger

​Troubleshooting

​Field Not Showing/Hiding

​Condition Not Working

​Bonus Tip: