Layouts for Labs UI

You have a number of user interface layout options when designing your labs. Layouts are determined by the "uilayout" option in a lab’s index.json file under the "environment" key. Available layouts include:

NOTE: If your content requires learners editing files, please use the vscode-terminal-split layout, as it will best supports functionality such as “copy to editor” going forward.

You can try the layouts and discover additional functionality at https://katacoda.com/scenario-examples/courses/uilayouts.

Dashboard Tabs

Adding Dashboard tabs to a lab can improve the user experience by making commonly used websites, or ports, easily accessible. Interactive labs currently support three types of Dashboard tabs:

• Displaying External Webpages: This is useful when you require a link to an external service such as a cloud dashboard or documentation.
• Rendering a Proxied Port: When running a service on a port within the environment, the lab provides a dynamic URL for the session. This tab will automatically create the correct URL based on the port you want to display.
• Rendering a Proxied URL: Similar to “Rendering a Proxied Portal,” the "href" parameter supports the standard labs placeholder values, allowing you to direct users to a particular page within the service, running within the lab environment.

The index.json used to create the scenarios is shown in the following; it is important to remember to set the "showdashboard" variable:

"environment": {
    "showdashboard": true,
    "dashboards": [{"name": "URL", "href": "https://www.google.co.uk"},
        {"name": "Port 80", "port": 80},
        {"name": "Placeholder", "href": "https://[[HOST_SUBDOMAIN]]-80-[[KATACODA_HOST]].environments.katacoda.com"}]
}

Displaying Dashboard Tabs Inline with the Lab

By default, dashboard tabs will open in a new window. When combined with the layout terminal-iframe, the dashboard tabs can be embedded as an iframe. This allows the user to keep a consistent view and allow the steps to explain actions that need to be performed within the UI. For example, you would add something like the following to your index.json file:

"environment": {
    "showdashboard": true,
    "dashboards": [{"name": "URL", "href": "https://www.katacoda.com"},
        {"name": "Port 80", "port": 80},
        {"name": "Placeholder", "href": "https://[[HOST_SUBDOMAIN]]-80-[[KATACODA_HOST]].environments.katacoda.com"}],
    "uilayout": "terminal-iframe"
}

If the URL matches the iframe then links will automatically switch the user to the correct tab when they are selected, such as https://www.katacoda.com and https://134c80536b854c0b984b9af4f1ff1095-167772168-8080-ollie09.environments.katacoda.com

Note: This approach uses iframes, as such, websites such as Google will not load due to Browser Security and Google’s iframe configuration. Look in your browser’s console to view the errors.

Creating Additional Tabs

Certain scenarios will require multiple terminal tabs to be running. These can be opened dynamically using the labs markdown extensions, but they can also be opened when the scenario starts.

For example, the index.json shown here includes syntax that allows you to define an additional terminal tab:

"environment": {
  "terminals": [{"name": "Terminal 2", "target": "host01"}]
}

Automatically Run Commands in Tabs

These tabs can automatically run certain commands to help the user understand what is happening. The following command will open a new Terminal tab and automatically run a docker container stats command:

"environment": {
  "terminals": [{"name": "Docker Stats", "command": "docker container stats", "target": "host01"}]
}

These can be used for tasks such as watching an event stream, or viewing all the processes running on a system. You can also use the "command" option to run a shell script that you load as an asset. For example:

"environment": {
  "terminals": [{"name": "Docker Stats", "command": "scenario-setup-configuration", "target": "host01"}]
}

As a reminder, the script must be available in the PATH, e.g.:

"assets": {
  "host01": [
    {
        "file": "scenario-setup-configuration.sh",
        "target": "/usr/local/bin", "chmod": "+x"
    }
  ]
}

VS Code Layout Options

Many authors choose to provide learners with a VS Code environment. These environments have a few additional options that are described in the following sections.

Tabbed Based

If you wish to use VS Code as a separate tab, add the following to your index.json.

"environment": {
    "showide": true
}

An example can be found in the Scenario Examples. You can try this scenario on Katacoda.

Split Screen

If you wish to use VS Code as a split screen with the terminal, use the uilayout vscode-terminal-split, for example:

"environment": {
  "uilayout": "vscode-terminal-split"
}

An example can be found in the Scenario Examples. You can try this scenario on Katacoda.