Skip to main content

Options & selections

tip

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

Single option​

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

from viktor.parametrization import ViktorParametrization, OptionField


class Parametrization(ViktorParametrization):
    option = OptionField('This is an OptionField', options=['A', 'B'], default='A')

Autocomplete​

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

from viktor.parametrization import ViktorParametrization, AutocompleteField


class Parametrization(ViktorParametrization):
    option = AutocompleteField('This is an AutocompleteField', options=['A', 'B'], default='A')

Variants​

The OptionField can also be shown as a radio buttons (vertical & horizontal) using the variant argument:

OptionField('This is an OptionField shown as vertical radio buttons', variant='radio')
OptionField('This is an OptionField shown as horizontal radio buttons', variant='radio-inline')
note

The variants are ignored within a Table

Auto-select single option​

By default, no auto-selection takes place if only a single option is available. This default behaviour can be altered by setting the autoselect_single_option argument:

OptionField('This is an OptionField', options=['A'], autoselect_single_option=True)

This could be especially useful when using dynamic options.

Multi-select​

If multiple options need to be selectable, a MultiSelectField can be used. The value in the params is a list of all selected options.

from viktor.parametrization import ViktorParametrization, MultiSelectField


class Parametrization(ViktorParametrization):
    options = MultiSelectField('This is a MultiSelectField', options=['A', 'B'], default=['A', 'B'])

Use different label & value​

If options are of type str or float, the value in the params equals the label that is shown to the user. If you, for example, want to show a descriptive label to the user that differs from the value to be used in the code, you can use an OptionListElement:

OptionField('X', options=[OptionListElement('value_1', 'A nice description 1'), 
                          OptionListElement('value_2', 'A nice description 2')], default='value_1')

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:

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(ViktorParametrization):
    material_group = OptionField('Material group', options=['Aluminium', 'Steel'])
    material_type = 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 can be used to share data between 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:

from viktor.parametrization import ..., OptionListElement, IsEqual, Lookup

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

class Parametrization(ViktorParametrization):
    material_group = OptionField('Material group', options=['Aluminium', 'Steel'])
    material_type = 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:

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(ViktorParametrization):
    array = DynamicArray('Array')
    array.material_group = OptionField('Material group', options=['Aluminium', 'Steel'])
    array.material_type = OptionField('Material', options=get_material_options)