Entity selection

Changed in v12.8.0

Entity selection fields return an Entity object instead of an entity id (integer) when the controller flag viktor_convert_entity_field is set to True. This affects the following fields:

• ChildEntityOptionField
• SiblingEntityOptionField
• ChildEntityMultiSelectField
• SiblingEntityMultiSelectField

When an entity depends on one or more other entities, the entity selection fields enable the user to make this selection. This is especially useful when making a tree-type app.

If none of the below entity selection fields are sufficient, data between entities can be shared using the API.

Select child(ren)

For the selection of a single child entity, the ChildEntityOptionField can be used. For example, when the entity type structure of your application looks similar to the following, and you need your users to select one of the child entities of a Project, the following code can be used:

ProjectFolder
└── Project
    └── CPTFile

from viktor.parametrization import ViktorParametrization, ChildEntityOptionField


class Parametrization(ViktorParametrization):
    selected_cpt = ChildEntityOptionField('Select a CPT')

In case multiple children should be selectable, the ChildEntityMultiSelectField can be used.

Select sibling(s)

Similar to children, siblings can be selected using the SiblingEntityOptionField:

from viktor.parametrization import ViktorParametrization, SiblingEntityOptionField


class Parametrization(ViktorParametrization):
    selected_sibling = SiblingEntityOptionField('Select a sibling')

In case multiple siblings should be selectable, the SiblingEntityMultiSelectField can be used.

Select generic entity

New in v13.0.0

EntityOptionField and EntityMultiSelectField can be used for selecting entities of given type. This will greatly improve the speed of apps where option fields are dynamically filled with entities.

In some cases, both the ChildEntityOptionField and SiblingEntityOptionField may not be sufficient because the entities you need to select are in a different part of the entity type tree. In the following example, we want to select a CPTFile entity in a Foundation entity:

ProjectFolder
└── Project
    ├── CPTFolder
    │   └── CPTFile
    └── Foundation

We can make use of the EntityOptionField and the entity_type_names attribute to filter which entity type(s) should be selectable:

from viktor.parametrization import ViktorParametrization, EntityOptionField


class FoundationParametrization(ViktorParametrization):
    selected_cpt = EntityOptionField('CPT File', entity_type_names=['CPTFile'])

Or use the EntityMultiSelectField when multiple entities should be selectable:

Entity object

Changed in v12.8.0

When the user selects an entity with these fields, the entity is returned in the params as Entity object. Please have a look at sharing information between entities for more detail on how to use an Entity.

from viktor import ViktorController
from viktor.parametrization import ViktorParametrization, EntityOptionField


class Parametrization(ViktorParametrization):
        cpt_entity = EntityOptionField('Select a CPT', entity_type_names=['CPTFile'])


class MyController(ViktorController):
    ...

    @DataView("CPT data", duration_guess=3)
    def visualize(self, params, **kwargs):
        cpt_entity = params.cpt_entity  # Entity | None
        if cpt_entity:
            return DataResult(DataGroup(
                x=DataItem('CPT X coordinate', cpt_entity.last_saved_params.x_coordinate),
                y=DataItem('CPT Y coordinate', cpt_entity.last_saved_params.y_coordinate)
            ))
        return DataResult(DataGroup())