Skip to content

Latest commit

 

History

History
133 lines (96 loc) · 4.49 KB

INTRODUCTION.md

File metadata and controls

133 lines (96 loc) · 4.49 KB

Webviz introduction

Fundamental configuration

A configuration consists of some mandatory properties, e.g. app title, and one or more pages. A page has a title and some content. Each page can contain as many plugins as you want.

Plugins represent predefined content, which can take one or more arguments. Lists and descriptions of installed plugins can be found on the other subpages.

Content which is not plugins is interpreted as text paragraphs.

A simple example configuration:

# This is a webviz configuration file example.
# The configuration files use the YAML standard (https://en.wikipedia.org/wiki/YAML).

title: Reek Webviz Demonstration

pages:

 - title: Front page
   content:
    - BannerImage:
        image: ./example_banner.png
        title: My banner image
    - Webviz created from a configuration file.

 - title: Markdown example
   content:
    - Markdown:
        markdown_file: ./example-markdown.md

Command line usage

Get documentation

You can always run webviz --help to see available command line options. To see command line options on a subcommand, run e.g. webviz build --help.

📚 To open the webviz documentation on all installed plugins, run webviz docs.

Portable vs. non-portable

Assuming you have a configuration file your_config.yml, there are two main usages of webviz:

webviz build your_config.yml

and

webviz build your_config.yml --portable ./some_output_folder
python ./some_output_folder/webviz_app.py

Portable

The portable way is useful when one or more plugins included in the configuration need to do some time-consuming data aggregation on their own, before presenting it to the user. The time-consuming part will then be done in the build step, and you can run your created application as many time as you want afterwards, with as little waiting time as possible.

The --portable way also has the benefit of creating a 🐳 Docker setup for your application - ready to be deployed to e.g. a cloud provider.

Non-portable

Non-portable is the easiest way if none of the plugins have time-consuming data aggregration to do.

A feature in Dash, used by webviz is hot reload. When the Dash Python code file is saved, the content seen in the web browser is automatically reloaded (no need for localhost server restart). This feature is passed on to the Webviz configuration utility, meaning that if you run

webviz build ./examples/basic_example.yaml

and then modify ./examples/basic_example.yaml while the Webviz application is still running, a hot reload will occur.

Localhost HSTS

Previous versions of webviz generated a local certificate to force localhost connections to go through HTTPS. This is no longer the case and localhost connections use HTTP. As such, the webviz certificate command has been deprecated.

Some browsers will force HTTPS and require extra steps to remove this security. Note that this is safe as no external computer may connect to a localhost server.

If you're having issues connecting to a localhost server running Webviz due to security issues, perform the following steps:

Google Chrome and Chromium

These are the steps to remove HSTS, a security feature that forces HTTPS connections even though the user has specified HTTP:

  1. Navigate to chrome://net-internals/#hsts
  2. In the Delete domain security policies, type in "localhost" and click delete
Firefox

Firefox does not have issues connecting to localhost addresses over HTTP.

User preferences

You can set preferred 🌈 theme and/or 🌍 browser, such that webviz remembers it for later runs. E.g.

webviz preferences --theme equinor --browser firefox

YAML schema

By running webviz schema you will get a YAML (or technically, a JSON) schema which you can use in text editors, which then will help you with auto-completion, detect mistakes immediately, and get hover description on different plugins.

If you are using Visual Studio Code, we recommend Red Hat's YAML extension. After installing the extension, and adding something like

{
  ...
  "yaml.schemas": { "file:///some/path/to/your/webviz_schema.json": ["*webviz*.yml", "*webviz*.yaml"]}
}

to your settings.json file, you will get help from the editor on YAML files following the namepatterns to the right (might have to restart the editor after updating the settings).