README

Volet is a highly customizable customer interaction widget for Laravel applications that provides a flexible feature system. It comes with one built-in feature: feedback messages collection. But it allows you to create your own custom features.

🎨 Fully customizable theme using CSS variables (or by using your own css)
🧩 Extensible feature system
📝 Built-in feedback message collection
🎯 Simple integration with Laravel
🛠️ Built with VueJS
🔧 Easy to create custom features, or install community made features

Introduction
Installation
Quickstart
- Style customization
Creating Custom Features
Built-in Features
- Feedback Messages

Introduction

Volet is an open-source widget-like component that you drop on your website to interact with your website's visitors. It's like Crisp, Zendesk, Intercom, Tawkto, etc.

First this package was named Laravel Kustomer. But due to a stupid copyright infringement, I had to rename this package to 'laravel-feedback-component'.

After several years I finally decided to take the time to rebuild it from scratch. It's now called Volet, which means "a panel that can be opened or closed" in French.

At it's core, it's simply a panel that opens up when you click the floating button. Inside that panel, you will decide what options you want to give your users. It can be a simple form, or a chatbot, or anything you want.

By default, Volet comes with one built-in feature: feedback messages collection, which is a simple way for your users to send you a single message.

What's great about Volet is that it's extensible. You can create custom features, or install community made features. If you want to make your own chatbot, you can integrate it to Volet! Or if someone else made one, you can install it and use it.

This package does not come with any chat out of the box (yet ?).

Installation

You can install the package via composer:

composer require mydnic/volet

Publish the assets with:

php artisan vendor:publish --tag="volet-assets" --force

You can publish and run the migrations with:

php artisan vendor:publish --tag="volet-migrations"
php artisan migrate

You can publish the config file with:

php artisan vendor:publish --tag="volet-config"

Have a quick look at config/volet.php and update anything you want.

Upgrade

If you're upgrading from an older version, you should run:

php artisan vendor:publish --tag="volet-config" --force
php artisan vendor:publish --tag="volet-assets" --force

Optionally, you can add this to your composer.json to automatically update the assets when you update the package:

{
    "scripts": {
        "post-package-update": [
            "@php artisan vendor:publish --tag=volet-assets --force"
        ]
    }
}

Quickstart

First, create a service provider to configure your Volet features. You can publish our pre-configured provider:

php artisan vendor:publish --tag="volet-provider"

This will create app/Providers/VoletApplicationServiceProvider.php with some example features already configured.

return [
    // ...
    App\Providers\VoletApplicationServiceProvider::class,
];

In your VoletApplicationServiceProvider, register and configure your features:

namespace App\Providers;

use Illuminate\Support\ServiceProvider;
use Mydnic\Volet\Features\FeedbackMessages;
use Mydnic\Volet\Features\FeatureManager;

class VoletApplicationServiceProvider extends ServiceProvider
{
    public function boot(FeatureManager $volet): void
    {
        // Register and configure the Feedback Messages feature
        $this->registerFeedbackMessagesFeature($volet);

        // Example of registering a custom feature
        // $volet->register(new YourCustomFeature());
    }

    private function registerFeedbackMessagesFeature(FeatureManager $volet): void
    {
        $volet->register(
            (new FeedbackMessages)
                // Configure feature display
                ->setLabel('Send us feedback')
                ->setIcon('https://api.iconify.design/lucide:message-square.svg?color=%23888888')

                // Add feedback categories
                ->addCategory(
                    slug: 'general',
                    name: 'General Feedback',
                    icon: 'https://api.iconify.design/lucide:smile.svg?color=%23888888'
                )
                ->addCategory(
                    slug: 'improvement',
                    name: 'Improvement',
                    icon: 'https://api.iconify.design/lucide:lightbulb.svg?color=%23888888'
                )
                ->addCategory(
                    slug: 'bug',
                    name: 'Bug Report',
                    icon: 'https://api.iconify.design/lucide:bug.svg?color=%23888888'
                )
        );
    }
}

Then add the Volet component to your blade view:

In the <head> section:

    @voletStyles <!-- skip this if you are using your own CSS theme -->
</head>

Right before the closing body tag:

    @volet
</body>

If you are planning to use your own CSS theme, you can skip adding the @voletStyles directive and add your own CSS file to your <head> section.

Style customization

Volet's default style uses CSS variables for styling. So you can already set your own variables to customize the look and feel of your Volet app.

Add this after the @voletStyles directive:

    @voletStyles
    <style>
        :root {
            --volet-background: #FF2D20;
        }
    </style>
</head>

All variables are listed here : https://github.com/mydnic/volet/blob/2.x/resources/css/volet.css#L4

Creating Custom Features

You can create your own features by extending the BaseFeature class:

namespace App\Volet\Features;

use Mydnic\Volet\Features\BaseFeature;

class CustomFeature extends BaseFeature
{
    public function getId(): string
    {
        return 'custom-chatbot';
    }
    
    public function getLabel(): string
    {
        return 'Talk with our chatbot';
    }
    
    public function getIcon(): string
    {
        return 'https://api.iconify.design/lucide:star.svg?color=%23888888';
    }
    
    public function getVueComponent(): ?string
    {
        return 'CustomFeatureComponent'; // Name of your Vue component
    }
    
    public function getConfig(): array
    {
        return [
            'routes' => [
                'store' => route('custom-feature.store'),
            ],
            'labels' => [
                'placeholder' => 'Enter your message...',
                'button' => 'Submit',
                'success' => 'Thank you!',
            ],
            // Add any other configuration your component needs
        ];
    }
}

You can check our FeatureMessages class for an example of how to configure your feature : https://github.com/mydnic/volet/blob/2.x/src/Features/FeedbackMessages.php

Create a Vue component for your feature's UI:

<!-- resources/js/components/CustomFeatureComponent.vue -->
<template>
    <div class="volet-custom-feature">
        <button class="volet-custom-button">
            Click me
        </button>
    </div>
</template>

<script setup>
defineProps({
    config: {
        type: Object,
        required: true,
    },
})
</script>

<style>
.my-feature-wrapper {
    padding: var(--volet-spacing);
}

.my-feature-button {
    background-color: var(--volet-primary);
    color: var(--volet-background);
    padding: calc(var(--volet-spacing) * 0.5);
    border-radius: 0.375rem;
    transition: background-color 0.2s;
}

.my-feature-button:hover {
    background-color: var(--volet-primary-hover);
}
</style>

You can of course use tailwindcss or any other CSS framework to style your component.

Then you must register your component with Volet.

// resources/js/my-custom-feature.js or similar
import CustomFeatureComponent from "./components/CustomFeatureComponent.vue";

function registerComponent() {
    if (window.Volet) {
        window.Volet.component('CustomFeatureComponent', CustomFeatureComponent);
    }
}

// Register once the DOM is ready
document.addEventListener("DOMContentLoaded", registerComponent);

Compile your javascript and include it after the @volet directive:

    @volet
    @vite('resources/js/my-custom-feature.js')
</body>

Built-in Features

Feedback Messages

The feedback messages feature allows users to submit feedback in different categories. Configure the table name in your config/volet.php:

return [
    'feedback-messages' => [
        'table' => 'custom_feedback_table', // Default: 'volet_feedback_messages'
        
        // ...
    ],
];

Configure the feature in your VoletApplicationServiceProvider:

use Mydnic\Volet\Features\FeedbackMessages;

$volet->register(
    (new FeedbackMessages())
        // Configure feature display
        ->setLabel('Send us feedback')
        ->setIcon('https://api.iconify.design/lucide:message-square.svg?color=%23888888')
        
        // Add feedback categories
        ->addCategory(
            slug: 'bug',
            name: 'Bug Report',
            icon: 'https://api.iconify.design/lucide:bug.svg?color=%23888888'
        )
        ->addCategory(
            slug: 'improvement',
            name: 'Improvement',
            icon: 'https://api.iconify.design/lucide:lightbulb.svg?color=%23888888'
        )
);

You can enable/disable the feature:

(new FeedbackMessages())->disable(); // or ->enable()

Or use conditional configuration:

(new FeedbackMessages())
    ->when(app()->isProduction(), fn ($f) => $f
        ->addCategory('bug', 'Production Bug Report', 'icon-url')
    );

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

License

The MIT License (MIT). Please see License File for more information.

mydnic / laravel-kustomer

Maintainers

Details