Cascading Options Field Type

Description:
The cascading_options field type allows you to create a dynamic selection list where the available options depend on the selection made in a parent field. This is useful for creating dependent dropdowns, such as selecting a state based on a chosen country or a subcategory based on a selected category. —

YAML Definition

- name: sub_category
  type: string
  display_name: "Sub Category"
  cascading_parent_field: "category"
  cascading_options:
    - parent_field_option: "Electronics"
      options:
        - "Mobile Phones"
        - "Laptops"
        - "Cameras"
    - parent_field_option: "Home Appliances"
      options:
        - "Refrigerators"
        - "Microwaves"
        - "Washing Machines"

---

Attributes

• name (string): Required.
  The unique identifier for the field.

• type (string): Required.
  Should be set to string for cascading options fields.

• display_name (string): Optional.
  The label displayed in the user interface. If not provided, a formatted version of name is used.

• cascading_parent_field (string): Required.
  The name of the parent field that this field depends on. The parent field must be defined in the same schema.

• cascading_options (array): Required.
  An array of objects that map each parent field option to a set of child options.

• required (boolean): Optional.
  If true, the field must have a value.

• readonly (boolean): Optional.
  If true, the field is read-only and cannot be modified by the user.

• hidden (boolean): Optional.
  If true, the field is hidden from the user interface.

• default_value (string): Optional.
  The default value for the field when no selection has been made.

---

Example

Suppose you have a category field and want the sub_category field to display options based on the selected category.

- name: category
  type: string
  display_name: "Category"
  options:
    - "Electronics"
    - "Home Appliances"
    - "Furniture"

- name: sub_category
  type: string
  display_name: "Sub Category"
  cascading_parent_field: "category"
  cascading_options:
    - parent_field_option: "Electronics"
      options:
        - "Mobile Phones"
        - "Laptops"
        - "Cameras"
    - parent_field_option: "Home Appliances"
      options:
        - "Refrigerators"
        - "Microwaves"
        - "Washing Machines"
    - parent_field_option: "Furniture"
      options:
        - "Sofas"
        - "Beds"
        - "Tables"

In this example:

• When the user selects Electronics in the category field, the sub_category field will display Mobile Phones, Laptops, and Cameras as options.
• If Home Appliances is selected, the options will be Refrigerators, Microwaves, and Washing Machines.
• Selecting Furniture will show Sofas, Beds, and Tables in the sub_category field.

---

Usage Notes

• Parent Field Requirement: The cascading_parent_field must reference a field that exists in the same schema and is of a compatible type (typically string with predefined options).

• Defining Cascading Options:
  • The cascading_options attribute is an array where each element maps a parent_field_option to a set of options.
  • Ensure that each parent_field_option matches exactly one of the options defined in the parent field.
• Default Behavior:
  • If the parent field’s value changes, the sub_category field’s options update automatically to reflect the corresponding options in cascading_options.
  • If the parent field’s value does not match any parent_field_option, the sub_category field will have no options available.
• Validation:
  • When the sub_category field is marked as required, ensure that the user selects a value after choosing an option in the parent field.
  • If the parent field is cleared or changed, consider resetting the sub_category field to prompt the user for a new selection.
• User Interface:
  • The cascading field typically appears as a dropdown or select list.
  • Provide clear labels and guidance to help users understand the dependency between fields.
• Use Cases:
  • Geographical Selection: Selecting a state or province based on the chosen country.
  • Product Categorization: Filtering subcategories or product types based on the selected main category.
  • Service Selection: Offering service options that are specific to a selected department or area.
• Performance Considerations:
  • For a large number of options, consider fetching options dynamically to improve performance.
  • Ensure that the cascading_options array is kept up-to-date with any changes to the parent field’s options.

---

By utilizing the cascading_options field type, you can create intuitive and dynamic forms that respond to user selections, improving data accuracy and user experience within your application.