Nativescript Copilot

Step-by-step walkthrough for your Nativescript app!

Inspired by the awesome React Native Copilot plugin

Nativescript-Copilot is a component that is currently only suitable for NativeScript-Vue. If you'd like to see a Nativescript-Core or Nativescript-Angular implementation, then please submit a PR.

Quick Start - Vue

npm install --save @nativescript-copilot/vue

Main entry point

import Copilot from '@nativescript-copilot/vue';
Vue.use(Copilot)

Nativescript-Vue Usage

This can be used on a Page by Page basis. The primary way the tour is driven is by passing in a ref for each step. For example below, we have a ref named step1 in the Image component.

  <StackLayout col="0" verticalAlignment="bottom" horizontalAlignment="left">
    <Image ref="step1" src="~/assets/logo.png" height="75%" width="75%" borderWidth="1"/>
  </StackLayout>

You can combine multiple refs to create a tour. You will need to create an object array that carries the config for the tour for a particular page. For example:

      this.steps = [
        {
          name: 'First',
          text: 'here is some text',
          order: 1,
          target: this.$refs.step1.nativeView,
          animated: true,
          isFirstStep: true
        },
        {
          name: 'Second',
          text: 'here is some text with a rounded highlighted zone and padding',
          order: 2,
          target: this.$refs.step2.nativeView,
          animated: true,
          highlightBorderRadius: 10,
          highlighPadding: 5,
        },
        {
          name: 'Third',
          text: 'here is some text that should hopefully be long enought to cause a wrap.  What will happen if the text is too long. Find out!',
          order: 3,
          target: this.$refs.step3.nativeView,
          animated: true
        },
        {
          name: 'Fourth',
          text: 'This has a veritcal offset of -5 which will push the step 5dp towards the top',
          order: 4,
          target: this.$refs.step4.nativeView,
          animated: false,
          verticalOffset: -5,
        },
        {
          name: 'Fifth',
          text: '',
          order: 4,
          target: this.$refs.step3.nativeView,
          animated: false,
          isCustom: true,
          itemTemplate: '<Label text="This is a custom template!" color="green"/>',
          customBackgroundColor: 'black',
          customBorderRadius: '15',
          numberAccentColor: 'white',
          numberBackgroundColor: 'green',
           customTooltipStyle:  {
            fontFamily: 'Avenir-Bold',
            tooltipFontSize: 12,
            tooltipTextColor: 'white',
            buttonFontSize: 12,
            accentColor: 'white'
          },
          customLabels: {
            skip: 'Stop',
            previous: 'Before',
            next: 'Continue',
            finish: 'Done'
          }
        },
        {
          name: 'Sixth',
          text: 'This will darken the whole page and center the tool tip',
          order: 4,
          target: this.$refs.step4.nativeView,
          animated: false,
          darkenWholePage: true,
          isLastStep: true
        }
      ]

There are several configuration items in a Step object:

Name	Type	Description
name	string	Purely for decoration/organizational purposes
text	string	The descriptive text to display in the tooltip
order	number	which step this is in the page's tour
target	string	the specific component that you want the tour to stop at. This must be in the format of this.$refs.step1.nativeView where step1 is the name of the actual ref
animated	boolean	Default is true, but if you don't want a step to animate to the next step, then set this and it will jump to the next location without any animation
verticalOffset	number	Use in case you need to vertically offset the area highlighted by the step. This can be a positive or negative number
isFirstStep	boolean	Used to tell the plugin which step is first so that it will hide the Previous button
isLastStep	boolean	Used to tell the plugin which step is last so that it will hide the Next button and show the 'Finish' button
isLastStep	boolean	Used to tell the plugin which step is last so that it will hide the Next button and show the 'Finish' button
darkenWholePage	boolean	Used to tell the plugin if a step has no highlighted value, to darken the whole screen, and center the text box vertically and horizontally
showNumber	boolean	Use in the case of not wanting to show the step number on a specific step
numberBackgroundColor	string	Used in the case of wanting a custom number background color on a specific step
numberAccentColor	string	Used in the case of wanting a custom number accent color on a specific step
customBackgroundColor	string	Use in the case of wanting a custom background tool tip color on a specific step
customBorderRadius	string	Use in the case of wanting a custom border radius for the tool tip on a specific step
highlightPadding	number	Use in the case of wanting a custom padding on the highlightedzone of the mask
highlightBorderRadius	number	Use in the case of wanting a custom border radius on the highlightedzone of the mask on a specific step (Warning: when using border radius, with how this plugin functions, having too high of a border radius / too high of a border radius near the edge of the device will cause IOS UI to misfunction, it is suggested to descrease your border radius) (Note: using border radius will decrease your highlighted area, use padding to increase it again)
isCustom	boolean	Use in the case of wanting a customized tool tip, along with the itemTemplate option
itemTemplate	string	Used if custom component is true on the step, pass in a string value of XML ( events and dynamic props do not work )
customTooltipStyle	object	Used in the case of wanting a custom style for the tool tip on a specific step
customLabels	object	Used in the case of wanting a custom style for the tool tip on a specific step

You will then pass the step config into the Copilot component as the steps prop. In the example below, we are using a computed property to feed the steps prop:

  <Copilot
    :steps="computedSteps"
    :animationDuration="animationDuration"
    :labels="labels"
    :tooltipStyle="tooltipStyle"
    :overlayColor="overlayColor"
    :backgroundColor="backgroundColor"
    :accentColor="accentColor"
    ref="copilot"
  />

There are several other props that can be passed into the Copilot component. They are:

Name	Type	Default	Description
animationDuration	string	300	Number of ms the animation will take to move to the next step
labels	object	{ skip: 'Skip', next: 'Next', previous: 'Previous', finish: 'Finish' }	The names of the four buttons used in the toolsip to move between tour steps. Skip will end the tour at any step while Finish will only end at the very last step.
tooltipStyle	object	{ fontFamily: Avenir-Light, tooltipFontSize: 14, tooltipTextColor: 'black', buttonFontSize: 14, accentColor: 'green' }	Used to control the overall apperance of the tooltip
overlayColor	string	rgba(0, 0, 0, 0.4)	Used to control the overlay color
numberBackgroundColor	string	white	Used to set the default number background color
numberAccentColor	string	green	Used to set the default number accent color
toolTipBackgroundColor	string	white	Used to set the default tool tip background color
toolTipBorderRadius	string	'3'	Used to set the default tool tip border radius
highlightBorderRadius	number	0	Used to set the default highlight border radius on the mask (Warning: when using border radius, with how this plugin functions, having too high of a border radius / too high of a border radius near the edge of the device will cause IOS UI to misfunction, it is suggested to descrease your border radius) (Note: using border radius will decrease your highlighted area, use padding to increase it again)
highlightPadding	number	5	Used to set the default highlight padding on the mask

An initialization example of the above options (done in typescript):

private animationDuration: number = 300;
private androidStatusBarVisible: boolean = false;
private labels: object = {
  skip: 'Skip',
  previous: 'Previous',
  next: 'Next',
  finish: 'Finish'
};
private tooltipStyle: object = {
  fontFamily: 'Avenir-Light',
  tooltipFontSize: 14,
  tooltipTextColor: 'black',
  buttonFontSize: 14,
  accentColor: 'green'
}
private overlayColor: string = 'rgba(0, 0, 0, 0.4)';
private numberAccentColor: string = 'green';
private numberBackgroundColor: string = 'white';
private toolTipBackgroundColor: string = 'white';
private toolTipBorderRadius: string = '3';
private highlightPadding: number = 5;
private highlightBorderRadius: number = 10;

There are several events emitted by the Copilot component:

Name	Type	Description
step-change	object	Emitted when a step progresses forward or backward, emits an object containing stepLeaving and stepArriving
stop	--	Emitted when the copilot is stopped
start	--	Emitted when the copilot is started
not-ready	--	Emitted when the copilot receives an invalid layout
highlight-tap	--	Emitted when the copilot's highlightedzone is tapped

You will call the event from the Copilot component as the name of the chosen event. In the example below, we are calling a function on the event:

  <Copilot
    :steps="computedSteps"
    @step-change="stepChanged"
    @stop="copilotStopped"
    @not-ready="copilotNotReady"
    @start="copilotStarted"
    @highlight-tap="copilotHighlightTap"
    ref="copilot"
  />

To start a tour on a particular page you will need to call the Copilot start function. An example of this is: this.$refs.copilot.start();

Vue Demo project

Take a look at the demo project for a simplistic project that implements this plugin with many of the options discussed above.