App types

The type of app can be set in the viktor.config.toml file by means of the app_type entry. App layout, requirements and corresponding feedback errors might differ depending on the chosen app type. Currently, the following types are available:

• Editor: the app consists of a single editor. Every users gets a 'fresh' editor upon entry and data is not saved.

  Tutorial

• Simple: the app consists of a single entity type. Users can create, save and edit instances of this type. Entities are shared among multiple users.

  Tutorial

• Tree: the app consists of multiple entity types in a developer-specified hierarchy. Entities are shared among multiple users.

  Tutorial

Editor-type app

The simplest app structure consists of a single editor only. The user automatically enters the editor when opening the application workspace, with no additional navigation functionalities.

When a user opens the workspace, a unique session is created. Sessions are not shared among multiple users, and are automatically closed when leaving the editor (state is not saved).

info

The following are not available for the 'editor' app type:

• InitialEntity
• ParamsFromFile
• Storage
• Summary

Simple-type app

The simple is similar to the editor type, however the user is able to create multiple entities of an entity type and the state of an entity can be saved. Earlier created revisions can be restored if desired. The user enters a folder and can navigate to the desired entity by selecting from the entity table.

Tree-type app

More complex apps, consisting of an entity type hierarchy, can be created by choosing the tree app type.

Recommended folder structure

The app.py file can quickly become cluttered with a lot of code if your app grows in size. For tree-type apps we recommend to separate the code in sub-folders. This can be done by replacing the app.py file with a file called __init__.py within a folder named app and add sub-folders per entity type. Furthermore, it might be desirable to also split the controller and parametrization classes into separate files. For a hypothetical app with entity types BlueType and GreenType this looks as follows:

my-folder
├── app
│   ├── blue_type
│   │   ├── __init__.py
│   │   ├── controller.py
│   │   └── parametrization.py
│   ├── green_type
│   │   ├── __init__.py
│   │   ├── controller.py
│   │   └── parametrization.py
│   └── __init__.py  <- this is the new entry point of your app, replacing app.py
├── requirements.txt
└── viktor.config.toml

note

The __init__.py files in the entity type sub-folders are required to make Python treat directories containing the file as packages and can be left empty.

Importing controllers

If the controller class is in a separate file, it can be imported in the app's __init__.py file using Python's import command. For example, a controller class named BlueType in a file blue_type/controller.py can be imported in __init__.py as follows:

from .blue_type.controller import BlueType  # defines entity type 'BlueType'

If the class name itself does not equal the entity type name, you can import as an alias. For example, a class named Controller in a file blue_type/controller.py can be imported in the app's __init__.py file to act as the controller for the BlueType entity type as follows:

from .blue_type.controller import Controller as BlueType  # defines entity type 'BlueType'

Initial entities

For a tree app type, it's required to define initial entities in code, since the top layer is not editable by the user.

Initial entities can be set by means of the initial_entities variable in app.py, which is a list of InitialEntity objects. For example, adding an entity with name "An example entity" of type "ExampleType" would look like:

import viktor as vkt


class ExampleType(vkt.Controller):
   ...


initial_entities = [
    vkt.InitialEntity("ExampleType", name="An example entity", params=...)
]

note

On your development workspace, the initial entities including their children are applied on every start. On a production workspace, however, only the top level entities are applied the first time the workspace is created.

Click to see all available InitialEntity arguments

InitialEntity has the following arguments:

• entity_type_name (obligatory): Refers to the class name of the entity-type's controller (or its alias).

• name (obligatory): Name of the entity which is shown in the interface.

• params:

  params of the initial entity. If not defined, the default params will be set.

  Assume we have a parametrization with inputs width and length, the initial values can be set using a dictionary notation:

  vkt.InitialEntity(..., params={"width": 300, "length": 500})

  or by pointing to a .json file located relative to the app file:

  vkt.InitialEntity(..., params='initial_dimensions.json')

  with initial_dimensions.json:

  {
    "width": 300,
    "length": 500
  }

• children (tree-type app only)

  List of children defined as InitialEntity objects. If not defined, no children will be added. Each child must be a valid child-type of its parent (i.e. the child-type must be defined as one of the children on the parent controller).

  vkt.InitialEntity("ParentType", ..., children=[
    vkt.InitialEntity("ChildType", ...),
    ...
  ])

• show_on_dashboard (tree-type app only, only on top-level entities)

  This flag controls which top-level entities are shown as cards on the dashboard (default=True)