Skip to main content

The parametrization class

New in v13.0.0

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

New in v13.0.0

The FileField and MultiFileField allow users to upload one or multiple files

New in v12.8.0

OptionField radio and radio-inline variants

Changed in v12.8.0

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

  • ChildEntityOptionField
  • SiblingEntityOptionField
  • ChildEntityMultiSelectField
  • SiblingEntityMultiSelectField
New in v12.1.0

Various fields have been renamed:

  • TextAreaInput -> TextAreaField
  • ToggleButton -> BooleanField
  • AnalyseButton -> ActionButton
  • OptimiseButton -> OptimizationButton
  • MultipleSelectField -> MultiSelectField
  • TableInput -> Table
New in v12.1.0

Parametrization can consist of 1 layer (field) or 2 layers (Tab + field, Section + field)

The Parametrization class defines the parameters of an entity type (e.g. length, width and height of a beam). Below is an overview of different forms of parametrizations and possible input fields.

A simple parametrization looks as follows:

from viktor.parametrization import ViktorParametrization, TextField, NumberFieldclass ExampleParametrization(ViktorParametrization):    input_1 = TextField('This is a text field')    input_2 = NumberField('This is a number field')

Parametrization, no tabs and sections

In some cases, the parametrization becomes quite big which requires a more structured layout. This can be achieved by making use of a Tab and Section, which represent a tab and collapsible section in the interface respectively.

A 2-layered structure using Tab objects looks like this:

from viktor.parametrization import ViktorParametrization, TextField, NumberField, Tabclass ExampleParametrization(ViktorParametrization):    tab_1 = Tab('Tab 1')    tab_1.input_1 = TextField('This is a text field')    tab_1.input_2 = NumberField('This is a number field')    tab_2 = Tab('Tab 2')    tab_2.input_1 = TextField('Text field in Tab 1')    tab_2.input_2 = NumberField('Number field in Tab 1')

Parametrization with tabs, no sections

Using Section objects results in the following:

from viktor.parametrization import ViktorParametrization, TextField, NumberField, Sectionclass ExampleParametrization(ViktorParametrization):    section_1 = Section('Section 1')    section_1.input_1 = TextField('This is a text field')    section_1.input_2 = NumberField('This is a number field')    section_2 = Section('Section 2')    section_2.input_1 = TextField('Text field in Section 1')    section_2.input_2 = NumberField('Number field in Section 1')

Parametrization with sections, no tabs

A parametrization with a maximum depth of 3 layers consists of Tab, Section, and Field objects:

from viktor.parametrization import ViktorParametrization, TextField, NumberField, Tab, Sectionclass ExampleParametrization(ViktorParametrization):    tab_1 = Tab('Tab 1')    tab_1.section_1 = Section('Section 1')    tab_1.section_1.input_1 = TextField('This is a text field')    tab_1.section_1.input_2 = NumberField('This is a number field')    tab_1.section_2 = Section('Section 2')    ...    tab_2 = Tab('Tab 2')    ...

Parametrization with sections and tabs

Input fields

The parametrization is built up by means of input fields that can be filled in by the user. Different types of input fields can be used, For each input field, arguments can be specified to set specific options and/or constraints such as the default, minimum, or maximum value. See the Field docstring for the possible options.

The following table gives an overview of all input fields that can be created:

Input fieldDescription
Text (>= v12.7.0)A static informative text (no input)
TextFieldA text input can be specified here
TextAreaFieldSimilar as a TextField, but for longer inputs (e.g. multiple sentences or complete paragraphs)
NumberFieldNumbers can be specified here, which can contain decimals
IntegerFieldThis is a specific NumberField case and can contain integers only
DateFieldA date can be selected in this input field in calender format
BooleanFieldA toggle button that can be either on or off
OutputFieldData (e.g. summation of two NumberFields) can be shown to the user, which cannot be edited
HiddenFieldTo store data in the parametrization, without showing it to the user
LineBreakA line break can be inserted to have successive fields start on a new row in the interface
OptionFieldA field containing different options
MultiSelectFieldIf multiple options should be considered for an input, this field can be created
AutocompleteFieldIn order to select an item from very large lists of possible inputs, tis field makes use of a text entry to find the specific input string
EntityOptionField (>= v13.0.0)Option-field for the selection of an entity with certain type(s)
ChildEntityOptionFieldOption-field for the selection of a child entity with certain type(s)
SiblingEntityOptionFieldOption-field for the selection of a sibling entity with certain type(s)
EntityMultiSelectField (>= v13.0.0)Multiselect-field for the selection of zero or more entities with certain type(s), with a limit of 5000 entities
ChildEntityMultiSelectFieldMultiselect-field for the selection of zero or more child entities with certain type(s), with a limit of 5000 entities
SiblingEntityMultiSelectFieldMultiselect-field for the selection of zero or more sibling entities with certain type(s), with a limit of 5000 entities
GeoPointFieldAllows a user to set a GeoPoint by directly clicking on a MapView
GeoPolylineFieldAllows a user to define a GeoPolyline by directly clicking on a MapView
GeoPolygonFieldAllows a user to define a GeoPolygon by directly clicking on a MapView
FileField (>= v13.0.0)Allows a user to upload a file
MultiFileField (>= v13.0.0)Allows a user to upload one or multiple files

Action buttons

In addition to the input fields, action buttons can be added to the parametrization to enable user actions. The following table gives an overview of all action buttons:

Action buttonDescription
ActionButtonDo some action without returning a result
DownloadButtonDownload a result to a file
OptimizationButtonPerform an optimization routine
SetParamsButtonPerform an analysis and override current input fields

Table vs DynamicArray

Both a Table and a DynamicArray can be used if the user must be able to make a dynamic number of objects sharing the same properties. The similarities and differences between the two are discussed below.

Setting up a Table or a DynamicArray follows the same structure as adding input fields to a Tab or Section object as shown below:

from viktor.parametrization import ViktorParametrization, DynamicArray, Table, TextFieldclass ExampleParametrization(ViktorParametrization):    field = TextField('This is an example field')    # table    table = Table('Table')    table.col_1 = TextField('TextField as table column')    # dynamic array    array = DynamicArray('Array')    array.col_1 = TextField('TextField as array field')

In the interface this parametrization looks like this:

Table vs. DynamicArray

In addition to these visual difference, there are more practical differences between the input fields which may determine the best solution for your use-case. The following comparison can be made:

TableDynamicArray
CompactLess compact
RectangularNot necessarily rectangular
Defaults when adding a new row is not supportedDefaults when adding a new row is supported
Options in OptionField cannot make use of a labelOptions in OptionField can make use of a label
Supports copy-paste of complete table contentSupports copy-paste per input field only
User can create rowsUser can create rows
User cannot create columnsUser cannot create fields, but may use dynamic visibility

Furthermore, not all regular fields can be used in both of these multi-row fields. The table below shows which fields are supported in the Table and DynamicArray

FieldTableDynamicArray
Text××
TextField
TextAreaField×
NumberField
IntegerField
BooleanField
DateField×
OutputField××
HiddenField××
LineBreak×
OptionField
MultiSelectField×
AutocompleteField
EntityOptionField×
ChildEntityOptionField×
SiblingEntityOptionField×
EntityMultiSelectField×
ChildEntityMultiSelectField×
SiblingEntityMultiSelectField×
FileField×
MultiFileField×
GeoPointField×✓ (>= v12.2.0)
GeoPolylineField×✓ (>= v12.2.0)
GeoPolygonField×✓ (>= v12.2.0)
ActionButton××
DownloadButton××
OptimizationButton××
SetParamsButton××

In the comparison, rectangular means that each row in the Table contains the same columns visually as well as in the parameter set. Rows in a DynamicArray on the other hand could contain different input fields, by making use of the visibility of these fields. This allows a user to make input fields (dis)appear by, for example, selecting a toggle.

from viktor.parametrization import ViktorParametrization, DynamicArray, Table, RowLookup, NumberField, TextField, \    BooleanFieldclass ExampleParametrization(ViktorParametrization):    field = TextField('This is an example field')    # table    table = Table('Table')    table.col_1 = TextField('TextField as table column')    table.col_2 = BooleanField('BooleanField')    table.col_3 = NumberField('NumberField')  # visible not supported    # dynamic array    array = DynamicArray('Array')    array.col_1 = TextField('TextField as array field')    array.col_2 = BooleanField('BooleanField')    array.col_3 = NumberField('NumberField', visible=RowLookup('col_2'))

In this example, a DynamicArray row in which the toggle (col_2) is active will also show the NumberField (col_3). In a Table col_3 is always visible.

Visibility of columns/fields

Creating a Page

New in v12.5.0

A Page can be used to construct a combination of inputs (e.g. tabs / sections) and outputs (views). This grouping allows for specific views to become visible, depending on the page a user has selected.

Assume an editor with a GeometryView and a DataView:

...


class ExampleController(ViktorController):
...

@GeometryView(...)
def geometry_view(...):
...

@DataView(...)
def data_view(...):
...

Now we would like to have an editor with 2 pages. When a user is working on "Page 1", no views will be visible. When the user switches to "Page 2", a geometry view and a data view will become visible.

A Page is defined in the parametrization similar to a Tab or Section:

from viktor.parametrization import ViktorParametrization, Page, TextField, NumberFieldclass ExampleParametrization(ViktorParametrization):    page_1 = Page('Page 1 - without views')    page_1.input_1 = TextField('This is a text field')    page_1.input_2 = NumberField('This is a number field')    page_2 = Page('Page 2 - with views', views=['geometry_view', 'data_view'])    page_2.input_1 = TextField('This is a text field')    page_2.input_2 = NumberField('This is a number field')

Page 1 with no views

Page 2 with a GeometryView and a DataView

All the layered structures of Tab / Section / fields as described earlier can be encapsulated in a Page:

# fields directly as input fields on a pageclass ExampleParametrization(ViktorParametrization):    page = Page(...)    page.number = NumberField(...)    ...# tabs on a pageclass ExampleParametrization(ViktorParametrization):    page = Page(...)    page.tab = Tab(...)    ...# sections on a pageclass ExampleParametrization(ViktorParametrization):    page = Page(...)    page.section = Section(...)    ...

Creating a Step

New in v12.9.0

Similar to creating a Page, grouping can be achieved by using the Step class. Other than with Page, with Step the developer can dictate the order of pages to be visited, i.e. the user is not able to move freely between pages but moves to the next/previous step with a next/previous button.

A Step is defined in the parametrization similar to a Page. The labels of the next and previous buttons can be set per step:

from viktor.parametrization import ViktorParametrization, Step, TextField, NumberFieldclass ExampleParametrization(ViktorParametrization):    step_1 = Step('Step 1 - without views', next_label="Go to step 2")    step_1.input_1 = TextField('This is a text field')    step_1.input_2 = NumberField('This is a number field')    step_2 = Step('Step 2 - with views', views=['geometry_view', 'data_view'], previous_label="Go to step 1")    step_2.input_1 = TextField('This is a text field')    step_2.input_2 = NumberField('This is a number field')

Page and Step objects cannot be combined within a parametrization.