Custom layouts & themes

Learn how to enable, and customise your lab layouts and themes. Custom layouts help you create a tailored lab experience for your product.

This feature, alongside the new lab look is currently in beta. Please reach out to your Instruqt representative to learn how to enable this feature.

What are Custom Layouts

Custom layouts allow you to customise the tab panels of a lab for an entire play, or customise the layout of each individual challenge for a more tailored experience.

A lab set up with custom layouts.

In the screen shot above, we show a lab with custom layouts enabled. Users entering the lab will all have this layout by default.

How to enable custom layouts

You can enable custom layouts and theming in both the web application and with our CLI. Enable the Lab V2 flag on a track level, to experiment and validate without having to convert all your labs, for a smoother migration story. Note that enabling custom layouts will also enable our new lab styling.

Web

You can enable the early access Lab V2 toggle. You can find the switch on the right side of the track dashboard, under "Layout & Theming".

CLI

# track.yml
...
lab_config:
  lab_v2: true
...

To enable the Lab V2 feature for a track, you can configure the lab_config root level object, and set the lab_v2 flag to true

How to configure custom layouts

The Web UI will give you a visual layout editor, while the CLI will use serialised output that uses Dockview under the hood, so you can refer to their docs for the layout, if you prefer to manage your labs this way.

Web

1. After enabling the Lab V2 beta, you can create your custom layouts from the same Layout & Theming widget on the sidebar of a track dashboard.

2. Click the Edit button next to the Layout label.

The Layout configuration page.

Choosing a layout for all challenges in your track.

3. If you want to have the same, simple layout for your lab, simply enable on the Use track layout for all challenges toggle on the layout landing page. You now have useful default layouts that should easily fit most use cases.

4. Save changes, and you're done! Your lab should now be using the default layout for each of your challenges.

Customising layouts for individual challenges.

3. Select the challenge you want to customise and drag-and-drop tabs to your desired outcome.

4. Save your changes, and you're done! The challenge should now be reflecting the specific layout you have designed for the challenge.

You can customise each challenge to best fit your product and how you design your content.

CLI

Customise the layout for the whole track

Open up your track.yml file, under the lab_config options you can configure the default_layout option, and toggle override_challenge_layout to true, configuring the layout for the entire lab.

# track.yml
...
lab_config:
  lab_v2: true
  theme:
    name: modern-dark
  override_challenge_layout: false
  default_layout: AssignmentLeft
...

Layout API for lab_config

Field	Options	Description
lab_v2	true or false	enables the new lab style and custom layouts.
theme.name	modern-dark or original	These two options are the only current themes available. A modern take on the Instruqt lab, and the classic original colour scheme.
override_challenge_layout	true or false	Tells Instruqt to use the default track layout for your lab. And overrides any custom layouts you have enabled for any challenge.
default_layout	AssignmentRight, AssignmentLeft, or AssignmentBottom	Selects which default layout you would like to have for a track.

Customise layout for an individual challenge

You can also manage the individual, custom layouts as code, by adding a serialised string of the Dockview state. You can explore the interface here.

# <challenge_slug>/assignment.md frontmatter block
...
lab_config:
  custom_layout: '{"root":{"children":[{"branch":{"children":[{"leaf":{"tabs":["assignment"],"activeTabId":"assignment","size":50}},{"leaf":{"tabs":["feedback"],"activeTabId":"feedback","size":50}}],"size":49}},{"leaf":{"tabs":["xpbbhgg2ilnm","vcly1o5zid56","jvcbfq9tblpa","zaw51ozikez1","dmyxy9cxga73"],"activeTabId":"xpbbhgg2ilnm","size":50}}],"orientation":"Horizontal"}}'
...

Themes

ModernDark	Original

Web

1. Enable Lab V2 for the track.

2. In the Layout & Theming widget select between the ModernDark theme and the Original colour scheme.

   

   Available themes.

3. The track will now use the selected theme for all plays.

CLI

Refer to the How to configure layouts and check the API here.