Skip to main content

Starter guide

Great to see you are ready to learn how to use VIKTOR! Here you will learn the basics of creating VIKTOR apps!

Before you continue, please make sure you completed the installation / activation instructions which include:

  • Installing Python on your computer
  • Installing a code editor on your computer (e.g. PyCharm or VS Code)
  • Activating your VIKTOR development account
New to Python?

Writing VIKTOR apps requires basic Python knowledge. If you are entirely new to this programming language, we advise to check out "Python for Non-Programmers" which lists learning resources including some nice interactive courses.

Set up the app​

Every new app setup starts by running the quickstart command, which will:

  • Download and extract a template app to your machine
  • Install the app's Python dependencies
  • Prompt to open the app in your code editor of choice

Before you continue, make sure that you have a code editor installed on your computer. We recommend using VS Code or PyCharm.

Now open Windows PowerShell using Start (or a terminal if you use Linux) and start by running the following command:

viktor-cli quickstart hello-viktor

and select your code editor of choice:

Your app is ready and located at: C:\Users\<USER>\viktor-apps\hello-viktor

? Do you want to open the app code in your code editor?  [Use arrows to move, type to filter]
> Open with `VS Code`
  Open with `PyCharm Community Edition 20XX.X.X`
  Skip

After pressing enter, the code editor will open the folder where the app is extracted to and automatically start the app as shown in the code editor's terminal. You may first see a security warning about trusting projects located in the viktor-apps directory.

Go ahead and tick the checkbox, followed by clicking the "Trust Project" button:

PyCharm should now open and look similar as shown below:

Do not close the terminal as this will break the connection with your app.

tip

Continuing development of an already existing app does not require you to run the quickstart command again. Simply open the project folder in your code editor and the app will automatically start!

Error?

viktor-cli not recognized

If you activated your account, continued with the starter guide and installed a code editor in the same session you might encounter the following error:

viktor-cli : The term 'viktor-cli' is not recognized as the name of a cmdlet, function, script file, or operable program. Check the spelling of the name, or if a path was included, verify that the path
is correct and try again.
At line:1 char:1
+ viktor-cli
+ ~~~~~~~~~~
    + CategoryInfo          : ObjectNotFound: (viktor-cli:String) [], CommandNotFoundException
    + FullyQualifiedErrorId : CommandNotFoundException

You can solve this error by closing and restarting your code editor. After doing so you can run the command without any problems. The problem is caused because your code editor inherits the environment variables of the process that launched it and because you installed the VIKTOR CLI in the same session it requires a restart to be recognized properly.

I cannot find my code editor's terminal

You can find the terminal as shown below:

Development workspace​

The Development workspace is where you can see and use the resulting app. Switch to VIKTOR in your browser:

  • If you continued with this starter guide immediately after activating your account you have been automatically redirected into your Development workspace. In that case simply refresh the browser to see your app.

  • If this is not the case you can navigate to the URL shown in the terminal. In the environment you can open the Development workspace by clicking the open button as shown in the image below:

After you have entered the development workspace you should see your connected app:

Create your first input fields​

Open the app.py file in your code editor. This is where you will write the code of your app. The content should look like this:

import viktor as vkt


class Parametrization(vkt.Parametrization):
    welcome = vkt.Text("# 👋 Welcome to your first VIKTOR app! 👋\n## Let's start with the basics")


class Controller(vkt.Controller):
    parametrization = Parametrization

The app.py file consists of 3 parts:

  • (line 1) imports: this is where you import Python modules you use in your app
  • (lines 4-5) Parametrization class: this is where you define the inputs of your app
  • (lines 8-9) Controller class: this is where you define the outputs (such as visualizations) of your app

A detailed explanation of the folder structure and above concepts can be found here.

App connection
  • The app will update automatically after adjusting and saving the app.py file (as long as you don't close the terminal!)
  • Closed your code editor or the terminal inside your editor? Use viktor-cli start to reconnect the app.

Let's add a NumberField by copying the highlighted line of code. Your app.py file should look like this:

import viktor as vkt


class Parametrization(vkt.Parametrization):
    welcome = vkt.Text("# 👋 Welcome to your first VIKTOR app! 👋\n## Let's start with the basics")
    length = vkt.NumberField("Length")


class Controller(vkt.Controller):
    parametrization = Parametrization

Save the app.py file. This action triggers a reload of your app. This reload is shown in the terminal. If you made a coding mistake, errors will also be printed in the terminal.

INFO    : Reloading app...
INFO    : App is ready

Refresh your webpage in the browser to see the "Length" input we just added:

Go ahead and click in the box just beneath "Length" to start typing.

In many cases it is helpful to guide the user by providing a default value for the input fields. You can add a default value of 1 like this:

import viktor as vkt


class Parametrization(vkt.Parametrization):
    welcome = vkt.Text("# 👋 Welcome to your first VIKTOR app! 👋\n## Let's start with the basics")
    length = vkt.NumberField("Length", default=1)


class Controller(vkt.Controller):
    parametrization = Parametrization

Save the app.py file and refresh your webpage in the browser. Any pop-up regarding unsaved changes may be ignored. After reloading, your app will show the default value:

To conclude the parametrization of our design, we will add 2 more number fields representing the "Width" and "Height" respectively. Copy the highlighted lines of code below such that your app.py file looks similar:

import viktor as vkt


class Parametrization(vkt.Parametrization):
    welcome = vkt.Text("# 👋 Welcome to your first VIKTOR app! 👋\n## Let's start with the basics")
    length = vkt.NumberField("Length", default=1)
    width = vkt.NumberField("Width", default=1)
    height = vkt.NumberField("Height", default=1)


class Controller(vkt.Controller):
    parametrization = Parametrization

Save the app.py file and refresh your webpage in the browser:

Create your first visualization​

Now let's see how we can use these input fields in a result! In this example we will use the length, width, and height defined in the parametrization as dimensions of a cube. The cube's volume and outer surface area are the results we will show in a table view.

Copy the highlighted lines of code below, such that your app.py file looks like this:

import viktor as vkt


class Parametrization(vkt.Parametrization):
    welcome = vkt.Text("# 👋 Welcome to your first VIKTOR app! 👋\n## Let's start with the basics")
    length = vkt.NumberField("Length", default=1)
    width = vkt.NumberField("Width", default=1)
    height = vkt.NumberField("Height", default=1)


class Controller(vkt.Controller):
    parametrization = Parametrization

    @vkt.TableView("Results")
    def results(self, params, **kwargs):
        data = [
            [1, 2],
            [3, 4],
        ]
        row_headers = ["Row 1", "Row 2"]
        column_headers = ["Col 1", "Col 2"]
        return vkt.TableResult(data, row_headers=row_headers, column_headers=column_headers)

Save the app.py file and refresh your webpage in the browser:

Great, now let's connect the input values (obtained using the params argument) to the output. We will also rename the row and column headers to be more specific for our app:

import viktor as vkt


class Parametrization(vkt.Parametrization):
    welcome = vkt.Text("# 👋 Welcome to your first VIKTOR app! 👋\n## Let's start with the basics")
    length = vkt.NumberField("Length", default=1)
    width = vkt.NumberField("Width", default=1)
    height = vkt.NumberField("Height", default=1)


class Controller(vkt.Controller):
    parametrization = Parametrization

    @vkt.TableView("Results")
    def results(self, params, **kwargs):
        volume = params.length * params.width * params.height
        surface = 2 * (params.length * params.width + params.length * params.height + params.width * params.height)
        data = [
            [volume, "m³"],
            [surface, "m²"],
        ]
        row_headers = ["Volume", "Surface"]
        column_headers = ["Value", "Unit"]
        return vkt.TableResult(data, row_headers=row_headers, column_headers=column_headers)

Save the app.py file and refresh your webpage in the browser:

Well done! You can now adjust the dimensions of the cube and directly see its effect on the volume and outer surface area.

Automate the boring!​

With these basic instructions you now have the skills to build your very own apps!

This is just the tip of the iceberg however. With VIKTOR you can also create 3D models, interactive data visualizations, automated reports, geographic maps and much more... Click the button below to continue your journey!