Skip to content

Web app

Introduction🔗

Users can create their web applications and run them from within or outside of Modelon Impact. Simulation and web-app specialists can prepare a web page that executes with a specific Modelon Impact model through the REST API. Web apps pass inputs and read results from that model and have customized interactive post-processing based on modern web technologies.

Note

Web apps can be launched directly from the Workspace selection screen by clicking on . Some may only be available when a workspace is opened.

Below example shows a web app describing a simple electric vehicle. It allows a user to select different power-train components (e.g. motor, battery, ...) and run an analysis. The analysis then calculates the electric driving range of the selected combination.

This application can be shared and used by multiple users.

Tip

Modelon can help you to create your web app. Contact us to get more information.

Before we start the tutorial🔗

You will need approximately 20 minutes to finish all tutorial steps.

Attention

It is expected that a person creating and maintaining a web app has experience in HTML, CSS and Javascript and some experience with running commands in a console.

What are we building?

In this tutorial, we'll show how to add and execute a web-app example, allowing you to run and post-process any opened model.

A simple heating system model Modelica.Fluid.Examples.HeatingSystem has been chosen for this exercise.

You will learn how to:

  • Setup development environment for a web-app
  • Adjust the web app
  • Prepare the web app for deployment/sharing

Working with web-apps🔗

Example of working web apps for Modelon Impact can be found on GitHub.

Tools used🔗

This tutorial requires that you have Git and NPM installed on your computer and can access them in the console. You can download installers for git from here and for NPM from here.

Before we continue, please open the command line interface (console) of your choice and run the following commands:

git --version

npm --version

If the programs are correctly installed this should print version numbers.

Explore an example🔗

Let's start by checking out the example code from GitHub:

git clone https://github.com/modelon-community/impact-webapp-example

Tip

You can also fork the project on GitHub and clone the fork. That way you can commit any changes to keep track of your work.

Proceed with entering the directory of the pressure cycle example:

cd impact-webapp-example/pressure-cycle

Tip

Go https://github.com/modelon-community/impact-webapp-example/tree/master/pressure-cycle to read about the web-app structure.

This is the project directory of a web app and contains a variety of files and directories. You can get an in-depth description of each of them in the README.md-file. Right now we are only concerned with the package.json-file, as it defines the project.

In the package.json file, let's look at the dependencies and devDependencies attributes. They state the packages and their respective versions that the project depends on. The devDependencies in particular lists the packages that are needed for supporting development, like various tools for building the project. dependencies list the dependencies that our web app needs to function. In this example, we have the impact-client, which is a convenience library for interacting with Impact through its REST API, and plotly.js-dist, a plotting library that we can use for graphing out the result of a simulation.

Let's go ahead and install our dependencies:

npm install

If everything has finished without any errors, a directory named node_modules should be present in the project.

Let's peek into the package.json file again. Aside from dependencies and project-info, there is an attribute called scripts that allows you to map custom commands to keywords. In our example we have:

  • build - builds the contents of the src-directory and put the result in a dist-directory.
  • watch - starts a watcher that automatically rebuilds when changes are detected in the src-directory. Nice to have during development.
  • proxy - starts a proxy server that makes it possible to call your Impact installation from the development environment. (I.e. you don't need to deploy your code to the installation every time you want to test while developing.)
  • clean - removes the dist-directory.

Each of these scripts can be run by prefixing with npm run at the command prompt. Let's build the project:

npm run build

A dist-directory should now be present. If we compare the contents of the src-directory with that of the dist-directory, we see that the main difference is src/index.js and dist/main.js. index.js in the src-directory contains the application logic, and main.js in dist is the complete bundle of the application logic with the dependencies we saw listed in package.json. In other words, the dist-directory contains the distributable files that you publish. We'll go into detail about how that is done in a bit.

While we are developing our application, the cycle of deploying the web app to the installation for each rebuild is tedious. The proxy allows you to serve the contents of the dist-directory as if it was deployed to Impact.

To start the proxy, enter the following into the command prompt:

npm run proxy

This will by default target the local installation located at http://127.0.0.1:8080 and serve the web app on port 3000 (i.e. you can access the example on http://127.0.0.1:3000 in the browser). If you need to target a different install and/or listen to another port, you do so by setting the environment variables TARGET and PORT respectively before issuing the command:

On Windows:

set TARGET=http://somewhere
set PORT=5000
npm run proxy

On Linux and macOS:

TARGET=http://somehwere PORT=5000 npm run proxy

Now that we have explored the tooling, let's dive in with altering the pressure cycle example.

Open up two command shells and go to the directory of the example as described above for both of them. In the first window, issue npm run proxy, and in the second npm run watch. The second one is a command we haven't covered, and its purpose is to issue npm run build for any changes that are detected in src.

Create a new workspace and name it web_app_example. When a web app is run using a workspace, it will use the models and resources that are contained within it.

Open up a browser window or tab and go to http://127.0.0.1:3000/?workspaceId=web_app_example (given that you use the default PORT number). You should see the web app being served. Note that you need to specify the name of the workspace as the query parameter workspaceId. Click on the "Simulate"-button and wait for the result to show up in the bar graph.

The colors are nice but can be clearer. Open the file src/index.js and go to the color object on line 90:

const colors = {
  positive: "rgba(55, 128, 191, 0.7)",
  negative: "rgba(219, 64, 82, 0.7)"
};

Let's change the alpha values from 0.7 to 1.0:

const colors = {
  positive: "rgba(55, 128, 191, 1.0)",
  negative: "rgba(219, 64, 82, 1.0)"
};

Save and note when the window running watch is finished. Refresh the tab containing the web app and click on the "Simulate"-button to observe the changes.

Deploying a web-app🔗

Once you have decided you are ready to share your web app, you can go ahead and rename the dist folder to something appropriate. (Let's call it pressure-cycle2)

If you are running off a local installation, the deployment entails copying this folder to the customizations directory in the root of the installation directory. (E.g. C:/Users/<user_name>/impact/customizations.)

For a managed on-premise deployment, you archive the folder as a zip file and send it to the system administrator.

The web app is now available on the path /workspaces/web_app_example/customization/pressure-cycle2 for the workspace web_app_example. (E.g. http://127.0.0.1:8080/workspaces/web_app_example/customization/pressure-cycle2)

Web apps are accessible from the categorized Apps menu () on the toolbar. Apps can be organized under categories, which are defined in their 'src/metadata.json' file with the optional 'category' key.

If it is desired to load additional web apps from a location other than the default ('../impact/customizations') the environment variable 'IMPACT_EXTRA_CUSTOMIZATION_DIR' can be used to define an additional directory to search.