1 Introduction

Introduction

Skip logic in OpenSpecimen allows fields in custom forms to be dynamically shown or hidden based on the value of another field. This functionality ensures that forms adapt to user input, improving usability and reducing the likelihood of errors. Skip logic is defined using XML and retains its configuration even when the form is edited and saved via the UI.

You need to know how to edit XMLs to define skip logic.
Skip logic can be configured only via XML import. We will enhance the UI to support this in future.
Skip logic is retained even if the form is edited and saved via UI (enhanced in v6.2).

What are the different types of skip logic supported?

Fields can be shown or hidden based on the value of dropdowns or radio buttons.
Skip logic can be applied based on specific text or numerical values.
Conditions can include ranges for numbers, dates, or text values.
Show/Hide Using Logical and Relational Operators:
- Logical operators: and, or
- Relational operators: <, >, =, <=, >=, !=
- Complex expressions involving these operators can control field visibility.

What is not supported currently?

Conditions based on regex.
Enabling or disabling fields (only show/hide is supported).
Skip logic cannot be applied to fields within sub-forms.

Best practices to create skip logic in a form

Create the form with all required fields via the UI.
Export the XML of the form using the Export button.
Edit the XML to define skip logic using the showWhen tag.
Re-import the edited XML. Ensure the form name in the XML is unchanged to avoid creating a duplicate form.
Once imported, the skip logic is saved and remains functional even after subsequent updates via the UI.

Example form definition XML with skip logic: GeneticHistory.xml, Smoking History

Check the syntax of the "showWhen" tag in the above XML.

Sample form:

Form field	Control	Values	Control logic

Form field	Control	Values	Control logic
Proband	Radio Button	Yes, No	-
Relation with Proband	Drop down	Father, Mother, Son, Daughter, Others	The field should appear if option ‘No’ is selected for ‘Proband’ field
Other Relation	String Text Box	-	The field should appear if option ‘Others’ is selected for ‘Relation with Proband’ field

Try out the above sample form on the demo site: 'Genetic History'

On selecting 'Yes', the form field 'Relation with Proband' will not appear

On selecting 'No' option, form field 'Relation with Proband' will appear

Example of skip logic with condition involving logical operator:

Condition: Display 'FOBT Results' field when the value for 'FOBT Results' is either one of 'Positive' or 'Negative'

Syntax:

Example of skip logic to hide/show a subform

Condition: Display the subform "Family History Details" when the value of the field "Family Cancer History" is "Yes"

Syntax (to be added just above the subform control name): <showWhen><![CDATA[familyCancerHistory = "Yes" ]]></showWhen>

When 'Family Cancer History' value is 'No', subform does not appear.

When 'Family Cancer History' value is 'Yes', a subform 'Family History Details' is visible.

Example 3: Use Single checkbox in </showWhen>, since its boolean value, you need to mentioned 0/1 in the condition as below

Example 4: Show or hide form fields based on container type. When a form is attached at the container level, some fields may need to appear only for boxes, while others should display for freezers, racks, or shelves. This can be controlled using the code below.

Check code within <showWhen>

<textArea>
<name>demo_freezer_comments</name>
<udn>demo_freezer_comments</udn>
...
<showWhen><![CDATA[container.typeName == 'Demo Freezer']]></showWhen>
...

<textArea>
<name>fluid_freezer_comments</name>
<udn>fluid_freezer_comments</udn>
....
<showWhen><![CDATA[container.typeName == '-80 Fluid Freezer']]></showWhen>
.....
</textArea>

Fields supported from Container Module:

Field Name	Example Code

Field Name	Example Code
Container Name/Unique Name	`<showWhen><![CDATA[container.name == 'TIA_R37_S4_B2']]></showWhen>`
Site	`<showWhen><![CDATA[container.siteName == 'new hbw site']]></showWhen>`
Barcode	`<showWhen><![CDATA[container.typeName == 'Demo Freezer']]></showWhen>`
Display Name	`<showWhen><![CDATA[container.displayName == 'NS_HBW Freezer 2']]></showWhen>`
Container Type	`<showWhen><![CDATA[container.typeName == 'Demo Freezer']]></showWhen>`
Top-level container (No parent) `!container.storageLocation` checks whether the container has a parent. If it’s true (means no parent), the field will show only for top-level containers.	`<showWhen><![CDATA[!container.storageLocation]]></showWhen>`
Child containers (with parent) Similarly, `!!container.storageLocation` shows it only when it does have a parent, i.e., for child-level containers.	`<showWhen><![CDATA[!!container.storageLocation]]></showWhen>`
Show the field only if the container is a child of a specific parent.	Example: Parent: TIA_R37 (TIA - Freezer, R37 Rack) Children follow the same naming: TIA_R37_B1, TIA_R37_B2, etc. So the field stays hidden for TIA_R37, and visible for all child containers under TIA_R37, `<showWhen><![CDATA[container.name.startsWith('TIA_R37') && container.name != 'TIA_R37']]></showWhen>`

How to set control (skip) logic in custom forms?

Introduction

What are the different types of skip logic supported?

What is not supported currently?

Best practices to create skip logic in a form

Example form definition XML with skip logic: GeneticHistory.xml, Smoking History