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 (>= v13.0.0).

New in v12.3.0

Simple options can be defined without an OptionListElement class.

Single option​

New in v12.8.0

OptionField radio and radio-inline variants

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​

Changed in v12.1.0

MultipleSelectField has been renamed to MultiSelectField

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, and entity_name 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, **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)