User Tour

Beachfront User Tour

The user tour in Beachfront is intended to give a new user a basic introduction to the Beachfront user interface and product capabilities. It mostly follows a similar path to that described in the Beachfront User's Guide. Start the tour by clicking on the tour bus icon in the navigation sidebar. Once you start the tour, you cannot interact directly with the application until you close the tour. This prevents the user from changing the state of the application in such a way that the tour no longer knows how to proceed.

Implementation

The NPM module, react-user-tour, is used for the basic framework for the tour. It handles the basic rendering of the dialog boxes, including positioning around the current active element and basic navigation from step to step. This module is very basic, but does have the basic API hooks required to change application state as the user navigates from step to step.

One goal when implementing this tour is to impact the actual application code as little as possible. Most of the code is contained in two files:

• src/components/Tour.tsx
• src/components/Tour.css

There is some code in src/components/Application.tsx and src/components/Navigation.tsx to load and start the tour.

The central React component to the tour is <UserTour/> with one required property, application, providing access to the central Beachfront <Application/> component.

The steps in the tour are hard-coded in src/components/Tour.tsx as an attribute of the <UserTour/> component. Most of the properties of each step are used as described in the react-user-tour documentation, however, I have made a few additions:

• hideArrow — (optional) A boolean value indicating if the arrow should be hidden. Defaults to false.
• before — (optional) A function returning a promise that will be executed and resolved before the tour moves into this state.
• after — (optional) A function returning a promise that will be executed and resolved after the tour moves from this state and before moving to the next state.

State changes are executed using the gotoStep(n: number): Promise<any> function where n is the number of the step being entered. Returned is a promise that is resolved after:

1. The after function for the step being exited is executed and its promise resolved.
2. The before function for the step being entered is executed and its promise resolved.
3. The element specified by the selector property of the step is scrolled into view, if necessary.

The above actions occur synchronously in the prescribed sequence.

Configuration

Various values used in the tour are read from the configuration file, src/config.ts. Here is what it looks like as of this writing:

export const TOUR = {
  algorithm: ':nth-child(3)',
  /*
  apiKeyInstructions: `
    To get an API key, ask the experts at <a
      href="https://rocketchat.gs.mil/channel/planetdas_askanexpert"
      target="_blank"
    >Rocket.Chat #planetdas_askanexpert</a>.
  `,
  */
  apiKeyInstructions: `
    To get an API key you must have a Planet account.  For more information see <a
      href="https://support.planet.com/hc/en-us/articles/212318178-What-is-my-API-key-"
      target="_blank"
    >What Is My API Key?</a>
  `,
  basemap: 'OSM',
  bbox: [-85, 19.7, -74, 23.4],
  bboxName: 'Cuba',
  searchCriteria: {
    cloudCover: 8,
    dateFrom: '2017-07-01',
    dateTo: '2017-10-31',
    source: 'landsat',
  },
  zoom: 6,
}

• algorithm — (required) Which algorithm to use in the list of compatible algorithms for running the job. There is nothing in the DOM structure that I can use to identify an algorithm, so this value should be a pseudo-selector like :first-child, :last-child, or :nth-child(2).
• apiKeyInstructions — (required) Instructions on how to get an API key. This will be displayed inside a <div/> element.
• basemap — (required) Which basemap will be used for the tour.
• bbox — (required) What boundary box will be drawn and used to search for imagery. The center of this box is used when shifting the map to the area of interest.
• bboxName — (required) A human name for the geographical area highlighted by the boundary box.
• searchCriteria — (required) All the search criteria used to search for imagery.
• zoom — (required) The zoom level used when shifting the map to the area of interest. The values used should be sufficient to contain the bounding box in its entirety.