Code lists (options)
How to configure Options / Code lists for an app?
Altinn offers two different ways an application can use code lists - static and dynamic. Both is primarily exposed
through the options api from application, and are available at {org}/{app}/api/options/{optionsId}
.
Checkbox, Dropdown, and RadioButton components will automatically be able to fetch such lists if you connect the
component to the option id in question. Not all dynamic code list have to be fetched from the options api - we can also
have code lists based on the values from a repeating structure in the datamodel.
Connect the component to options (code list)
This is done by adding the optionId you would like to refer to either through the component UI in Designer or directly
in FormLayout.json
as shown below:
{
"id": "some-dropdown-component",
"type": "Dropdown",
"textResourceBindings": {},
"dataModelBindings": {},
"optionsId": "countries"
}
Save label value in the datamodel
Sometimes you might wish to save the displayed value in the users chosen language to simplify creation of simple presentations of data without addtional lookups or a requirement to remember the label the user actually picked in case it have changed over time.
This is performed by having a separate dataModelBindings
with the key "label":
in addition to "simpleBinding":
{
"id": "dropdown-component",
"type": "Dropdown",
"dataModelBindings": {
"simpleBinding": "soknad.nyGaranti.loyvetype",
"label":"soknad.nyGaranti.loyvetypeLabel"
},
"optionsId": "biler"
}
Pass query parameters when fetching options
Options supports query parameters when making the api call, the parameter language
is added automatically.
Pass static query parameters
You can add static query parameters by setting the queryParameters
property on the component:
{
"id": "some-dropdown-component",
"type": "Dropdown",
"textResourceBindings": {
"title": "NyGarantiLoyvetype"
},
"dataModelBindings": {
"simpleBinding": "soknad.nyGaranti.loyvetype"
},
"required": true,
"optionsId": "loyvetyper",
"queryParameters": {
"loyvetype": "garanti"
}
},
In the example above the parameter ?loyvetype=garanti
will be added to the request.
Pass dynamic query parameters based on the data model
You can add dynamic parameters by setting the mapping
property on the component:
{
"id": "some-dropdown-component",
"type": "Dropdown",
"textResourceBindings": {
"title": "NyGarantiLoyvetype"
},
"dataModelBindings": {
"simpleBinding": "soknad.nyGaranti.loyvetype"
},
"required": true,
"optionsId": "loyvetyper",
"mapping": {
"soknad.transportorOrgnummer": "orgnummer"
}
},
In the example above, the query parameter orgnummer={nr}
, where {nr}
is the value of soknad.transportorOrgnummer
will be set.
If an option is setup with mapping and the given data field changes app-frontend will refetch the option. This can be
used to dynamically decide which choices are available based on information given by the end user.
Passing query parameters from repeating groups is also supported by adding an index indicator for the relevant indexes. Example for a group:
{
"id": "dropdown-group",
"type": "Dropdown",
"textResourceBindings": {
"title": "Select city"
},
"dataModelBindings": {
"simpleBinding": "Group.City"
},
"required": true,
"optionsId": "cities",
"mapping": {
"Group[{0}].Country": "country"
}
},
For nested groups follows the same pattern but with an additional index indicator for the nested group:
{
"id": "dropdown-nested-group",
"type": "Dropdown",
"textResourceBindings": {
"title": "Select city"
},
"dataModelBindings": {
"simpleBinding": "Group.SubGroup.City"
},
"required": true,
"optionsId": "cities",
"mapping": {
"Group[{0}].SubGroup[{1}].Country": "country"
}
},
For a complete example of how this is setup see our demo app.
Applies to applications using version 7.4.0 or older of the nuget packages - https://github.com/Altinn/app-lib-dotnet/release
During PDF-generation the app will try to call the same option endpoint as app-frontend does. We currently have a weakness where mapping parameters not are included in this request, see issue #7903.
A possible workaround here is to return an empty array when the PDF-generator asks for options with empty query params, example:
string someArg = keyValuePairs.GetValueOrDefault("someArg");
string someOtherArg = keyValuePairs.GetValueOrDefault("someOtherArg");
if (string.IsNullOrEmpty(someArg) || string.IsNullOrEmpty(someOtherArg)) {
return await Task.FromResult(new List<AppOption>());
}
Notice that this wil result in the option value and not the label being present as the end users answer.
Store metadata for the parameters used to retrieve options in tha datamodel
You can store metadata for the parameters used to retrieve options in the datamodel by setting the metadata
property
on the components dataModelBinding
property:
{
"id": "some-dropdown-component",
"type": "Dropdown",
"textResourceBindings": {
"title": "NyGarantiLoyvetype"
},
"dataModelBindings": {
"simpleBinding": "soknad.nyGaranti.loyvetype",
"metadata": "soknad.transportorOrgnummer"
},
"required": true,
"optionsId": "loyvetyper",
"mapping": {
"soknad.transportorOrgnummer": "orgnummer"
}
},
This configuration will store the metadata of the retrieved options as a comma separated string in the
field soknad.transportorOrgnummer
in the datamodel.
Description and HelpText
description
and helpText
is supported by options in apps that use version v7.8.0 or higher. description
and
helpText
can be displayed by the components RadioButtons
and Checkboxes
by providing the option list with the
mentioned properties.
Descriptions and HelpTexts can be provided to options
in the same way that a label
is provided, in either static or
dynamic code lists. One can also use them in options based on repeating groups in the source
attribute.
[
{
"value": "norway",
"label": "Norge",
"description": "This is a description",
"helpText": "This is a help text"
},
{
"value": "denmark",
"label": "Danmark"
}
]
var options = new AppOptions
{
Options = new List<AppOption>
{
new AppOption
{
Label = "Ole",
Value = "1",
Description = "This is a description",
HelpText = "This is a help text"
},
new AppOption
{
Label = "Dole",
Value = "2"
}
}
};
Descriptions and help texts used in options based on repeating groups can be set up with dynamic text-resources in the same way as labels, described in options based on repeating groups.
{
"id": "checkboxes-component-id",
"type": "Checkboxes",
...
"source": {
"group": "some.group",
"label": "checkboxes.label",
"description": "checkboxes.descripiton",
"helpText": "checkboxes.helpText",
"value": "some.group[{0}].someField"
}
},
- Static code lists from the application repository
How to configure static code lists from the application repository.
- Dynamic code lists generated runtime
How to create dynamic code lists created during runtime execution of the application?
- Code lists based on repeating groups from the data model
How to configure code lists that gets it's values from a repeating group from the datamodel?
- Common shared code lists
How to re-use common code lists shared across applications?
- Re-use code lists from Altinn 2
How to configure code lists that exists in Altinn 2 in an Altinn 3 app?