Smart Fields

Overview

Smart Fields allow you to customize Data Definitions to dynamically reveal and hide fields or groups of fields depending on previously entered values. This is useful for long forms where some fields are only needed if a particular field value is specified elsewhere. One common example of this involves a set of fields for contact information that should only be visible if the user has elected to include contact information on the page.

Fields or groups of fields can be hidden/shown based on the values of fields with pre-selected values -- checkboxes, dropdowns, radio buttons, and multi-selects.

Configuring Smart Fields

Smart Fields are configured by editing a specific field value for a checkbox, radio button, dropdown or multi-select field and selecting which fields or groups of fields should be exposed when that value is selected. For a particular field or group of fields, if any rules exist to show the field when another field's value is selected, then the field or group of fields will be hidden when viewing the form unless that value is specified.

To configure Smart Fields in the graphical Data Definition builder:

  1. Edit a checkbox, radio button, dropdown or multi-select field.
  2. In the Item area for the field value that should reveal another field or group of fields, use the Select a field... picker under Show Fields to select one or more fields to reveal.

To configure Smart Fields in the XML view:

  1. Add a show-fields attribute to the <item> containing the value that should reveal the other fields or groups or fields.
  2. Enter a comma-separated list of field identifiers. For fields inside of groups, use a slash / to indicate the group nesting, e.g. group1/inside-field.

When editing a Data Definition with the graphical builder, all fields are always visible. There is text below fields affected by Smart Field rules explaining when these fields will appear.

When viewing a Data Definition itself, all fields are initially visible. Use the Apply Smart Field rules to toggle previewing the form with and without the rules applied.

Examples

A use-case that demonstrates a few different features of Smart Fields is a form with fields for an address including a "Country" dropdown and associated zip-code field.

When the Country "United States" is selected, a "5 digit zip code" field could be revealed whereas when "Canada" is selected, a "6 character postal code" field could be shown. If the "Country" field has no value selected, both "5 digit zip code" and "6 character postal code" fields could be hidden.


            <system-data-structure>
  ... other fields ...
  <text identifier="Country" type="dropdown">
    <dropdown-item show-fields="5-digit-zip" value="US"/>
    <dropdown-item show-fields="6-char-postal" value="Canada"/>
    ... other countries ...
  </text>
  <text identifier="5-digit-zip" label="US Zip Code (5 digit)"/>
  <text identifier="6-chart-postal" label="Canadian Postal Code (6 characters)"/>
</system-data-structure>
            

These rules can stack up as well. In the example above, we could have an "Include Address?" checkbox with the "Country" show-field selected. This would automatically cause the "Country" field, "5 digit zip code", and "6 character postal code" fields to be hidden by default when the "Show Address?" checkbox is unchecked, even if the "Country" field has a default value selected. This is because for the Smart Field rules, hidden fields count as if they had no value selected.


            <system-data-structure>  
  ... other fields ...  
  <text identifier="include-address" label="Include Address?" type="checkbox">  
    <checkbox-item show-fields="Country,..other address fields..." value="yes"/>  
    <checkbox-item value="no"/>  
  </text>  
  ... other address fields ...  
  <text identifier="Country" type="dropdown">  
    <dropdown-item show-fields="5-digit-zip" value="US"/>  
    <dropdown-item show-fields="6-char-postal" value="Canada"/>  
    ... other countries ...  
  </text>  
  <text identifier="5-digit-zip" label="US Zip Code (5 digit)"/>  
  <text identifier="6-char-postal" label="Canadian Postal Code (6 characters)"/>  
</system-data-structure>  
            

Groups of fields can also be progressively disclosed, which would result in the group being hidden by default unless a specific value is selected. In the example above, the "Country", "5 digit zip code", and "6 character postal code" fields could be inside of "Address" group. Then, the "Include Address?" checkbox could have the "Address" group selected as a show-field.


            <system-data-structure>  
  ... other fields ...  
  <text identifier="include-address" label="Include Address?" type="checkbox">  
    <checkbox-item show-fields="Address" value="yes"/>  
    <checkbox-item value="no"/>  
  </text>  
  <group identifier="Address">  
    ... other address fields ...  
    <text identifier="Country" type="dropdown">  
      <dropdown-item show-fields="5-digit-zip" value="US"/>  
      <dropdown-item show-fields="6-char-postal" value="Canada"/>  
      ... other countries ...  
    </text>  
    <text identifier="5-digit-zip" label="US Zip Code (5 digit)"/>  
    <text identifier="6-char-postal" label="Canadian Postal Code (6 characters)"/>  
  </group>  
</system-data-structure>  
            

In-context Editing with Smart Fields

When editing a page in-context, only the selected in-context fields for a given region are included in show-field rules. Using the example above, if only the "Address" group is configured to appear for an in-context editing region and the "Show Address?" checkbox is not, the "Address" group will be always visible - i.e. the rule coming from the "Show Address?" checkbox will be ignored because the field is not selected for this region for in-context editing purposes.

Field Validation with Smart Fields

Fields that are marked as required or whose content is validated with regular expressions but are hidden due to Smart Field rules are not validated on submit. This allows you to create conditionally required and conditionally validated fields in Data Definitions.

Smart Fields and Rendered Structured Data

Smart Field rules do not affect the rendered structured data content that appears on pages or in index blocks. This is important when writing formats because you can assume all fields will always be visible.

As a format writer, you may also need to check the values of fields you're using to reveal other fields. For example, a field such as the "Country" dropdown mentioned above may have a value set but may not be shown due to the fact that "Include address?" is not checked. Before outputting the "Country" field in your format, you need to check the value of "Include Address?" instead of just checking for the presence of a value for the "Country" field.