@mock-monkey/ngx-onboarding-tour v0.0.2

Onboarding Tour Module

General project description

This module is built to display PopOvers on certain elements, based on a configuration file.\ It will show a background blur, elevate the selected element and draw the PopOver with the specified contents.\ See the rest of this README for specific information

Positioning

There are several possibilities regarding positions. \ The application will determine which position is best suited for the PopOver position.\ It will do so based on the global configuration (see config chapter) and specific specification (see step chapter)

The possible positions are displayed in the image below.

Note that:

• top spec includes all positions above the left-center and right-center positions
• bottom spec includes all positions below left-center and right-center positions
• left spec includes all positions left of top-center and bottom-center positions
• right spec includes all positions right of top-center and bottom-center positions

Please note that any configured (global or step) positions might be invalid.\ In that case the module will determine the best suitable alternative.

Installation and usage

The library only contains a forRoot method, which should be called in the root module of your project.\ As of this moment it requires two parameters and has a third optional parameter:

• tourChonfig: the configuration for the tour, containing chapters and steps (see tour configuration chapter (other configuration options))
  • required
• tourOptions: the configuration options for the tour (see configuration chapter (main))
  • required
• completedSteps: the steps that have been marked as completed, this is an array of hash values of steps.
  • optional

Configuration (main)

The following configuration options can be provided when bootstrapping the module, most of them are optional but have great influence on how the onboarding PopOver behaves.

  startStep?: {
    title: string,
    text: string
    allowPrevious?: boolean
  },
  continueStep?: {
    title: string,
    text: string,
    allowPrevious?: boolean
  }
  endStep?: {
    title: string,
    text: string,
    allowPrevious?: boolean
  },
  showFirstStepOnChapterReturn?: boolean,
  showChapterIntro?: boolean,
  showChapterOutro?: boolean,
  combineChapterIntroOutro?: boolean,
  trackIntroOutroSteps?: boolean,
  nextButtonText?: string,
  prevButtonText?: string,
  closeButtonText?: string,
  resizeDebounceTime?: number,
  preferredPosition?: Position,
  preferHorizontal?: boolean,
  preferDirect?: boolean,
  preferRight?: boolean,
  preferBottom?: boolean,
  disableScroll?: boolean,
  useProgressStorage?: boolean,
  progressCallback?: Function,
  imageBackgroundColor?: string
}

Start, end and continue steps

• startStep: when provided will be the introduction popover to the tour; this should give the user some information on what's about to happen.
  • note: no introduction will be given when this step was not provided. the user will start directly with the first available step.
• endStep: when provided will be the very last popover a user sees, upon finishing the full tour.
  • note: no ending will be given when this step was not provided. the user will be able to close the tour without any further information.
• continueStep: when provided will be the first popover a user sees upon returning to the application, skipping any finished steps and chapters before that.
  • note: no continue step will be given when this step was not provided. the user will start directly with the first available step.

Further configuration

Optional object property to display extra steps between chapters

• showFirstStepOnChapterReturn: determines wether the user is sent back to the first step of a chapter upon returning to the previous chapter.
  • note: a user will lose any progress on that entire chapter, should this be set to true
  • default: false
• showChapterIntro: determines whether the intros of chapters should be rendered as steps.
  • default: true
• showChapterOutro: determines whether the outros of chapters should be rendered as steps.
  • default: true
• combineChapterIntroOutro: if true it will send the user back to the very first step of the previous chapter when returning (previous) from an intermediate step
  • default: false
• trackIntroOutroSteps: if true it will include intro and outro step completion and returning in the progress of a chapter.
  • they will also be included in the total count regarding showing the finished step counter on regular steps.

Button texts

Optionally provide alternative texts for the buttons displayed in the PopOver.\ Will all default to English values if none are provided.

• nextButtonText: will be the text in the next button
  • default: next
• prevButtonText: will be the text in the next button
  • default: previous
• closeButtonText: will be the text in the next button
  • default: close

Other configuration options

• resizeDebounceTime: window resize events will be debounced by this time (ms)
  • default: 200
• preferedPosition: the position that would be preferred for any of the popovers.
  • no default
  • please keep in mind that this global configuration may be overwritten by specific configurations per step (see step configuration chapter)
• preferHorizontal: prefer horizontal positions to vertical positions (see positions chapter)
  • default: false
  • please keep in mind that this global configuration may be overwritten by specific configurations per step (see step configuration chapter)
• preferDirect: prefer direct (center) positions to indirect (non-center) positions (see positions chapter)
  • default: true
  • please keep in mind that this global configuration may be overwritten by specific configurations per step (see step configuration chapter)
• preferRight: prefer right positions to left positions (see positions chapter)
  • default: true
  • please keep in mind that this global configuration may be overwritten by specific configurations per step (see step configuration chapter)
• preferBottom: prefer bottom positions to top positions (see positions chapter)
  • default: true
  • please keep in mind that this global configuration may be overwritten by specific configurations per step (see step configuration chapter)
• disableScroll: will 'freeze' the page and disallow the user to scroll
  • default: true
  • please keep in mind that enabling scroll might have impact on performance as the PopOver will be repositioned with every scroll event, similar to window resize events.
• useProgressStorage: will store the progress of the user in the local storage
  • default: false
  • NO IMPLEMENTATION YET!
• progressCallback: a function that will be called when the user completes a step
  • default: void
  • result: event with the step and timestamp of completion.
• imageBackgroundColor: the background color of the image in the PopOver
  • default: #E9F4FB
  • please keep in mind that this global configuration may be overwritten by specific configurations per step (see step configuration chapter)

Tour configuration

The tour module was built on the premise that a tour contains multiple steps.\ For each individual step a PopOver will be generated.\ Steps can be divided over Chapters; a Chapter is a collection of one or more steps.

Chapter configuration

  chapterTitle: string,
  allowSkipping?: boolean,
  chapterIntro?: string,
  chapterOutro?: string,
  steps: Step[],

• chapterTitle: the title that will be displayed for the chapter
• allowSkipping: enables skipping entire chapters. adds a 'skip' button to chapter popOvers (intros)
  • NO IMPLEMENTATION YET!
• chapterIntro: the text that should be used as an introduction to a chapter
  • default: `Missing chapter introduction text'
• chapterOutro: the text that should be used as an outro to a chapter
  • default: `Missing chapter outro text
• steps: see next README chapter

Step configuration

  element: Element,
  title: string,
  description?: string,
  longDescription: string
  version?: number,
  trackable?: boolean,
  image?: {
    backgroundColor: string,
    path: string
  }
}

• element: see Element chapter in README
• title: the title to be displayed to the user in the PopOver for this particular step
• description: the (short) description to be displayed in the PopOver for this particular step
• longDescription: the lonnger description that can be displayed in the book
  • note: the book page has not been implemented yet.
• version: the version of the step configuration;
  • if the version changes and the user had previously completed the step it will be marked as uncompleted based on the version.
• trackable: if true the step will be included in the progress of the chapter
  • default: true
• image: optional object property to display an image in the PopOver
  • backgroundColor: optional property to the background color of the image
    • default: #E9F4FB
  • path: the path to the image

Element selection

  selector: string,
  type: 'class' | 'id' | 'custom',
  customType?: string,
  preferHorizontal?: boolean,
  preferDirect?: boolean
  preferredPosition: Position,
  locationUrl: string

• selector: the identifier for the chosen element (i.e.: classname or id)
• type: the type of selector; either class, id or custom
• customType (optional): the tag to be searched for (i.e.: data-tour-id)
  • only applies when type is marked as custom
• preferDirect (optional): prefer direct (center) positions to indirect (non-center) positions (see positions chapter)
  • default: true
  • please keep in mind that this will overwrite global configuration
• preferHorizontal (optional): prefer horizontal positions to vertical positions (see positions chapter)
  • default: false
  • please keep in mind that this will overwrite global configuration
• preferredPosition (optional): the position that would be preferred
  • tour module will try to apply this position but will fall back to another position if the PopOver will not fit.
  • must be one of the given positions
• locationUrl: the route of the page where the element presides.
  • note: this must be exact, including the initial prepending forward slash.

Missing features (TODO)

Short term:

• align the popOver style/design with UI/UX design
  • the implementation currently deviates from the design
  • mostly in the footer/button/progress area
• add a way to handle locationUrl more generic (id's, query parameters, etc.)
  • also update docs accordingly
• make project into a library/package.
• add a 'book' page, where all chapters are displayed on a single, scrollable, page.
  • this includes a (minimal) navigation
  • should have an option to get the menu items from the tour
  • should have an option to enable/disable navigation from tour module (i.e.: allow for custom navigation)

Long(er) term:

• add support for images in longDescription ('book' functionality)
  • descriptions for popOvers should not be impacted; no images or other content (such as bullet lists) should be included
• add button (and option to enable button) to open the full description from popOver
  • should navigate the user to the correct (sub)chapter on the book page
  • should allow the user to navigate back to the tour
• add a way to store tour progress internally, so one doesn't have to use the progressCallback and an own implementation
• add functionality to scroll to the given element when a page is larger than the browser window.
• move display (css) logic to css files
• add JSDoc to all files
• add a way to select elements by class (several) and highlighting all of them
  • include a way to choose which element should display the popOver
• add tests for all files
• add a way to mark progress on chapters as well (similar to how it's done for steps)
  • this includes events and such.
• add a way to skip entire chapters
  • this should result in them having to be completed at a later time (not marked as completed)
• add a way to enable developer mode
  • which should display errors and warnings
• add forFeature option to the module
• add support for different styling (styling object with properties for different colors)
• add a way to provide custom components, rather than the default ones

Recently completed:

• fix counter for steps
• fix next, previous and close buttons
• fix chapterSwitching correctly
• add step completion events (emit)
  • including a progresCallback function
  • excluding internal storage
• add a startStep to the tour (welcome step)
• add an endStep to the tour (goodbye step)
• add a way to navigate between routes to display the correct PopOver (based on locationUrl)
• add a way to receive a list (hash) of completed steps, so that the tour can 'hide' these.
• add a continueStep to the tour (welcome back step)
• add a way to add (animated) images to popOvers