Options & selections

Reference

For a more technical API reference, please see the following pages:

OptionField - single option

To present a dropdown list with options to select from, an OptionField can be used.

import viktor as vkt

fruits = ['Avocado', 'Banana', 'Coconut']

class Parametrization(vkt.Parametrization):
    option = vkt.OptionField('Pick your favorite fruit', options=fruits)
    radio_v = vkt.OptionField('Pick your favorite fruit', options=fruits, variant='radio')
    radio_h = vkt.OptionField('Pick your favorite fruit', options=fruits, variant='radio-inline')

The user input can be obtained through the params argument and can have the following values:

int / float / str: when user selects an option
None: when empty

Expand to see all available arguments

In alphabetical order:

autoselect_single_option: (default=False) automatically select when only a single option is available, relevant in case of dynamic options
```
option = vkt.OptionField('Pick your favorite fruit', options=fruits, autoselect_single_option=True)
```

default: a default value will be prefilled

option = vkt.OptionField('Pick your favorite fruit', options=fruits, default="Coconut")

description: add a tooltip with additional information

option = vkt.OptionField('Pick your favorite fruit', options=fruits, description="This input represents the ...")

flex: the width of the field between 0 and 100 (default=33)

option = vkt.OptionField('Pick your favorite fruit', options=fruits, flex=50)

name: defines the position of the parameter in the params

option = vkt.OptionField('Pick your favorite fruit', options=fruits, name="o")  # obtained using params.o

options: available options a user can select from

can be defined as list of strings

option = vkt.OptionField('Pick your favorite fruit', options=['Avocado', 'Banana', 'Coconut'])

..or as list of numbers

option = vkt.OptionField('...', options=[1, 2, 3])

..or as list of OptionListElement objects

option = vkt.OptionField(
    'Pick your favorite fruit',
    options=[
        OptionListElement(value=1, label="Avocado"), # when selected, params.option will be 1
        OptionListElement(value=2, label="Banana"),
        OptionListElement(value=3, label="Coconut"),
    ]
)

prefix: a prefix will be put in front of the ui name

option = vkt.OptionField('Pick your favorite fruit', options=fruits, prefix="..")

suffix: a suffix will be placed behind the ui name

option = vkt.OptionField('Pick your favorite fruit', options=fruits, suffix="..")

variant: the field can be shown as radio buttons

option = vkt.OptionField('Pick your favorite fruit', options=fruits, variant='radio')

option = vkt.OptionField('Pick your favorite fruit', options=fruits, variant='radio-inline')

note

The variants are ignored within a Table

visible: can be used when the visibility depends on other input fields
```
option = vkt.OptionField('Pick your favorite fruit', options=fruits, visible=vkt.Lookup("another_field"))
```
See 'Hide a field' for elaborate examples.

Autocomplete

If there are many options, it might be desirable for the user to filter options by typing. This is possible using the AutocompleteField.

import viktor as vkt

fruits = ['Avocado', 'Banana', 'Coconut']

class Parametrization(vkt.Parametrization):
    option = vkt.AutocompleteField('Pick your favorite fruit (type to filter)', options=fruits)

Expand to see all available arguments

In alphabetical order:

default: a default value will be prefilled

option = vkt.AutocompleteField(
    'Pick your favorite fruit (type to filter)', options=fruits, default="Coconut"
)

description: add a tooltip with additional information

option = vkt.AutocompleteField(
    'Pick your favorite fruit (type to filter)', options=fruits, description="This input represents the ..."
)

flex: the width of the field between 0 and 100 (default=33)

option = vkt.AutocompleteField(
    'Pick your favorite fruit (type to filter)', options=fruits, flex=50
)

name: defines the position of the parameter in the params

option = vkt.AutocompleteField(
    'Pick your favorite fruit (type to filter)', options=fruits, name="o"
)  # obtained using params.o

options: available options a user can select from

can be defined as list of strings

option = vkt.AutocompleteField(
    'Pick your favorite fruit (type to filter)', options=['Avocado', 'Banana', 'Coconut']
)

..or as list of numbers

option = vkt.AutocompleteField('...', options=[1, 2, 3])

..or as list of OptionListElement objects

option = vkt.AutocompleteField(
    'Pick your favorite fruit (type to filter)',
    options=[
        OptionListElement(value=1, label="Avocado"), # when selected, params.option will be 1
        OptionListElement(value=2, label="Banana"),
        OptionListElement(value=3, label="Coconut"),
    ]
)

prefix: a prefix will be put in front of the ui name

option = vkt.AutocompleteField(
    'Pick your favorite fruit (type to filter)', options=fruits, prefix=".."
)

suffix: a suffix will be placed behind the ui name

option = vkt.AutocompleteField(
    'Pick your favorite fruit (type to filter)', options=fruits, suffix=".."
)

visible: can be used when the visibility depends on other input fields

option = vkt.AutocompleteField(
    'Pick your favorite fruit (type to filter)', options=fruits, visible=vkt.Lookup("another_field")
)

See 'Hide a field' for elaborate examples.

Selecting an entity

In case you need to create an option field with entities as options, you can make use of dedicated entity selection fields.

MultiSelectField - multiple options

If multiple options need to be selectable, a MultiSelectField can be used.

import viktor as vkt

fruits = ['Avocado', 'Banana', 'Coconut']

class Parametrization(vkt.Parametrization):
    options = vkt.MultiSelectField('Pick your favorite fruit(s)', options=fruits)

The user input can be obtained through the params argument and can have the following values:

list: when user selects one or multiple options
empty list when nothing is selected

Expand to see all available arguments

In alphabetical order:

default: a default value will be prefilled

options = vkt.MultiSelectField(
    'Pick your favorite fruit(s)', options=fruits, default=["Avocado", "Coconut"]
)

description: add a tooltip with additional information

options = vkt.MultiSelectField(
    'Pick your favorite fruit(s)', options=fruits, description="This input represents the ..."
)

flex: the width of the field between 0 and 100 (default=33)

options = vkt.MultiSelectField(
    'Pick your favorite fruit(s)', options=fruits, flex=50
)

name: defines the position of the parameter in the params

options = vkt.MultiSelectField(
    'Pick your favorite fruit(s)', options=fruits, name="o"
)  # obtained using params.o

options: available options a user can select from

can be defined as list of strings

options = vkt.MultiSelectField(
    'Pick your favorite fruit(s)', options=['Avocado', 'Banana', 'Coconut']
)

..or as list of numbers

options = vkt.MultiSelectField('...', options=[1, 2, 3])

..or as list of OptionListElement objects

options = vkt.MultiSelectField(
    'Pick your favorite fruit(s)',
    options=[
        OptionListElement(value=1, label="Avocado"), # when selected, params.options will be [1]
        OptionListElement(value=2, label="Banana"),
        OptionListElement(value=3, label="Coconut"),
    ]
)

prefix: a prefix will be put in front of the ui name

options = vkt.MultiSelectField(
    'Pick your favorite fruit(s)', options=fruits, prefix=".."
)

suffix: a suffix will be placed behind the ui name

options = vkt.MultiSelectField(
    'Pick your favorite fruit(s)', options=fruits, suffix=".."
)

visible: can be used when the visibility depends on other input fields

options = vkt.MultiSelectField(
    'Pick your favorite fruit(s)', options=fruits, visible=vkt.Lookup("another_field")
)

See 'Hide a field' for elaborate examples.

Selecting entities

In case you need to create an option field with entities as options, you can make use of dedicated entity selection fields.

Dynamic options

Sometimes it is desired to create options dynamically (depending on other parameters). This can be achieved in several ways:

Using a function

The most generic way to dynamically set the options is to use a 'callback function'. Upon evaluation of the options, the platform passes the params, entity_id, entity_name, and workspace_id (>= v14.7.1) to the custom function. For example, material options can be set based on a pre-selected material type as follows:

import viktor as vkt


def get_material_options(params, **kwargs):
    if params.material_group == 'Aluminium':
        return ['Aluminium 5083', 'Aluminium 6082']
    elif params.material_group == 'Steel':
        return ['Steel S355', 'Steel S690']
    else:
        return []

class Parametrization(vkt.Parametrization):
    material_group = vkt.OptionField('Material group', options=['Aluminium', 'Steel'])
    material_type = vkt.OptionField('Material', options=get_material_options)

tip

All individual kwargs can be added explicitly in the signature if needed:

def get_material_options(params, entity_id, entity_name, workspace_id, **kwargs):
    ...

With a callback function it is also possible to make use of the entity_id to navigate to and obtain data from other entities using the API.

OptionListElement visibility

The same dynamic options as above can be achieved by making use of the visible argument on an OptionListElement. By using the IsEqual and Lookup operators, we can make use of the visibility to hide/show options, similar as hiding/showing fields:

import viktor as vkt


material_options = [
    vkt.OptionListElement('Aluminium 5083', visible=vkt.IsEqual(vkt.Lookup('material_group'), 'Aluminium')),
    vkt.OptionListElement('Aluminium 6082', visible=vkt.IsEqual(vkt.Lookup('material_group'), 'Aluminium')),
    vkt.OptionListElement('Steel S355', visible=vkt.IsEqual(vkt.Lookup('material_group'), 'Steel')),
    vkt.OptionListElement('Steel S690', visible=vkt.IsEqual(vkt.Lookup('material_group'), 'Steel'))
]

class Parametrization(vkt.Parametrization):
    material_group = vkt.OptionField('Material group', options=['Aluminium', 'Steel'])
    material_type = vkt.OptionField('Material', options=material_options)

Inside a DynamicArray

New in v14.8.0

If the options should be filled depending on another field within a DynamicArray, a callback function can be used to return a list of lists. Each sublist represents the options of the corresponding array row. Make sure that the length of the list is equal to the number of rows in the array:

import viktor as vkt


def get_material_options(params, **kwargs):
    options = []
    for row in params.array:
        if row['material_group'] == 'Aluminium':
            options.append(['Aluminium 5083', 'Aluminium 6082'])
        elif row['material_group'] == 'Steel':
            options.append(['Steel S355', 'Steel S690'])
    return options

class Parametrization(vkt.Parametrization):
    array = vkt.DynamicArray('Array')
    array.material_group = vkt.OptionField('Material group', options=['Aluminium', 'Steel'])
    array.material_type = vkt.OptionField('Material', options=get_material_options)

Options & selections

OptionField - single option​

Autocomplete​

Selecting an entity​

MultiSelectField - multiple options​

Selecting entities​

Dynamic options​

Using a function​

OptionListElement visibility​

Inside a DynamicArray​

OptionField - single option

Autocomplete

Selecting an entity

MultiSelectField - multiple options

Selecting entities

Dynamic options

Using a function

OptionListElement visibility

Inside a DynamicArray