Getting Started with the NavVis IVION Frontend API

Confirming your NavVis IVION Version

Procedure

On the NavVis IVION Instance dashboard, click the hamburger icon in the top left corner of your screen.
Click About in the bottom left corner of your screen.

The box that opens will show which version of NavVis IVION you are currently running.

Setting Up

Follow these steps to set up your development environment.

Procedure

Note: We recommend using a modular package management system and code bundler. We are using Node Package Manager (NPM) and Webpack as examples here.

Optionally, install a package manager and code bundler such as NPM and Webpack.
If you have installed NPM and Webpack, verify the installation by running:
```
$ npm -v

$ webpack -v
```
If NPM and Webpack are installed correctly, running these commands should return the version.
Optionally, download the scaffold project. The scaffold project package contains a simple TypeScript-based NodeJS application to help you get started.
Download the NavVis IVION Frontend API NPM package.

Place a copy of the NPM package into your project folder:

├── navvis-ivion-VERSION.tgz <---
├── package.json
├── src
│   ├── image
│   │   └── favicon.ico
│   ├── index.html
│   ├── index.scss
│   └── index.ts
├── tsconfig.json
└── webpack.config.js

If you are not using the scaffold project, add the NPM package to the project dependency by running:
```
  },
  "dependencies": {
    "@navvis/ivion": "file:navvis-ivion-VERSION.tgz"
  }
}
```
Note: Replace VERSION with the version number of the NPM package
Install dependencies by running:
```
$ npm install
```

Checking the Code

Procedure

Open ./src/index.ts in your code editor. You should see:

// index.ts
import "./index.scss";
import {getApi, ApiInterface} from "@navvis/ivion";

class TestApp
{
  public ivApi: ApiInterface;

  constructor()
  {
    getApi("https://iviondemo.iv.navvis.com/")
      .then((iv: ApiInterface) => {
        this.ivApi = iv;
        // Code added here will execute after NavVis IVION is completely loaded.
      })
  }
}

(<any>window).TestApp = new TestApp();

Initializing NavVis IVION

To initialize NavVis IVION, run:

getApi("https://iviondemo.iv.navvis.com/").then((iv: ApiInterface) => { /* run after IV loads. */ });

getApi(instanceUrl [, configuration]) instantiates NavVis IVION and returns a promise, which is used to run code after NavVis IVION is completely loaded.

The first argument of getApi() is the URL of your NavVis IVION instance.

The second, optional argument allows you to configure the behavior and appearance of NavVis IVION on startup. For example, if you want NavVis IVION to be in German, set the option to:

getApi("https://iviondemo.iv.navvis.com/", { "lang=de"}).then((iv: ApiInterface) => { /* run after IV loads. */ });

Embedding NavVis IVION

Procedure

Open ./src/index.html in your code editor. You should see:

<!DOCTYPE html>
<html>
<head>
  <title>IV API Testing App</title>
</head>
<body>
  <ivion></ivion>
</body>
</html>

The <ivion> tag is used by NavVis IVION to bootstrap and dynamically inject DOM elements and scripts into your application. This tag can be placed anywhere within your DOM structure.

Running the Application

Procedure

If you are using the scaffold project, run:

$ npm run serve

This will compile your code, start your default browser, and load the application.

Fetching Failed

If you receive an error similar to the following, your NavVis IVION instance is not reachable.

Verify that:
- The instance URL is correct.
- You have network access to the instance.

CORS Disabled

If you receive the following error, you have to revise your CORS security settings.

Go to Instance Settings > Instance Configuration.
Revise your CORS security settings.

FAQ

How can I confirm the version of NavVis IVION I am using?

To confirm your NavVis IVION version, click the hamburger icon on the dashboard, then select 'About' in the bottom left corner.

What package management system is recommended for setting up the development environment?

It is recommended to use a modular package management system like Node Package Manager (NPM) along with a code bundler like Webpack.

What should I do if I encounter a fetching error?

If you receive a fetching error, verify that the instance URL is correct and that you have network access to the instance.

Is it necessary to install NPM and Webpack?

While it is optional, installing NPM and Webpack is recommended for managing packages and bundling your code.

How do I initialize NavVis IVION in my application?

To initialize NavVis IVION, use the getApi function with the URL of your NavVis IVION instance.

Can I customize the language settings for NavVis IVION?

Yes, you can customize the language settings by passing an optional configuration argument to the getApi function.

What should I do if I receive a CORS error?

If you receive a CORS error, go to Instance Settings and revise your CORS security settings.

How do I run the application if I am using the scaffold project?

If you are using the scaffold project, run the command '$ npm run serve' to compile your code and start the application.