Guided tours

[ignapas]

After the first POCs were implemented for oSPARC and the Postpro/Analysis service (PAS from now on) and a first meeting with @cosfor1, a new preliminary set of requirements can be defined. Requirements are different for oSPARC and PAS, so the implementations for both apps can be different. It is still to be decided what to do and when, to be discussed with @odeimaiz, @mguidon and @cosfor1.

Related to #931

Types of guided tours

For the moment we identified two possible types of tours:

Self-triggering tours

These are tours that are started spontaneously after some user action. Some examples of these kind of tours and what they could show to the user:

• A user logs in for the first time
  • oSPARC
  • Identifies the different parts of the UI, in a general way
  • Makes it clear for the user what is the dynamic service's iframe (that could be maximized) and its own menus (top bar, iframe's maximize and reload buttons, etc.)
  • PAS
  • Identifies the different parts of the UI, in a general way
  • Guides the user on what could be a first simple simulation and postpro setup
• PAS: A user fails to drop an item (drag and drop interaction) on the correct element of the tree (could be triggered by the frontend only)
  • Gets instructed about where to drop it correctly (for ex.: model entities are normally dropped on the materials group)
• PAS: A hint after some more complex condition is met. Examples:
  • After a user creates a new sensor extractor, the outputs sections is explained
  • After two model entities are selected, the user is made aware about the boolean operations that became available

The majority of these tours are triggered by the backend, which also needs to remember if they have been shown and/or dismissed already, not to show them again.

On-demand tours

The user wants to learn about some specific feature of the app for which a tour is available. Examples:

• A tour about how to set up a new FDTD simulation
• A tour on how to use expressions
• A tour about setting up a grid and voxeling
• etc.

These tours are actively searched by the user to learn the app's features and need to be easily accessible for relaunching.

Both types of tours are not mutually exclusive, a tour could be triggered by the server but still be available for the user to run it again.

Implementation

As a result of the requirements captured so far, a first implementation is proposed

UI

Tour steps

• Have a title, text, progress, skip tour button, previous button and next button
• They are attached to the UI element(s?) they describe or are rendered in the center of the screen (general step)
• They can orient themselves with respect to the highlighted item (top, right, bottom, left)
• Auto-clicking. Each step can define an element (or sequence of elements?) that get automatically clicked by the framework to get the interface into the correct state. "beforeClicks" and "afterClicks" can be defined for when the tour enters a step (from the previous step clicking the next button) or leaves it (from the current step's next button).
• Advancing through a guided tour with auto-clicking could get the interface into a state where showing a previous step no longer makes sense or is just impossible. For these cases we need to add the possibility to revert the clicks. The same way we define a sequence of clicks before going to the next step, we define another sequence to revert those clicks to go back to the same state as before.
• Another option for changing the UI's state while navigating between states is to instruct the user to make the clicks. In this case the step's text needs to ask the user to click somewhere and the framework needs to detect the click to automatically advance to the next step. This is possible when only one click is needed.
• Only one clicking strategy is chosen and implemented.

Highlighting

• The highlighted item stands out by dimming the rest of the interface.
• The rest of the interface gets blocked from user interactions.

Guided tours catalog

For the user to browse and launch (or relaunch) tours, a view is created where the tours are displayed. The view has search functionality and shows a list of available tours, with a title and description. Could be useful to have it categorised.

Client-server communication

There are two moments where client and server could have to communicate:

• Start of the tour
  • Server wants the client to start a tour (self triggering tours)
  • Client informs the server that the user wants to start a tour. For example, the server might need to load a project before the tour starts.
• End of the tour
  • The client informs the server that the user went through a tour or that the tour was skipped. This can be used to flag the tour as "done", to not trigger it again.

Definition files

Proposed model

type AllTours = {
  [id]: GuidedTour
}

type GuidedTour = {
  id: string,
  title?: string,
  description?: string, // Title and description are needed when showInCatalog = true
  showInCatalog?: boolean = false,
  notifyStart?: boolean = false,
  notifyCompleted?: boolean = false, // Should the client notify the server upon starting/completing a tour?
  steps: Step[]
}

type Step = {
  title?: string,
  text: string,
  anchorEl?: string, // CSS selector. The step follows this element in the UI. If undefined, the step is centered in the screen
  highlightedEl?: string | string[], // CSS selector. The items to highlight, it defaults to the anchorEl
  blockUI?: boolean = true,
  placement?: 'top' | 'right' | 'bottom' | 'left' = 'bottom'
  beforeClick?: ClickSequence,
  afterClick?: ClickSequence
}

type ClickSequence = {
  selector: string | string[], // CSS selector
  revertSequence?: string | string[] // CSS selector
}

[ignapas]

For planning meeting (just ideas for discussion)

• Main problem is, tours need to be remembered mainly per user, then per service and optionally per version. This means tour persistence (already run / skipped) lives in oSPARC's DB.
• On the other hand, the tours themselves are highly dependent on UI (using CSS selector to highlight items) and on the specific version of the service, so it makes sense that they live in the service.
• For that reason some sort of common interface needs to be defined. The same way the service defines that it has the "screenshots" feature implemented, it also defines that it has "guided tours". That allows and instructs oSPARC to tell the service which tours were already finished for that user and service, when it starts, and also tells it where to communicate new tours finishing.
• The tours themselves (definition file) live in the service and are updated as the UI evolves. When a tour finishes, Rocket informs Python server which informs oSPARC (for PAS).
• What's new tours. When the user starts a new version, a tour showcases the new features of that version. For this the back-end would need to remember the last opened version. Then, if there are any "what's new" tours between that version and the current one, the last one is started.
• Front-end still needs to adapt to specification.
• Tour catalog?

[mguidon]

@ignapas After discussion with @sanderegg and @GitHK we decided to have a way to pass user based json data from/to the db via a file in a volume mount. That will allow us to bi-directionally talk with the db through the sidecar.