How to use the navigator API in your e-Detailers

Overview

The navigator module ensures navigation in e-Detailers and surveys. Navіgation means transition between slides, subslides, and chapters when you swipe the slides. Use the settings.json file to define the navigation settings.

The navigator module includes the transition hooks that activate certain transition effects, animation, CSS, and other actions when you enter or leave a slide.

The navigator module uses the standard slide demonstration flow defined in the structure.json file. You can create a new demonstration flow dynamically while viewing an e-Detailer.

The navіgation instance is bound to the instance of Vue as $navigator. You have access to the navigator API and its methods via this context on a slide.

this.$navigator

The navigator API has the following methods for navigating to the specific slides in your e-Detailer.

goTo

The goTo method opens the slide that you define in the options parameter for this method. You can call this API method on any slide of your e-Detailer using this context.

this.$navigator.goTo(options, force);

The options parameter is required. The force parameter is optional.

Parameters of goTo

The goTo method has the following parameters.

• options (Object) is the required parameter that includes the following fields: — slide (String) specifies the ID of the slide to navigate. — chapter (String) specifies the ID of the chapter to which the slide belongs. — presentation (String) specifies the ID of the e-Detailer to navigate; available only in the iRep and Viseven CLM builds. For Viseven CLM, specify the e-Detailer id as the presentation field value. For example, presentation: "my-edetailer". See e-Detailer settings for Viseven CLM. — animation (Boolean) defines if the slide's transition animation is played during the navіgation (true) or skipped (false). Defaults to true.

• force (Boolean) is the optional parameter. Specifies if the navіgation lock is ignored. Defaults to false.

TIP: The force option can be useful if the navіgation to the neighboring slide is locked but you still need to execute the navіgation to this slide.

Usage of goTo

To use the goTo method on a slide, add this code to your slide instance.

<!-- ./slides/goTo/index.vue -->
<template>
<div class="layout">
<button @click="goToLastSlide">Go to the last slide</button>
</div>
</template>

// ./slides/goTo/index.vue
export default {
methods: {
goToLastSlide() {
const options = {
slide: "outsideClick",
chapter: "actions",
animation: true
};
this.$navigator.goTo(options);
},
},
};

This code adds the HTML button to your slide. Click the Go to the last slide button on the slide to call the goTo method. The method executes navіgation to the slide that you define in the options parameter.

goToNextSlide

The goToNextSlide method opens the next slide of your e-Detailer. If the subslide option is set to true, the next subslide opens. You can call this API method on any slide of your e-Detailer using this context.

this.$navigator.goToNextSlide(force, { subslide: true })

The force and subslide parameters are optional.

Parameters of goToNextSlide

The goToNextSlide method has the following parameters.

• force (Boolean) is the optional parameter. Specifies if the navіgation lock is ignored. Defaults to false.

TIP: The force option can be useful if the navіgation to the neighboring slide is locked but you still need to execute the navіgation to this slide.

• subslide (Object) is the optional parameter. If the subslide option is set to true, the next subslide opens. Defaults to true.

Usage of goToNextSlide

To use the goToNextSlide method on a slide, add this code to your slide instance.

<!-- ./slides/goTo/index.vue -->
<template>
<div class="layout">
<button @click="goToNextSlide">Go to the next slide</button>
</div>
</template>

// ./slides/goTo/index.vue
export default {
methods: {
goToNextSlide() {
this.$navigator.goToNextSlide();
},
},
};

This code adds the HTML button to your slide. Click the Go to the next slide button on the slide to call the goToNextSlide method. The method executes navіgation to the next slide of your e-Detailer.

goToPrevSlide

The goToPrevSlide method opens the previous slide of your e-Detailer. If the subslide option is set to true, the previous subslide opens. You can call this API method on any slide of your e-Detailer using this context.

this.$navigator.goToPrevSlide(force, { subslide: true })

The force and subslide parameters are optional.

Parameters of goToPrevSlide

The goToPrevSlide method has the following parameters.

• force (Boolean) is the optional parameter. Specifies if the navіgation lock is ignored. Defaults to false.

TIP: The force option can be useful if the navіgation to the neighboring slide is locked but you still need to execute the navіgation to this slide.

• subslide (Object) is the optional parameter. If the subslide option is set to true, the previous subslide opens. Defaults to true.

Usage of goToPrevSlide

To use the goToPrevSlide method on a slide, add this code to your slide instance.

<!-- ./slides/open/index.vue -->
<template>
<div class="layout">
<button @click="goToPreviousSlide">Go to the previous slide</button>
</div>
</template>

// ./slides/open/index.vue
export default {
methods: {
goToPreviousSlide() {
this.$navigator.goToPrevSlide();
},
},
};

This code adds the HTML button to your slide. Click the Go to the previous slide button on the slide to call the goToPrevSlide method. The method executes navіgation to the previous slide of your e-Detailer.

goToNextChapter

The goToNextChapter method opens the next chapter of your e-Detailer. You can call this API method on any slide of your e-Detailer using this context.

this.$navigator.goToNextChapter(force)

The force (Boolean) is the optional parameter. It specifies if the navіgation lock is ignored. Defaults to false.

TIP: The force option can be useful if the navіgation to the neighboring slide is locked but you still need to execute the navіgation to this slide.

Usage of goToNextChapter

To use the goToNextChapter method on a slide, add this code to your slide instance.

<!-- ./slides/goTo/index.vue -->
<template>
<div class="layout">
<button @click="goToNextChapter">Go to the next chapter</button>
</div>
</template>

// ./slides/goTo/index.vue
export default {
methods: {
goToNextChapter() {
this.$navigator.goToNextChapter();
},
},
};

This code adds the HTML button to your slide. Click the Go to the next chapter button on the slide to call the goToNextChapter method. The method executes navіgation to the next chapter of your e-Detailer.

goToPrevChapter

The goToPrevChapter method opens the previous chapter of your e-Detailer. You can call this API method on any slide of your e-Detailer using this context.

this.$navigator.goToPrevChapter(force)

The force (Boolean) is the optional parameter. It specifies if the navіgation lock is ignored. Defaults to false.

TIP: The force option can be useful if the navіgation to the neighboring slide is locked but you still need to execute the navіgation to this slide.

Usage of goToPrevChapter

To use the goToPrevChapter method on a slide, add this code to your slide instance.

<!-- ./slides/goTo/index.vue -->
<template>
<div class="layout">
<button @click="goToPreviousChapter">Go to the previous chapter</button>
</div>
</template>

// ./slides/goTo/index.vue
export default {
methods: {
goToPreviousChapter() {
this.$navigator.goToPrevChapter();
},
},
};

This code adds the HTML button to your slide. Click the Go to the previous chapter button on the slide to call the goToPrevChapter method. The method executes navіgation to the previous chapter of your e-Detailer.

Locking the navіgation

The navigator module provides the API methods to restrict the navіgation from the current slide. When you lock the navіgation, you can't use the swipe gestures, the keyboard, or the navigator API methods for navigating to any next or previous slide in your e-Detailer. To override the locked navіgation, use the force parameter or the unlocking API methods.

The following API methods are available for locking and unlocking navіgation.

• lockNext() locks the navіgation to any next slide.

• lockPrev() locks the navіgation to any previous slide.

• lock() locks the navіgation to any next and previous slides.

• unlockNext() unlocks the navіgation to any next slide.

• unlockPrev() unlocks the navіgation to any previous slide.

• unlock() unlocks the navіgation to any next and previous slides.

Usage of locking the navіgation

To use the locking or unlocking API methods on a slide, add this code to your slide instance.

<!-- ./slides/open/index.vue -->
<template>
<div class="layout">
<button @click="lockNextSlide">Lock any next slide</button>
<button @click="lockPreviousSlide">Lock any previous slide</button>
<button @click="lockAnySlide">Lock any slide</button>
<button @click="unlockNextSlide">Unlock any next slide</button>
<button @click="unlockPreviousSlide">Unlock any previous slide</button>
<button @click="unlockAnySlide">Unlock any slide</button>
</div>
</template>

// ./slides/open/index.vue
export default {
methods: {
lockNextSlide() {
this.$navigator.lockNext();
},
lockPreviousSlide() {
this.$navigator.lockPrev();
},
lockAnySlide() {
this.$navigator.lock();
},
unlockNextSlide() {
this.$navigator.unlockNext();
},
unlockPreviousSlide() {
this.$navigator.unlockPrev();
},
unlockAnySlide() {
this.$navigator.unlock();
},
},
};

This code adds the HTML buttons to your slide. Click the respective button on the slide to call the navіgation locking or unlocking method. For example, click the Lock any next slide button to lock the navіgation to any next slide in your e-Detailer. To unlock the navіgation, click the Unlock any next slide button.

Navіgation status

The navigator module provides the navіgation status API methods that:

• Show if the navіgation to the previous or next slide is locked.

• Show IDs for the current/previous/next slide and chapter.

getNavіgationStatus

Use the getNavіgationStatus API method to find out if the navіgation to the previous or next slide is locked. You can call this API method on any slide of your e-Detailer using this context.

this.$navigator.getNavіgationStatus();

The getNavіgationStatus method returns an object with the status values:

• prevNavіgationLocked (Boolean) indicates if the navіgation to the previous slide is locked.

• nextNavіgationLocked (Boolean) indicates if the navіgation to the next slide is locked.

Consider the following example.

// ./slides/open/index.vue export default { mounted() { this.$navigator.lockNext(); const getStatus = this.$navigator.getNavіgationStatus(); console.log(getStatus); }, };

The returned result in the browser console:

getCurrentSlide

Use the getCurrentSlide API method to show the IDs for the current slide and chapter. You can call this API method on any slide of your e-Detailer using this context.

this.$navigator.getCurrentSlide();

The getCurrentSlide method returns an object with the IDs for the current slide and chapter:

• chapter (String) shows the current chapter ID.

• slide (String) shows the current slide ID.

Consider the following example.

// ./slides/open/index.vue
export default {
mounted() {
const getCurrentSlide = this.$navigator.getCurrentSlide();
console.log(getCurrentSlide);
},
};

The returned result in the browser console:

getNextSlide

Use the getNextSlide API method to show the IDs for the next slide and chapter. You can call this API method on any slide of your e-Detailer using this context.

this.$navigator.getNextSlide();

The getNextSlide method returns an object with the IDs for the next slide and chapter:

• chapter (String) shows the next chapter ID.

• slide (String) shows the next slide ID.

Consider the following example.

// ./slides/open/index.vue
export default {
mounted() {
const getNextSlide = this.$navigator.getNextSlide();
console.log(getNextSlide);
},
};

The returned result in the browser console:

getPreviousSlide

Use the getPreviousSlide API method to show the IDs for the previous slide and chapter. You can call this API method on any slide of your e-Detailer using this context.

this.$navigator.getPreviousSlide();

The getPreviousSlide method returns an object with the IDs for the previous slide and chapter:

• chapter (String) shows the previous chapter ID.

• slide (String) shows the previous slide ID.

Consider the following example.

// ./slides/open/index.vue
export default {
mounted() {
const getPreviousSlide = this.$navigator.getPreviousSlide();
console.log(getPreviousSlide);
},
};

The returned result in the browser console:

Flow API

A flow means the order in which slides, subslides, and chapters are displayed in your e-Detailer. You can set the flow in the structure.json file. You can't change the e-Detailer structure when users view the e-Detailer. To change the slides order in the e-Detailer you can use custom flows. You can create a new demonstration flow dynamically by reusing the existing slides or subslides. This means that during the e-Detailer demonstration, only the slides from the new flow are displayed.

The navigator module provides the following API methods to work with flows.

setFlow

The setFlow method sets the new flow for displaying the slides in your e-Detailer. You can call this API method on any slide using this context.

this.$navigator.setFlow(structureFlow, goToOptions);

The structureFlow and goToOptions are the required parameters for the setFlow method.

Parameters for setFlow

• structureFlow (Array) is the collection of slides to form the new e-Detailer flow. Each slide in the array is an object with the following fields:

— slide (String) is the slide ID

— chapter (String) is the chapter ID

• goToOptions (Object) defines the slide you're redirected to after creating the new flow; the object itself has the same fields as the goTo method options.

Usage of setFlow

To use the setFlow method on a slide, add this code to your slide instance.

<!-- ./slides/goTo/index.vue -->
<template>
<div class="layout">
<button @click="createFlow">Create a flow</button>
</div>
</template>

// ./slides/goTo/index.vue
export default {
methods: {
createFlow() {
const structureFlow = [{
slide: "open",
chapter: "actions"
},
{
slide: "toggle",
chapter: "actions"
},
{
slide: "switch",
chapter: "actions"
}
];
const goToOptions = {
slide: "open",
chapter: "actions"
};
this.$navigator.setFlow(structureFlow, goToOptions);
},
},
};

This code adds the HTML button to your slide. Click the Create a flow button on the slide to call the setFlow method. The method returns the new flow for displaying the slides. The navigatіon is now between the following slides: open, toggle, and switch. The first slide in the new flow is the open slide that you define in the goToOptions parameter.

resetFlow

The resetFlow method resets the current flow and defines the previous flow as current. If the previous flow doesn't exist, the structure.json file is used instead. You can call this API method on any slide using this context.

this.$navigator.resetFlow();

The goToOptions is the optional parameter for the resetFlow method. Use this parameter if you want to open the specific slide when you reset the flow.

Usage of resetFlow

To use the resetFlow method on a slide, add this code to your slide instance.

<!-- ./slides/switch/index.vue -->
<template>
<div class="layout">
<button @click="resetFlow">Reset a flow</button>
</div>
</template>

// ./slides/switch/index.vue
export default {
methods: {
resetFlow() {
const goToOptions = {
slide: "open",
chapter: "actions"
};
this.$navigator.resetFlow(goToOptions);
}
}
};

This code adds the HTML button to your slide. Click the Reset a flow button on the slide to call the resetFlow method. This method resets the flow of slides to the previous flow or to the flow defined in the structure.json file. Your flow starts with the open slide because you define it in the goToOptions parameter.

TIP: You can create the flow within the already created one and fill it with other slides. In this case, you can return to the previous flow by using the resetFlow method.

reset

The reset method resets the current flow to the flow defined in the structure.json file. You can call this API method on any slide using this context.

this.$navigator.reset();

The goToOptions is the optional parameter for the resetFlow method. Use this parameter if you want to open the specific slide when you reset the flow. Use the reset method in the same way you use the resetFlow method.

Navіgation hooks

The navigator module provides the API methods in the form of hooks. All hooks are called with their this.$navigator context pointing to the Vue instance invoking it. Use the hooks to subscribe a function to the slide navіgation events. With hooks, you can activate certain transition effects, animation, CSS, and other actions when you enter or leave a slide. You can add the hooks on any slide or component in e-Detailers.

The following hooks are available.

• onbeforeenter(handler, options) registers the subscriber function executed each time when you open a slide, before the slide's transition animation starts.

• onenter(handler, options) registers the subscriber function executed each time when you open the slide, after the transition animation ends.

• onbeforeleave(handler, options) registers the subscriber function executed each time when you leave the current slide, before the slide transition animation starts.

• onleave(handler, options) registers the subscriber function executed each time when you leave the current slide, after the slide transition animation ends.

Parameters for the navіgation hooks

Each hook method has the following parameters.

• handler (Function) is the function that executes after the event publication. The handler function returns the object with the IDs for the current chapter, slide, subslide, and the HTMLElement for the current slide.

• options (Object) — global (Boolean) – if true, specifies that the handler function is registered as global. This means that the handler is invoked on each slide.

Usage of the navіgation hooks

To use the navіgation hooks, add the hook and its parameters to the slide instance. For example, add the onenter hook that accepts the navіgation function as its parameter.

// ./slides/slider1/index.vue export default { created() { this.$navigator.onenter(navіgation => { console.log(navіgation) }, ); }, };

When you open the slide with this hook, the method returns this result in the browser console.

This hooks executes on the slide where you define it. To use this hook globally on every slide in your e-Detailer, add the global parameter with the true value.

// ./slides/slider1/index.vue export default { created() { this.$navigator.onenter(navіgation => { console.log(navіgation) }, { global: true }); }, };

When you open every slide of your e-Detailer, the method returns this result in the browser console.

To use the onleave hook on every slide in your e-Detailer, add this code to your slide instance.

// ./slides/slider1/index.vue export default { created() { this.$navigator.onleave(navіgation => { console.log(navіgation) }, { global: true }); }, };

When you leave the slide with this hook and open the next slide, the method returns the result for the previous slide in the browser console.

openDocument

The openDocument method opens the file defined in the path parameter. You can call this API method on any slide using this context.

this.$navigator.openDocument(path);

The path parameter is required. Its type is String.

Usage of openDocument

To use the openDocument method, add this code to your slide instance.

// ./slides/slider2/index.vue
export default {
created() {
this.$navigator.openDocument('./e-Detailer.pdf');
},
};

The openDocument method opens the file located as defined in the path parameter. A PDF file opens in a new browser tab as a PowerPoint presentation compatible with CLMs.

The openDocument method opens the files that have the formats supported by your browser. If your browser doesn't support viewing the file format, the download dialog opens. You can download the file to your computer and open it with the dedicated app.

You can use hyperlinks as the path parameter. The link opens in a new browser tab.

// ./slides/slider2/index.vue
export default {
created() {
this.$navigator.openDocument('https://viseven.com/');
},
};

The openDocument method executes when you navigate to the slide where this method is defined.