Advanced JSON Form Specification - Chapter 4: Options Widgets

• Download Options Widgets Form - 818 B

Chapters

• Chapter 1: Introduction
• Chapter 2: Input Widgets
• Chapter 3: Input List Widgets
• Chapter 4: Options Widgets
• Chapter 5: Options List Widgets
• Chapter 6: Capture Widgets
• Chapter 7: Date and Time Widgets
• Chapter 8: Advanced Form Features

Introduction

This chapter presents screens that display a number of choices on a form screen from which a user can select one or more choices. The reader should download, unzip and copy the Option Widget form to the Android device and then use the CCA-Mobile app to fill out this example form.

Below is a code block that shows an example of a completed instance of the form in its raw JSON format.

/*
{
"Group Level": "A", 
"Level": "A1", 
"Fruit Fave": ["Guavas", "Oranges", "Mangoes"], 
"Ack": true
}
*/

Remember that a complete instance of a form can be viewed in its raw JSON format by backing up that instance to the device.

Single Choice Option Screen

As the name implies, the single choice option screen allows a user to select one and only one option from a set of options displayed. The image below shows an example of such a screen.

The definition for the screen above is shown in the code block below:

/*

{
"mainScreen":  {
"screenID": "Group Level", 
"screenDisplayArray": [
{
"localeCode": "en", 
"screenLabel": "1. What is your English language proficiency level group?
", 
"screenHint": "Please select only one.
"
}], 
"screenwidgetType": "singleChoice", 
"inputRequired": true, 
"widgetSchema": "
\"Group Level\": {
\"type\": \"string\"
}", 
"options": ["A", "B", "C"]
}
}
*/

The screenwidgetType is set to singleChoice. A singleChoice screen has a mandatory JSON array parameter called options. This array contains the texts of the choices made available to the user. The widgetSchema parameter holds the escaped schema for a JSON string called Group Level. Please be aware that the escaped schema string held in the widgetSchema of a singleChoice screen is not restricted to JSON strings alone. If the options parameter array contain only integer values then the widgetSchema should hold an escaped JSON integer schema. Correspondingly, if the options contain only number or Boolean values, then the escaped content of the widgetSchema should be a JSON number or JSON Boolean type, respectively.

Cascade Choice Option Screen

Cascade choice option screens are a special kind of singleChoice screen; “special” in the sense that a cascade option screen has the ability to display a different set of options to the user based on the selection on a previous form screen. To understand what is being said here, consider the screen depicted below:

The screen above offers two selection options to the user, i.e., A1 and A2. This is so because A was chosen in the singleChoice screen of the last section. If the option selected in the singleChoice screen had been B then B1 and B2 would have been displayed in the image above. Find out what would have been displayed on this screen if C was chosen in the previous singleChoice screen.

With a grasp of the concept of cascade choice option screens, explore the code block below to understand how these screen types are defined.

/*
{
"mainScreen":  {
"screenID": "Level", 
"screenDisplayArray": [
{
"localeCode": "en", 
"screenLabel": "2. What is your English language proficiency level?
", 
"screenHint": "Please select only one.
"
}], 
"screenwidgetType": "cascade", 
"inputRequired": true, 
"widgetSchema": "
\"Level\": {
\"anyOf\": [
{
\"type\": \"string\"
},
{
\"type\": \"number\"
},
{
\"type\": \"integer\"
},
{
\"type\": \"boolean\"
}
]
}", 
"cascadeOptions":  {
"screenID": "Group Level", 
"widgetName": "Group Level", 
"A": ["A1", "A2"], 
"B": ["B1", "B2"], 
"C": ["C1", "C2"]
}
}
}
*/

The screenwidgetType is set to cascade.

Just before a cascade option screen is displayed, the application responsible for displaying the screen does the following;

1. Extract the value of the screenID JSON string contained in the cascadeOptions. In this example, this value is Group Level.
2. Search the form for the screen whose identity matches the value extracted in step 1.
3. Extract the value of the widgetName JSON string contained in the cascadeOptions parameter. In this example, this value is Group Level.
4. Search the screen found in step 2 for the value of the input whose label matches the widgetName value extracted in step 3.
5. Match the input value found in step 4 to the names of the JSON arrays contained in the cascadeOptions parameter.
6. If an array match is found, display the contents of the matching array as the options on the cascade screen. For example, if the value of Group Level is C, then the items of the JSON array C, i.e., [C1, C2], are displayed on the cascade option screen.

The value of the widgetSchema parameter is a JSON escaped schema that says the input to a cascade screen can be a JSON boolean, integer, number or string type by way of the use of the anyOf JSON keyword. This flexibility is required, as the options displayed to the user on a cascade screen is dynamic and cannot be known ahead of time.

Multiple Choice Option Screen

The multiple choice screen example shown above is defined by the code block below:

/*

{
"mainScreen":  {
"screenID": "Fruit Fave", 
"screenDisplayArray": [
{
"localeCode": "en", 
"screenLabel": "3.  What are your favourite fruit?
", 
"screenHint": "Please select all that apply?
"
}], 
"screenwidgetType": "multipleChoice", 
"inputRequired": true, 
"widgetSchema": "
\"Fruit Fave\": {
\"type\": \"array\",
\"items\": 
{
\"type\": \"string\"
},
\"additionalItems\": false
}", 
"options": ["Guavas", "Oranges", "Apples", "Mangoes", "Peaches", "Plums"]
}
}

*/

The screenwidgetType is set to multipleChoice and the options parameter is a JSON array whose items are the select options offered to the user. The widgetSchema parameter contains the escaped JSON schema for an array that holds the selected or checked user values. In the example above, the items of this array are expected to be of JSON string type because the contents of the options parameter are strings. If the options parameter array held integer, number or boolean JSON types, then the items of the Fruit Fave array in the widgetSchema would be integer, number or Boolean, respectively.

Acknowledgement Screen

This is a form screen that prompts the user to confirm some information before proceeding with the rest of the form. Below are screenshots of an example of an acknowledgement screen:

The code block below shows the JSON definition of the screen depicted in the images above:

/*

{
"mainScreen":  {
"screenID": "Ack", 
"screenDisplayArray": [
{
"localeCode": "en", 
"screenLabel": "4. Do you confirm that the information entered into this form is correct?", 
"screenHint": "Click the button below to confirm."
}], 
"screenwidgetType": "acknowledge", 
"inputRequired": true, 
"widgetSchema": "
\"Ack\": {
\"type\": \"boolean\"
}"
}

*/

It can be seen from the definition above that the screenwidgetType is set to acknowledge and the widgetSchema parameter is simply the schema for a JSON boolean variable.

Next Chapter

In chapter 5, more advanced option screens called Option List Widgets are discussed.

Point of Interest

The interested reader should follow the form design sections of these walkthroughs and use this GUI tool to learn more about designing forms based on a number of use case scenarios.

History

• 18^th July, 2016: First version
• 3^rd November, 2016: Made corrections to this work