Visualization Onboarding

This repository proposes a technical approach for the semi-automated creation of onboarding elements for different visualization types and data sets. We demonstrate the approach using three well-known high-level descriptive visualization grammars (Vega-Lite, Plotly.js, and ECharts) to extract and describe visualization onboarding instructions and show the feasibility by the example of a bar chart, a horizon graph, and a change matrix. We provide a demo for each visualization type in all three charting libraries.

Docs

Getting started

Derieve automatically generated onboarding messages

Our library provides two main functions which can be used to create and add the onboarding to your visualization. The function generateBasicAnnotations allows you to get the automatically generated onboarding messages for your chart type

CHART_TYPE: defines the type of chart for which you want to get the onboarding messages for. We support all charttypes which are contained in the enum EVisualizationType.

CHART: Pass the runtime object of your visualization as the second parameter to this funcition.

RETURN VALUE: The funciton returns an array of OnboardingMessages

EXAMPLE: import { generateBasicAnnotations, EVisualizationType } from '@visahoi/plotly';
const defaultOnboardingMessages = generateBasicAnnotations(EVisualizationType.BAR_CHART, chart)

Customize the default onboarding messages

As you got the automatically generated onboarding messages for your cart type now, you can freely customize them. You could interate over the array and customize the text, add new items or remove some which you don't need. For newly added items consider that they need to match the IOnboardingMessage interface.

Create the onboarding

When you're done customizing your onboarding messages, it's time to create the onboarding interface for your visualization. To do that, call our ahoi(CHART_TYPE, CHART, CONFIG) method.

CHART_TYPE: EVisualizationType

CHART: Pass the runtime object of your visualization

CONFIG: The config object contains all configuration necessary to customize the onboarding, including the onboarding messages. See the interface IAhoiConfig

• onboardingMessages: IOnboardingMessage[];
• backdrop: IBackdropConfig;

EXAMPLE: const onboardingUI = await ahoi(EVisualizationType.BAR_CHART, chart, ahoiConfig);

Customizations via the onboarding messages

Marker

• Radius (optional)
• Font size (optional)
• Content (optional, default: index)

Tooltip position

Onboarding stages

• title
• iconClass
• backgroundColor
• hoverBackgroundColor (optional)
• activeBackgroundColor (optional)
• order

Message title

Message text

Remove the onboarding

To remove the onboarding again, call removeOnboarding on the onboardnig instance.

EXAMPLE: onboardingUI?.removeOnboarding();