Introduction 

CDAP is a big web application, with a lot of components. First time user going to the UI might get confused or overwhelmed with all the different options and the locations of the features they are interested in. A guided overview on different components will give users a quick overview of the UI, and reduce the ramp up time to use the system.

Goals

The goal for this project is to provide a framework to create a guided tooltip tour in CDAP. 

User Stories 

• User Tour Developer (Engineer) should be able to create a guided tooltip tour.
• User should be able to navigate to the next step of the tour.
• User should be able to exit from the tour at any time.
• User should not be prompted by the guided tour every time they start CDAP.
• User should be able to get focused to the important element during the tour.
  
  

Design

UI will be utilizing the framework Shepherd for the tooltip creation. 

Approach

Packaging

Shepherd does not work out of the box just by installing the project through yarn and importing the class. We will have to do a UMD packaging to make it work with CDAP UI project.

Shepherd open source project was just recently being picked up and actively maintained again. Long term solution is to discuss with Shepherd team and create a pull request to that project. However, since that may take some time, we are going to package the framework ourself and move towards the released library when the fix had been incorporated with the Shepherd project.

Focus Overlay

Shepherd does not have a built-in focus overlay for the target element for the tooltip tour. We will create a wrapper class that will expose this capability. 

The focus will be in the form of overlay that will darken other components besides the target element.

Steps:

1. Look for the element target.

2. Figure out the location and size of the element relative to the screen size.

3. Create 4 curtains overlay:

1. Left and right curtains will take the height of the element + some padding.

2. Left curtain will go from left of screen to the location of element - padding. Right curtain will go from right of screen to the end of width of element + padding.

3. Top and bottom curtains will have the width of the screen.

4. Top curtain will go from top of screen to the location of the element - padding.

5. Bottom curtain will go from bottom of the screen to the location of element + height + padding.

Saving User State

UI will save the state whether user have gone through the tour or not in User Store. 

note: Backend work for new key-value user store is still pending. If the new key-value store does not come in time, then we will use the old blob user store.

API

Tour Creation

To create a tour, user have to define an array of the tour steps.

Each step is an object. Full Shepherd API documentation: https://shipshapecode.github.io/shepherd/

{
  id: 'stepId',
  attachTo: '#navbar-brand',
  title: 'Welcome to CDAP',
  text: 'Some explanation about CDAP capability. This text will be in the body of the tooltip',
  buttons: [
    {
      text: 'Custom Button Text',
      action: () => {
        '...some custom function'
      }
    }
  ],
  *shouldFocus: true || false,
  when: {
    // Lifecycle events 
    'before-show': () => { }, 
    'show',
    'before-hide',
    'hide',
    'destroy',
    'complete',
    'cancel',
  }
}

* additional property exposed by CDAP Shepherd wrapper class

Test Scenarios (TBD)

Future work

• Add Packaging PR to Shepherd project
• Create more tutorials / guided tour for different CDAP sections.