Feedbacky

Overview

Feedbacky is a JavaScript package designed for handling feedback in the browser environment. It provides a customizable and easy-to-use feedback modal and form that you can integrate into your web applications.

Visit Feedbacky for more information and try it out.

Features

• **Extremely Lightweight: ** Minified: ~20 KB | Gzipped: ~6 KB
• Zero Dependencies: No external dependencies for seamless integration.
• Ready to Use: Out-of-the-box solution for collecting feedback from users.
• Framework Agnostic: Compatible with any frontend framework of your choice.
• CDN Support: Facilitates easy integration with Content Delivery Network (CDN).
• Custom Submit Handlers: Support for personalized submit handlers tailored to your backend.
• Customizable Form Fields: Flexibility in defining and styling text, textarea, and select form fields.
• Effortless Styling: Easily customize styles using convenient data attributes.
• Responsive Design: Ensures optimal user experience across different devices and screen sizes.
• Accessibility-Focused: Designed with accessibility in mind for a more inclusive user interface.
• TypeScript Support: Built with TypeScript for enhanced development with type safety.
• Feedbacky Server: Default backend solution for Feedbacky that allows you to get feedback reports easily.
• SheetDB Backend: Option to use SheetDB as a backend solution.

Contents

• Overview
• Features
• Contents
• Installation
• Usage
  • As a Module
  • As a CDN Script
  • Typescript
  • SheetDB Api Configuration
• Feedbacky Options
  • Example Options
• Props
  • Form Fields ('IFormFieldBase`)
  • Input Form Field (IInputFormField)
  • Text Area Form Field (ITextAreaFormField)
  • Select Form Field (ISelectFormField)
• How to Style?
• Test and Development
  • Testing
  • Covarage Report
  • Building
  • Linting
• License
• Author

Installation

npm install @ogzhnsfgl/feedbacky

# or

yarn add @ogzhnsfgl/feedbacky

Alternatively, you can use the package from the CDN:

 <script src="https://cdn.jsdelivr.net/npm/@ogzhnsfgl/feedbacky"
         data-fby-script
         data-fby-sheet-db-api-key="YOUR_SHEET_DB_API_KEY"
         data-fby-options="{ "primaryColor": "#000" }"
 ></script>

Usage

As a Module

To use Feedbacky in your project, you need to create an instance of the Feedbacky class and initialize it. Here's an example using TypeScript:

import Feedbacky from '@ogzhnsfgl/feedbacky';
import initFeedbacky from './utils/init-feedbacky';

const feedbackyInstance = new Feedbacky({
  sheetDbApiKey: 'YOUR_SHEETDB_API_KEY', // If you want to use SheetDB as a backend
  clientId: 'YOUR_CLIENT_ID_PROVIDED_BY_FEEDBACKY_SERVER', // If you want to use Feedbacky Server
  onSuccessSubmit: () => {
    console.log('Form submitted successfully!');
  },
  onErrorSubmit: () => {
    console.log('Form submission failed!');
  },
  primaryColor: '#3C1234'
  // ... other options
});

initFeedbacky(feedbackyInstance);

If you want to use Feedbacky Server, you need to pass clientId option instead of sheetDbApiKey option.

Make sure to replace 'YOUR_SHEETDB_API_KEY' with your actual SheetDB API key.
You can obtain an API key from [SheetDB](https://docs.sheetdb.io/).

### As a CDN Script

You can pass [data-fby-options] attribute to the script tag to customize the
Feedbacky. Here's an example:

```html
<script
  src="https://unpkg.com/@ogzhnsfgl/feedbacky"
  data-fby-script // This attribute is required for initializing Feedbacky
  data-fby-sheet-db-api-key="YOUR_SHEET_DB_API_KEY" // If you want to use SheetDB as a backend
  data-fby-client-id="YOUR_CLIENT_ID_PROVIDED_BY_FEEDBACKY_SERVER" // If you want to use Feedbacky Server
  data-fby-options={
    "backgroundColor": "#ffffff",
    "primaryColor": "#3CA735",
    "buttonText": "💬 Provide Feedback"
    // ... other options
  }
></script>

Feedbacky will be initialized automatically when the page loads. And attach itself to Window object as window.Feedbacky.

Feedbacky instance has 2 methods:

• init() : Initializes the feedbacky, create the main button on the page.
• destroy() : Destroys the feedbacky.

Note: If Feedbacky is already initialized, calling init again will result in a warning message, and you should call the destroy method before initializing it again.

Typescript

Feedbacky is written in TypeScript and comes with its own type definitions. You can use Feedbacky with TypeScript without any additional configuration.

You can also import the type definitions from the package:

import type { IFeedbackyOptions } from '@ogzhnsfgl/feedbacky';

SheetDB Api Configuration

You can use SheetDB as a backend, SheetDB is a spreadsheet-based database that allows you to store data in Google Sheets. To use SheetDB as a backend, you need to create a SheetDB API key and pass it to the sheetDbApiKey option when initializing Feedbacky.

Before use Feedbacky, you need to create first item with correct fields in your sheet. Please remind that Feedbacky adds automatically date field to POST request.

Here is an example of a correct item:

Your feedbacky form fields:

formFields: [
  {
    element: 'input',
    type: 'text',
    name: 'name',
    label: 'Name',
    placeholder: 'Your name',
    required: true,
    requiredErrorMessage: 'Please enter your name'
  },
  {
    element: 'input',
    type: 'email',
    name: 'email',
    label: 'Email',
    placeholder: 'Your email',
    required: true,
    requiredErrorMessage: 'Please enter your email'
  },
  {
    element: 'textarea',
    name: 'message',
    label: 'Message',
    placeholder: 'Your message',
    required: true,
    requiredErrorMessage: 'Please enter your message'
  }
];

Your sheetdb sheet fields should be like this:

| name | email | message | date |

Feedbacky Options

Feedbacky comes with a set of customizable options to tailor the appearance and behavior of the feedback form. Purpose of easy to use, Feedbacky has a default set of options that you can override with your own values.

Example Options:

const feedbackyInstance = new Feedbacky({
  sheetDbApiKey: 'YOUR_SHEETDB_API_KEY',
  clientId:'YOUR_CLIENT_ID_PROVIDED_BY_FEEDBACKY_SERVER',
  backgroundColor: '#ffffff',
  primaryColor: '#3CA735',
  buttonText: '💬 Provide Feedback',
  ... other options });

initFeedbacky(feedbackyInstance);

For a full list of available options and their default values, see the Props section below.

Props

Here are the props you can pass to the Feedbacky class:

Props

Here are the props you can pass to the Feedbacky class:

Form Fields

Feedbacky comes with default form fields that you can use out of the box. You can also customize the form fields by passing an array of form field.

Default form fields:

formFields: [
  {
    element: 'textarea',
    name: 'message',
    label: 'Message',
    placeholder: 'Your message',
    required: true
  }
];

Feedbacky supports three types of form fields: text, textarea, and select. You can customize the form fields by passing an array of form field configurations to the formFields option. Here's list of available form field properties:

Form Fields ('IFormFieldBase)

Input Form Field (IInputFormField)

IInputFormField extends IFormFieldBase and adds the following properties:

Text Area Form Field (ITextAreaFormField)

ITextAreaFormField extends IFormFieldBase and adds the following properties:

Select Form Field (ISelectFormField)

ISelectFormField extends IFormFieldBase and adds the following properties:

How to Style?

Feedbacky offers extensive customization options, allowing you to style every aspect of the feedback form, from the main button to the modal. By applying styles to the provided data attributes, you can achieve a tailored appearance for your Feedbacky integration. Here's a comprehensive list of data attributes along with their default targets and styles:

You can easily customize the Feedbacky modal by applying styles to these data attributes. For example, to change the background color of the modal, you can use:

[data-fby-modal] {
  /* Custom styles for the modal */
  background-color: #fff;
  box-shadow: 0 0 10px rgba(0, 0, 0, 0.2);
  /* ... */
}

Feel free to customize these styles based on your project's design requirements.

Test and Development

Testing

To run tests using Jest, use the following script:

yarn test

For watching files and running tests on changes, you can use:

```bash
  yarn test:watch

To generate test coverage reports, use:

yarn test:coverage

Covarage Report

Building

To build the package in development mode, use:

yarn build:dev

To build the package in production mode, use:

yarn build:prod

To serve the package locally, use:

yarn serve

Linting

To lint the project using ESLint, use:

yarn lint

To fix linting errors, use:

yarn lint:fix

License

Feedbacky is licensed under the MIT License.

Author

Oğuzhan Sofuoglu.

Made with ❤️