Advanced JSON Form Specification - Chapter 3: Input List Widgets

• Download Input_List_Widgets_Form - 879 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

Input List Widgets are screens that allow a user to enter two or more separate values into a single form screen. An example of a form demonstrating these screen types is attached to this article. Before proceeding any further, the reader should test this form by downloading, unzipping and copying this form to the Android device. Use the CCA-mobile app to fill out the form. Back up the completed form to see the JSON formatted form instance.

Below is a code block that shows a completed instance of the attached form.

/*
{
"OrgAbbrev":  {
"International Monetary Fund": "IMF", 
"United Nations": "UN", 
"World Health Organization": "WHO", 
"North Atlantic Treaty Organization": "NATO"
}, 
"OrgYear":  {
"International Monetary Fund": 1945, 
"United Nations": 1945, 
"World Health Organization": 1948, 
"North Atlantic Treaty Organization": 1949
}, 
"FruitAffinity":  {
"Guava": 0.8, 
"Apple": 0.8, 
"Banana": 0.6, 
"Oranges": 0.9
}
}
*/

The rest of this article discusses the three Input List Widget screen types.

Text Input List

A Text Input List screen allows a user to enter multiple text values into a single screen as exemplified in the image below:

In the code block below, the specific parameters with respect to the input screen above are the screenwidgetType JSON string, the widgetSchema JSON string and the options JSON array.

/*
{
"mainScreen":  {
"screenID": "OrgAbbrev", 
"screenDisplayArray": [
{
"localeCode": "en", 
"screenLabel": "1. Type in the abbreviations for the organizations listed below.
", 
"screenHint": "All inputs are compulsory.
"
}], 
"screenwidgetType": "textInputList", 
"inputRequired": true, 
"widgetSchema": "
\"OrgAbbrev\": {
\"type\": \"object\",
\"properties\":  {
\"International Monetary Fund\": {
\"type\": \"string\"
},
\"United Nations\": {
\"type\": \"string\"
},
\"World Health Organization\": {
\"type\": \"string\"
},
\"North Atlantic Treaty Organization\": {
\"type\": \"string\"
}
},
\"additionalProperties\": false
}", 
"options": ["International Monetary Fund", "United Nations", 
            "World Health Organization", "North Atlantic Treaty Organization"]
}
}
*/

The screenwidgetType is set to textInputList. The widgetSchema contains an escaped string for the input schema. In this case, the input schema is a JSON object called OrgAbbrev which has four properties that are of JSON string types. The text inputs for this screen must map to one of the schemas of these four properties. Note that the constraints on length and format can be applied to these four properties as is the case with textInput screens.

The options parameter is a JSON array that contains the text that labels each input textbox for the form screen.

Integer Input List

The JSON form specification for the Integer Input List screen is similar to that of the Text Input List screen with the exception that the properties of the object escaped in the widgetSchema are of JSON integer type and the screenwidgetType is set to integerInputList.

As can be seen in the code block below, the constraints, in terms of acceptable input value ranges, that apply to integerInput screens are also applicable here.

/*

{
"mainScreen":  {
"screenID": "OrgYear", 
"screenDisplayArray": [
{
"localeCode": "en", 
"screenLabel": "2. Type in the year in which each of these organizations listed where created.
", 
"screenHint": "Enter values between 1900 and 2000.
"
}], 
"screenwidgetType": "integerInputList", 
"inputRequired": true, 
"widgetSchema": "
\"OrgYear\": {
\"type\": \"object\",
\"properties\":  {
\"International Monetary Fund\": {
\"type\": \"integer\",
\"minimum\": 1900,
\"maximum\": 2000
},
\"United Nations\": {
\"type\": \"integer\",
\"minimum\": 1900,
\"maximum\": 2000
},
\"World Health Organization\": {
\"type\": \"integer\",
\"minimum\": 1900,
\"maximum\": 2000
},
\"North Atlantic Treaty Organization\": {
\"type\": \"integer\",
\"minimum\": 1900,
\"maximum\": 2000
}
},
\"additionalProperties\": false
}", 
"options": ["International Monetary Fund", "United Nations", 
            "World Health Organization", "North Atlantic Treaty Organization"]
}
}
*/

Number Input List

The image and code block in this section are self-explanatory.

/*

{
"mainScreen":  {
"screenID": "FruitAffinity", 
"screenDisplayArray": [
{
"localeCode": "en", 
"screenLabel": "3. On a scale of 0.1 to 0.9 how much do you like the fruits listed below?
", 
"screenHint": "Enter a valid decimal value in the range stated above.
"
}], 
"screenwidgetType": "numberInputList", 
"inputRequired": true, 
"widgetSchema": "
\"FruitAffinity\": {
\"type\": \"object\",
\"properties\":  {
\"Guava\": {
\"type\": \"number\",
\"minimum\": 0.1,
\"maximum\": 0.9
},
\"Apple\": {
\"type\": \"number\",
\"minimum\": 0.1,
\"maximum\": 0.9
},
\"Banana\": {
\"type\": \"number\",
\"minimum\": 0.1,
\"maximum\": 0.9
},
\"Oranges\": {
\"type\": \"number\",
\"minimum\": 0.1,
\"maximum\": 0.9
}
},
\"additionalProperties\": false
}", 
"options": ["Guava", "Apple", "Banana", "Oranges"]
}
}
*/

Next Chapter

Parameters that define screens that enable users to select one or more options from a given list is presented in Chapter 4.

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