npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

botman-extended-web-widget

v1.2.8

Published

A BotMan frontend package for the web widget

Downloads

32

Readme

Quick Links


Overview

The BotMan Extended Web Widget is an enhanced version of the BotMan Web Widget that allows you to integrate a rich chatbot experience into your website. The widget is built using modern web technologies and provides a seamless integration experience. It offers features such as shadow DOM, custom styles injection, enhanced authentication, and support for single-page application (SPA) frameworks.


Demo

  • HTML Implementation: Check out this HTML Example
  • VUE SPA Implementation: Check out this Vue SPA Example

Features

  • No Iframe Required: Leverage modern web technologies to embed your chatbot.
  • Shadow DOM: Utilize encapsulated styles and markup for widget isolation.
  • Custom Styles Injection: Easily apply custom styles to match your website's theme.
  • Enhanced Authentication: Secure your chatbot with custom headers.
  • Vite and TypeScript: optimized build process and improved code reliability.
  • SPA Framework Support: Seamlessly integrate the widget into your React, Angular, or Vue app.

Installation

npm

npm install botman-extended-web-widget

yarn

yarn add botman-extended-web-widget

Usage

JavaScript (default configuration)

By default, the widget is rendered as a custom element utilizing Shadow DOM for encapsulation. Defualt styles are injected directly into the Shadow DOM for a seamless integration. To use the widget, simply import the module and initialize it with the URL of your chat server.

import BotManWidget from 'botman-extended-web-widget';
new BotManWidget({
    chatServer: 'https://php-uk-conference-2018.marcelpociot.de/botman',
});

HTML

in your HTML file, add the following code:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>BotMan Widget</title>
</head>
<body>
<script>
    var botmanWidget = {
        chatServer: 'https://php-uk-conference-2018.marcelpociot.de/botman',
        frameEndpoint: './chat.html',
        useChatAsIframe: true,
        useInAppCss: false,
        useShadowDom: false,
        autoInit: true,
        useLoader: true,
        requestHeaders: {
            'X-Shop-Domain': '1234'
        },
        customStylesInjection:`
            /* with shadow dom and no iframe */
            .botmanWidgetRootInner > div:nth-child(2) {
                background-color: green;
            }

            /* with iframe */
            html, body{
                background-color: red;
            }
        `,
    };
</script>
<script type="module" src="../dist/widget.js"></script>
</body>
</html>

SPA Frameworks (React, Angular, Vue, etc.)

import BotManWidget from 'botman-extended-web-widget';

new BotManWidget({
    chatServer: 'https://php-uk-conference-2018.marcelpociot.de/botman',
    frameEndpoint: './chat.html',
    useChatAsIframe: true,
    useInAppCss: false,
    useShadowDom: false,
    useLoader: true,
    requestHeaders: {
        'X-Shop-Domain': '1234'
    },
    customStylesInjection:`
        /* with shadow dom and no iframe */
        .botmanWidgetRootInner > div:nth-child(2) {
            background-color: green;
        }

        /* with iframe */
        html, body{
            background-color: red;
        }
    `,
});

Configuration

The BotMan Extended Web Widget can be configured using the following options:

Orginal options can be found here

Here are the new options: | Option | Type | Description | default | notes | | --- | --- | --- | --- | --- | | useChatAsIframe | boolean | Whether to use the chat as an iframe. | false | | useInAppCss | boolean | Whether to use in-app inline CSS. | false | | useShadowDom | boolean | Whether to use shadow DOM. | true | css is always injected | | requestHeaders | object | Custom headers for authentication. | {} | | customStylesInjection | string | Custom styles to inject into the widget. | '' | | autoInit | boolean | Whether to automatically initialize the widget. use if load in html | false | | useLoader | boolean | Whether to use a loader as a type indication until the server responds | false | | sandboxAttributes | string | The sandbox attribute for the iframe | '' | Sandbox Docs |

reactiv chat open / close state

    var wasChatOpened = false; // Flag to track if the chat was opened
    window.addEventListener('chatOpenStateChange', function(event) {
        // event.detail = {isOpen: true} or {isOpen: false}
        if (event.detail.isOpen && !wasChatOpened) {
            // This block will only execute once, the first time the chat is opened
            window.botmanChatWidget.whisper("start conversation");
            wasChatOpened = true; // Set the flag to true after sending the message
        }
    });

Customization

styles

The BotMan Extended Web Widget can be customized using the customStylesInjection option. This option accepts a string containing CSS rules that will be injected into the widget. The following example demonstrates how to customize the widget's appearance:

new BotManWidget({
    chatServer: 'https://php-uk-conference-2018.marcelpociot.de/botman',
    frameEndpoint: './chat.html',
    useChatAsIframe: true,
    useInAppCss: false,
    useShadowDom: false,
    requestHeaders: {
        'X-Custom-Header': '1234'
    },
    customStylesInjection:`
        /* with shadow dom and no iframe */
        .botmanWidgetRootInner > div:nth-child(2) {
            background-color: green;
        }

        /* with iframe */
        html, body{
            background-color: red;
        }
    `,
});

Background Image

To embed a custom background image to the chat window, you can use the customStylesInjection option to set the background-image property. The following example demonstrates how to add a background image to the chat window with vite speciel syntax:

    import svgContent from '../assets/chat-background.svg?raw';
    const encodedSvg = encodeURIComponent(svgContent);
    new BotmanWidget({
      customStylesInjection: `
      .botmanWidgetRootInner > div:nth-child(2) {
        background-image: url("data:image/svg+xml,${encodedSvg}");
      }
        `,
    });

Actions

The BotMan Extended Web Widget provides a actions type that allows you to add buttons to the chat window. In some cases, you may want to write the action text in the chat window. To do this, you can use the additionalParameters option to set the isActionRespondVisible parameter to true. The following example demonstrates how to add buttons to the chat window:

    public function startConversation()
        {
            $question = Question::create('Do you need support or help with anything?')
                ->fallback('Unable to ask question')
                ->callbackId('ask_support')
                ->addButtons([
                    Button::create('Yes, I need help')->value('yes')->additionalParameters(['isActionRespondVisible' => true]),
                    Button::create('No, thank you')->value('no')->additionalParameters(['isActionRespondVisible' => true]),
                ]);
        }

Contributing

Issues

Please open an issue if you have any feature requests, bug fixes, or suggestions.

Contributing

Contributions are welcome, feel free to submit a PR.

Acknowledgments

  • BotMan - The original BotMan Web Widget provided the foundation for the BotMan Extended Web Widget. This project builds upon the original by adding new features and enhancements while maintaining compatibility with existing BotMan infrastructure. Thanks to Marcel Pociot, the creator of BotMan.

Supporting

If you like this project, please consider supporting it by starring this repository on GitHub.

License

This project is open-sourced software licensed under the MIT license.