Configure

Table of Contents

• Initialize
• Options
• Methods
• Events
• Step Definition
• Plugins
• Styling

---

Initialize

var guideChimp = GuideChimp(tour);

• tour: The name of the tour if HTML configuration being used or tour JavaScript object.

Options

Options can be used to control GuideChimp behaviour and look-and-feel.

var guideChimp = GuideChimp(tour, options);

• position: Define the position of the tour steps (top, bottom, right or left) (default: 'top')
• useKeyboard: Allow keyboard navigation between the steps (default: true)
• exitEscape: Stop tour on escape click (default: true)
• exitOverlay: Stop tour on overlay click (default: true)
• showPagination: Show pagination (default: true)
• showProgressbar: Show progress bar (default: true)
• interaction: Allow interaction with the highlighted components (default: true)
• padding: Padding between highlighted element and tooltip (default: 10)
• scrollPadding: Padding between top screen border and highlighted element (default: 10)
• scrollBehavior: Property that determines the scrolling behavior to the highlighted element (default: auto)

Methods

• start(stepNumber = 0, useIndex = true): Start the tour
  • stepNumber: Step number to start the tour from (default: 0)
  • useIndex: Use step index (top-down step position in HTML document) instead of the step number (step or data-guidechimp-step attribute) (default: true)
• go(stepNumber = 0, useIndex = true): Go to the specific step number
  • stepNumber: Step number to continue the tour from (default: 0)
  • useIndex: Use step index (top-down step position in HTML document) instead of the step number (step or data-guidechimp-step attribute) (default: true)
• previous(): Go to the previous step
• next(): Go to the next step
• stop(): Stop the tour
• on(event, callback): Register an event listener for a tour event

Methods start(), go(), stop(), previous(), next() support additional context, which will be made available in the corresponding events, such as onStop() and similar.

Example

guide.stop({ flag: true });

guide.on('onStop', (context) => {
    const { flag } = context || {};

    if (flag) {
        // ...
    } else {
        // ... 
    }
});

Events

• onStart: Called at the start of the tour
• onBeforeChange: Called before the step change
• onAfterChange: Called after the step change
• onStop: Called when the tour is stopped
• onComplete: Called when the tour is completed
• onPrevious: Called before the tour returns to the previous step
• onNext: Called before the tour move to the next step

Example

guideChimp.on('onBeforeChange|onAfterChange', (to, from)=>{});

guideChimp.on('onStart|onStop|onComplete', ()=>{});

Step Definition

You can define steps in two different ways (HTML Attributes or JavaScript Object):

HTML Attributes

Use these HTML attributes:

• data-guidechimp-tour: Name of the tour(-s); multiple tours need to be separated by a comma
• data-guidechimp-step: Tour step number (number)
• data-guidechimp-title: Tour step title
• data-guidechimp-description: Tour step description (HTML supported)
• data-guidechimp-position: Position of the tour steps
• data-guidechimp-interaction: Interact with the highlighted components
• data-guidechimp-scrollPadding: Override global padding between top screen border and highlighted element

In case the same HTML element being used in the multiple tours, you can define tour specific step attributes using the following pattern: data-guidechimp{-tourname}-title

Example

<!-- Single tour -->
<div class="tour-element"
     data-guidechimp-tour="tour"
     data-guidechimp-step="1"
     data-guidechimp-title="Step title"
     data-guidechimp-description="Step description">
     YOUR-CONTENT-HERE
</div>

<!-- Multiple tours -->
<div class="tour-element"
     data-guidechimp-tour="tour1,tour2"
     data-guidechimp-tour1-step="2"
     data-guidechimp-tour2-step="1"
     data-guidechimp-title="Step title"
     data-guidechimp-tour1-description="Step description"
     data-guidechimp-tour2-description="Step description"
     data-guidechimp-scrollPadding="100"
     data-guidechimp-position="bottom">  // common for all defined for this element tours
     YOUR-CONTENT-HERE
</div>

// js
var guideChimp = GuideChimp('tour');

JavaScript Object

Following options can be used to configure tour via JavaScript:

• element: Query selector string or HTML element; if not defined, the tooltip will be centred on the screen; see also How to verify CSS selector
• step: Step number (optional)
• title: Tour step title
• description: Tour Step description
• position: Position of the tour steps
• interaction: Allow interaction with the highlighted components
• buttons: Custom action buttons; can be an object or HTML element
  • tagName: HTML element to be used for button rendering (default: 'button')
  • title: Button title
  • class: Button style class(-es)
  • onClick: Listener function called on the element click
• scrollPadding: Override global padding between top screen border and highlighted element
• onBeforeChange(): Listener function called before the step change
• onAfterChange(): Listener function called after the step change

Example

var tour = [
    {
        element: '#element-id',
        title: 'Step title',
        description: 'Step description',
        buttons: [
            {
                title: 'See more',
                class: 'tour-button',
                onClick: function () {
                    alert("Step button click");
                }
            }
        ]
    },
];
var guideChimp = GuideChimp(tour);
guideChimp.start();

Plugins

GuideChimp can be extended using Built-In and Third-Party plugins.

You can enable multiple plugins based on your needs.

Enable Plugin as ES6 Module

// core
import GuideChimp from 'guidechimp';

// plugins
import licensing from 'guidechimp/dist/plugins/licensing';
import beacons from 'guidechimp/dist/plugins/beacons';
import multiPage from 'guidechimp/dist/plugins/multiPage';
import googleAnalytics from 'guidechimp/dist/plugins/googleAnalytics';
import triggers from 'guidechimp/dist/plugins/triggers';
import lazyLoading from 'guidechimp/dist/plugins/lazyLoading';
// ...

// enable plugins
GuideChimp.extend(licensing, { id: %CUSTOMER_NUMBER% });
GuideChimp.extend(beacons);
GuideChimp.extend(multiPage);
GuideChimp.extend(googleAnalytics);
GuideChimp.extend(triggers);
GuideChimp.extend(lazyLoading);

Enable Plugin as HTML Dependency

<script src="guidechimp/dist/guidechimp.min.js"></script>
<script src="guidechimp/dist/plugins/licensing.js"></script>
<script src="guidechimp/dist/plugins/beacons.js"></script>
<script src="guidechimp/dist/plugins/multiPage.js"></script>
<script src="guidechimp/dist/plugins/googleAnalytics.js"></script>
<script src="guidechimp/dist/plugins/triggers.js"></script>
<script src="guidechimp/dist/plugins/lazyLoading.js"></script>

<!-- Enable plugin as guideChimpPlugin{PluginName} -->
<script>
    GuideChimp.extend(guideChimpPluginLicensing, { id: %CUSTOMER_NUMBER% });
    GuideChimp.extend(guideChimpPluginBeacons);
    GuideChimp.extend(guideChimpPluginMultiPage);
    GuideChimp.extend(guideChimpPluginGoogleAnalytics);
    GuideChimp.extend(guideChimpPluginTriggers);
    GuideChimp.extend(guideChimpPluginLazyLoading);
</script>

Licensing

Commercial GuideChimp plugins require a valid customer account with the assigned plan and additional configuration, which will be used to validate the availability of particular GuideChimp functions or plugins for the given customer account.

Plugins Development

You can contribute and create own GuideChimp Plugin to meet various needs; e.g. integrate with other services such as User Surveys, Analytics, Collaboration and many others.

Use GuideChimp plugin boilerplate as a starting point for your plugin development.

Styling

You can override GuideChimp styles and define your individual Look and Feel for the visual elements.

Example

/* Change the background of the highlighted element */
.gc-highlight {
    background: none;
}

/* Change overlay color and transparency */
.gc-overlay {
    opacity: 0.5;
    background-color: #F08B53;
}

/* Change progressbar color */
.gc-progressbar {
    background-color: #7B2A10;
}

/* Wide tooltip */
.gc-tooltip {
    min-width: 700px;
    max-width: 800px;
}

/* Extended (high) decription area */
.gc-description {
    max-height: 500px;
}