DOCSEARCHbyAlgolia
Submit Docs

GuideChimp

repository·master·Indexed 42 days ago

https://github.com/labs64/guidechimp

A lightweight (< 45KB) library for delivering interactive product walkthroughs, user onboarding, and feature adoption guides in web applications. Version 5.0.5 supports SPAs and can be integrated via npm, ES6 modules, or CDN. It features a plugin system to extend the core class and factory, with available plugins for Vue Router integration, lazy loading of step elements, blurred overlay management, and beacon-triggered tours.

Tokens
3.5K
Snippets
13
Records
18
Agent score
52%

What's inside GuideChimp

  1. GuideChimp Licensing and Usage

    master

    GuideChimp is dual-licensed under the EUPL-1.2 and a Commercial License.

    • EUPL-1.2: If you use this license, you are required to release the source code of any program you distribute that uses GuideChimp.
    • Commercial License: Requires a fee per designated commercial application. Using this license means you are not required to disclose your source code.

    Note: Commercial GuideChimp plugins require a valid customer account and additional configuration via the Licensing-plugin to validate function availability.

  2. Use the plugin template to extend GuideChimp

    master

    GuideChimp plugins are implemented as functions that receive the cls (GuideChimp class), the factory (GuideChimp factory), and optional args (such as an options object).

    You can use this template to:

    • Extend the GuideChimp class: Add new methods to the prototype so they are available on instances (e.g., GuideChimp().customMethod()).
    • Extend the GuideChimp factory: Add new static methods to the factory object (e.g., GuideChimp.customMethod()).
    • Override existing API methods: Capture the original method (e.g., init) and call it within your new implementation to maintain core functionality while adding custom logic.
    • Override default options: Extend the object returned by getDefaultOptions to include plugin-specific configuration.
    /**
 * @param {Class} cls GuideChimp class
 * @param {Object} factory GuideChimp factory
 * @param {Array} args optional arguments needed for the plugin; for instance, the options object
 */
module.exports = (cls, factory, ...args) => {

    /**
     * extend GuideChimp() class
     * e.g. add GuideChimp(tour).customMethod()
     */
    cls.prototype.customMethod = () => {};
    
    /**
     * extend GuideChimp factory
     * e.g. add GuideChimp.customMethod()
     */
    factory.customMethod = () => {};

     // override existing API
     // e.g. extend GuideChimp().init()
     const parentInit = cls.prototype.init;
     cls.prototype.init = () => {
         parentInit();
 
         // custom code
         //...
     };

    // Override static method
    const parentDefaultOptions = cls.prototype.getDefaultOptions;
       cls.getDefaultOptions = () => ({
           ...parentDefaultOptions(),
           // custom options
           // ...
       });
 };

  5. Manual Installation of GuideChimp

    master

    To install manually, download the release from the GitHub releases page and copy the files from the dist directory into your project. Then, include the compiled JavaScript and CSS in your HTML.

    <script src="guidechimp/dist/guidechimp.min.js"></script>
<link rel="stylesheet" href="guidechimp/dist/guidechimp.min.css">

  6. How to create a GuideChimp plugin

    master

    To create a new plugin for the GuideChimp ecosystem, follow these steps:

    1. Fork the GuideChimp repository.
    2. Copy the plugins/_boilerplate folder to your new plugin directory and rename it (e.g., my-plugin).
    3. Implement your functionality using the provided template.
    4. Test your plugin thoroughly.
    5. Include installation and usage instructions in your plugin's own README.md.
    6. Submit a Pull Request to the main repository.

    Note: Submissions are verified against the project's quality requirements.

  7. Install GuideChimp as an ES6 Module

    master

    If your project uses ES6 modules, import the GuideChimp class and the required CSS file to ensure the tooltips and UI are styled correctly.

    import GuideChimp from 'guidechimp';
import 'guidechimp/dist/guidechimp.min.css';

  8. Configure tours via data attributes on beacon elements

    master

    The Beacons plugin automatically detects tour configurations by inspecting the HTML attributes of the beacon elements. It looks for two types of attributes based on the beacon's data prefix:

    1. Global Tour Attribute: [prefix]-tour — If present, this tour name/config is applied to all beacons.
    2. Specific Beacon Tour Attribute: [prefix]-[id]-tour — If present, this overrides the global tour for that specific beacon ID.

    When a user clicks a beacon, the plugin instantiates the guide associated with the value found in these attributes and calls .start() on it.

    <!-- Example: Global tour for all beacons with prefix 'gc' -->
<div gc-tour="my-global-tour-id"></div>

<!-- Example: Specific tour for a beacon with ID 'step-1' -->
<div gc-step-1-tour="{"steps": [...], "options": {}}"></div>

  10. Configure lazyLoading plugin options

    master

    The lazyLoading plugin accepts an options object to control the polling behavior used to detect step elements:

    OptionTypeDefaultDescription
    timeoutnumber5000The maximum time (in milliseconds) to wait for the element to appear before resolving the promise and moving on.
    frequencynumber100The interval (in milliseconds) at which the plugin checks for the existence of the element.

    Note: The timeout value is decremented by the frequency value on every interval tick.

  11. Use the lazyLoading plugin to wait for step elements

    master

    The lazyLoading plugin extends the GuideChimp class to handle scenarios where a step's element might not be immediately available in the DOM (e.g., due to asynchronous rendering or animations).

    When enabled, the plugin intercepts the onBeforeChange event. It pauses the transition to the next step by returning a Promise that only resolves when either:

    1. The target step's element is detected in the DOM and is not a 'fakeStep'.
    2. The specified timeout period is reached.

    This ensures that GuideChimp does not attempt to interact with or display a step before its content has actually rendered.

    // Example plugin registration pattern
import lazyLoading from './plugins/lazyLoading/index.js';

// Assuming 'GuideChimp' is your class and 'factory' is your factory instance
lazyLoading(GuideChimp, factory, {
  timeout: 5000,   // Total time to wait for the element (default: 5000ms)
  frequency: 100  // Interval to check for element existence (default: 100ms)
});

  12. Extend GuideChimp with the Beacons plugin

    master

    The Beacons plugin allows you to attach interactive guides (tours) to specific UI elements (beacons). It works by looking for specific data-* attributes on the beacon elements to determine which guide should be launched when the beacon is clicked.

    To use this plugin, you must provide it to the GuideChimp factory. The plugin overrides getDataBeacons to inject tour information from the DOM and createBeaconEl to attach click listeners that start the specified guide.

    // The plugin is exported as a function that accepts (Class, factory)
import beaconsPlugin from './plugins/beacons/index.js';

// Usage within the GuideChimp plugin system:
// factory.beacons(beacons, options)