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:
ChildEntityOptionFieldSiblingEntityOptionFieldChildEntityMultiSelectFieldSiblingEntityMultiSelectField
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 field | Description |
|---|---|
Text (>= v12.7.0) | A static informative text (no input) |
TextField | A text input can be specified here |
TextAreaField | Similar as a TextField, but for longer inputs (e.g. multiple sentences or complete paragraphs) |
NumberField | Numbers can be specified here, which can contain decimals |
IntegerField | This is a specific NumberField case and can contain integers only |
DateField | A date can be selected in this input field in calender format |
BooleanField | A toggle button that can be either on or off |
OutputField | Data (e.g. summation of two NumberFields) can be shown to the user, which cannot be edited |
HiddenField | To store data in the parametrization, without showing it to the user |
LineBreak | A line break can be inserted to have successive fields start on a new row in the interface |
OptionField | A field containing different options |
MultiSelectField | If multiple options should be considered for an input, this field can be created |
AutocompleteField | In 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) |
ChildEntityOptionField | Option-field for the selection of a child entity with certain type(s) |
SiblingEntityOptionField | Option-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 |
ChildEntityMultiSelectField | Multiselect-field for the selection of zero or more child entities with certain type(s), with a limit of 5000 entities |
SiblingEntityMultiSelectField | Multiselect-field for the selection of zero or more sibling entities with certain type(s), with a limit of 5000 entities |
GeoPointField | Allows a user to set a GeoPoint by directly clicking on a MapView |
GeoPolylineField | Allows a user to define a GeoPolyline by directly clicking on a MapView |
GeoPolygonField | Allows 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 button | Description |
|---|---|
ActionButton | Do some action without returning a result |
DownloadButton | Download a result to a file |
OptimizationButton | Perform an optimization routine |
SetParamsButton | Perform 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:
| Table | DynamicArray |
|---|---|
| Compact | Less compact |
| Rectangular | Not necessarily rectangular |
| Defaults when adding a new row is not supported | Defaults when adding a new row is supported |
Options in OptionField cannot make use of a label | Options in OptionField can make use of a label |
| Supports copy-paste of complete table content | Supports copy-paste per input field only |
| User can create rows | User can create rows |
| User cannot create columns | User 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
| Field | Table | DynamicArray |
|---|---|---|
| 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.