Skip to main content

Write tutorials

Definition

A tutorial is a collection of interactive materials that educate users about the platform. Such set of instructions can explain key concepts, such as viewers and filters, or illustrate certain workflows, e.g., how to access data or train a predictive model. A collection of tutorials on a specific topic is called a track.

Writing a tutorial

From a programmer's point of view, a tutorial is a class containing certain attributes as well as an event-based set of instructions. To start writing a tutorial in a package, we need to install @datagrok-libraries/tutorials.

The first step is to declare a subclass of Tutorial:

class CustomTutorial extends Tutorial {
// ...
}

Each tutorial should have name and description as well as an implementation of the _run method, where you should define a number of steps. Steps are the key units in every tutorial, and they correspond to the action method or helper methods calling it internally. Steps can come with interactive hints or more detailed description.

Registering a tutorial

Tutorials from outside the public Tutorials package should be registered. To do that, add a function to your package.ts file. It should have the tutorial tag and the meta.name parameter. As it should return a tutorial instance, the output type must be object. There are also optional parameters that you may use: meta.track specifies the track the tutorial belongs to; meta.icon contains the icon path relative to the package root; description contents are displayed in the UI.

import { CustomTutorial } from './tutorials/custom-tutorial';


//tags: tutorial
//meta.icon: images/custom-tutorial.png
//meta.name: Custom Tutorial
//meta.track: Test Track
//description: This tutorial illustrates a new feature
//output: object
export function registerTutorial() {
return new CustomTutorial();
}

Without a specified track, a tutorial is assigned to a new track created specially for the package. If an existing track is mentioned in the annotation, a tutorial is assigned to it. So, it's possible to extend a track from another package. If the meta.icon tag is absent, the default icon is used. If there is no description for the tutorial, it gets added with empty description.

It is also possible to register a track:

//tags: track
//help-url: https://datagrok.ai/help
//output: object
//meta.name: Test Track
export function registerTrack() {
return new Track('Test Track', [], 'https://datagrok.ai/help');
}

The function should have the track tag, parameters help-url and meta.name, and it should return a Track instance (marked as output: object in the function header).

Standard tutorials visibility

The Tutorials package provides a set of default tracks, such as Exploratory Data Analysis or Data Access. You can control their visibility on the user group level by applying relevant package settings.

See also: