Form items arrangement and organization

[xamelon]

Description

Form is a list of questions, grouped together around specific problem.
Form has it's own UI and should be filled out by some person (patient, practitioner, etc...)
By default questions are placed linearly, but it's usefull to arrange them more precicely.
Form has it's representation as JSON - which we call DSL.
It defines questions and their visual details (arrangement, size).

FHIR Questionnaire definitions example:

This example defines 2 questions and 1 display item in a group "Blood Pressure".
There is no information about their visual representation - just grouping and questions order.

{:title "Vitals Form"
 :items [{:id "blood-pressure"
          :type "group"
          :items [{:type "display" :text "Enter blood pressure observations"}
                  {:id "systolic" :text "Blood Pressure - Systolic"}
                  {:id "diastolic" :text "Blood Pressure - Diastolic"}]}]}

In Aidbox Forms we have 2 separate DSLs for Questions and Layout definitions, they complement each other:

Questions definition describes questions.

{:title "Vitals Form"
 :keys {:blood-pressure {:type "group"
                         :keys {:systolic  {:text "Blood Pressure - Systolic"}
                                :diastolic {:text "Blood Pressure - Diastolic"}}}}}

Layout definition describes questions arrangement(row, column) and has additional UI items (label)

{:layout {:type "row"
          :children [{:type "label" :label "Enter blood pressure observations"}
                     {:bind [:blood-pressure :systolic]}
                     {:bind [:blood-pressure :diastolic]}]}}

Separate Layout definition gives ability to define and use several layouts for the same form interchangeably.

But separate definitions goes with a cost - you should type twice one question - in a Questions and in a Layout.
Also it's more error prone to change a form - you can forget to update other definition.

Both options has it's pros and cons and we want to get best of that options.
Our intention - to simplify form definition and minimize required effort.
For that purpose we want to try use only single DSL instead of 2 separated.

Problem

How to simplify form definition and minimize effort required to define a form with custom layout.

Questions

• what gives a minimal effort to define a custom layout.
• what will be flexible enough to define a form with special row/columnar structure
• how easily layout can be changed without errors

Options

We found these options:

• Fixed grid layout (row == 12 columns). Layout details described in questions itself.
• Flex container widgets that place questions in a particular way.

Widget - some item/entity/object that can be displayed in the UI.
Container - widget that holds another widgets and change their behavior in some way

Aspects

• how much effort need to create custom layout (grid 2x2)
• how error-prone to change layout
• How easily it will be to convert Form to Questionnaire
• Do you need visual form to understand DSL layout?

Approach

Decision matrix

Call for action

You can read more about options in next comments.
Please give your feedback - what do you think
or just vote for the comment with emoji or "up" button.

[qdzo]

Fixed grid layout (row == 12 columns). Layout details described in questions itself.

In this option we assume that every form's row contains 12 cells.
Each input can be varied in size from 1 to 12,
and also can be positioned at any cell (1-12).

For example to place input in a center and take half of the width we define :column 4 and :size 6

  1   2   3   4   5   6   7   8   9  10   11  12
+---+---+---+---+---+---+---+---+---+---+---+---+
|   |   |   |xxxxxxxxxxxxxxxxxxxxxxx|   |   |   |
+---+---+---+---+---+---+---+---+---+---+---+---+

Both attributes are optional.
When widget size is bigger then remaining free row columns
then widget goes to the next line.

{:items [{:id "systolic"
          :text "Blood Pressure - Systolic"
          :size 8}
         {:id "diastolic"
          :text "Blood Pressure - Diastolic"
          :size 6}]}

This definition renders as

  1    2    3    4    5    6    7    8    9    10   11  12
+----+----+----+----+----+----+----+----+----+----+----+----+
|              systolic                 |    |    |    |    |
+----+----+----+----+----+----+----+----+----+----+----+----+
|        diastolic            |    |    |    |    |    |    |
+----+----+----+----+----+----+----+----+----+----+----+----+

Also group item should not have impact on layout - we consider it as just logic grouping.

how much effort need to create custom layout (grid 2x2)

    +------------------+------------------+
    |    systolic      |     diastolic    | 
    +------------------+------------------+
    |  body position   |    body site     |
    +------------------+------------------+

We need to set :size = 6 (half of a row) for all questions,

{:items [{:id "systolic"
          :text "Systolic blood pressure"
          :size 6}
          {:id "diastolic"
          :text "Diastolic blood pressure"
          :size 6}
         {:id "body-position"
          :text "Body Position"
          :size 6}
         {:id "body-site"
          :text "Body Site"
          :size 6}]}

how error-prone to change layout

Error prone due to size changes in previous widgets may affect
next widgets positioning.

How easily it will be to convert Form to Questionnaire

Straight-forward, no additional wrappers, question order is the same.

Do you need visual form to understand DSL layout?

It's better to use visual representation.

Since layout is based on widget size (and start column), it's more difficult to tell where is the widget located without visual representation - you shold calculate sizes and positions to know that.

[qdzo]

Flex container widgets that place questions in a particular way

In this option we add additional item types for layout - row and column

We can add more item types in the future

These items behave like containers - they contain other items and place them in a particular way.

For example row container places its children in a row and splits width between them.

[{:type "row"
  :items [{:id "systolic"
           :text "Systolic blood pressure"}
          {:id "diastolic"
           :text "Diastolic blood pressure"}]}

+-----------------------------+-----------------------------+
|         systolic            |        diastolic            | 
+-----------------------------+-----------------------------+

column container places its children in a column and every children placed in a new row.

[{:type "column"
  :items [{:id "systolic"
           :text "Systolic blood pressure"}
          {:id "diastolic"
           :text "Diastolic blood pressure"}]}

+-----------------------------+
|         systolic            |
+-----------------------------+
|         diastolic           |
+-----------------------------+

Also these containers can be composed together in a several ways.
For example 4 questions are placed in 2 columns that in their way is placed in a row.

[{:type "row"
  :items [{:type "column" 
           :items [{:id "systolic" :text "Systolic blood pressure"}
                   {:id "body-position" :text "Body Position"}]}
          {:type "column" 
           :items [{:id "diastolic" :text "Diastolic blood pressure"}
                   {:id "body-site" :text "Body Site"}
                  ]}]}

renders to this layout

+-----------------------------+-----------------------------+
|        systolic             |         systolic            |
+-----------------------------+-----------------------------+
|        body position        |         body site           |
+-----------------------------+-----------------------------+

how much effort need to create custom layout (grid 2x2)

    +------------------+------------------+
    |    systolic      |     diastolic    | 
    +------------------+------------------+
    |  body position   |    body site     |
    +------------------+------------------+

we need to wrap questions in 3 containers - 2 row containers and one column container

{:items {:type "column"
         :items [{:type "row"
                  :items [{:id "systolic"
                           :text "Systolic blood pressure"}
                          {:id "diastolic"
                           :text "Diastolic blood pressure"}]}
                 {:type "row"
                  :items [{:id "body-position"
                           :text "Body Position"}
                          {:id "body-site"
                           :text "Body Site"}]}]}}

How error-prone to change layout

Not at all. We can remove/add/change container and impact only child widgets.
Widget ordering is straightforward also

How easily it will be to convert Form to Questionnaire

Not so straightforward - we need to remove all containers,
and all widgets will be flattened in one list - that can be an issue.
Additionally we force forms-developer to manually wrap related questions in a group - to convey their meaning and relation.

Do you need visual form to understand DSL layout?

Likely it will be better to use it, but you can infer widgets position
by their structure.