Skip to main content

Show a message to the user

This guide explains how to send a message to the VIKTOR interface to inform/warn users. It will cover aspects as in what scenarios such messages come in handy, what steps to take to achieve this, and examples are given.

Warning message

One of the most common events in which we would like to warn a user is when one of the required inputs is not (yet) defined but still used at some point within the code. This could be either inputs through input fields, or file uploads for example. When this occurs, the app will crash and the user will only be able to see an error symbol. However, the programmer knows exactly what is happening and can therefore guide the user in the right direction by providing a warning message in the interface. This is implemented in the platform by raising an exception in the form of a so called UserException.

note

When a UserException is raised, the rest of the code will NOT be evaluated. In case the application should not be interrupted, one could consider implementing a Constraint on the input field(s).

Implementation

  1. Identify at what point in the code an event may occur where the user should be warned
  2. Catch this event (e.g. with if-else statements)
  3. Return the desired message through a UserException
from viktor import UserExceptionclass SomePythonClass:    def calculate_block_volume(self, params):        width = params.input.geometry.width        length = params.input.geometry.length        height = params.input.geometry.height        if not isinstance(width, (int, float)):            raise UserException("Input 'width' is not a number!")        if not isinstance(length, (int, float)):            raise UserException("Input 'length' is not a number!")        if not isinstance(height, (int, float)):            raise UserException("Input 'height' is not a number!")        return width * length * height

Progress message

Processing of analysis, optimization or downloadable content may take a while when working with large files or complex calculations. It may be useful to show the progress of the process to the user. It is possible to show the user a progress message and optionally a percentage of progress.

note

Whenever a progress message is invoked, the progress window will be "refreshed" with the specified text (i.e. old messages will be dropped).

Example usage

from viktor.core import progress_message

def process_files(my_files):
for file in my_files:
progress_message(message=f'Processing {file}')
... # process file

The progress_message also accepts a percentage. The platform will render the progress with your progress message and a progress bar showing the progress.

def process_files(my_files):
n = len(my_files)
for i, file in enumerate(my_files):
progress_message(message=f'Processing {file}', percentage=(i/n)*100)
... # process file

Extending a previous message

In some cases, it could be desired to keep showing the previous message to the user, and "append" with new information. This can be implemented by using line breaks within the message:

def process_files(my_files):    n = len(my_files)    for i, file in enumerate(my_files):        p_message = f'Reading {file}'        ... # read file        progress_message(message=p_message)        p_message += f'\n Processing {file}'        ... # process file        progress_message(message=p_message)        p_message += f'\n Export result of {file}'        ... # export results        progress_message(message=p_message)