Advanced JSON Form Specification - Chapter 3: Input List Widgets





5.00/5 (1 vote)
A JSON form specification
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
- 18th July, 2016: First version
- 3rd November, 2016: Made corrections to this work