@bruit/component

Bruit.io

BRuit is a User Issues Tool

Bruit.io is a WebComponent built on Stencil.js

Available on all frameworks that support WebComponents such as

---

Bruit.io is a tool to get your users feedbacks, designed to be as simple to use as possible, following the Web Component standards. Users' feedbacks are sent directly to your favorite project management tools 🎉 .

Bruit.io is built around an open source Web Component and a backend reciving the users feedback.

And we do no data retention at all about those feedbacks 👏

---

Getting started

start on bruit.io

Table of Contents

Installation
Usage
Configuration
    BrtConfig
    BrtField
    BrtLabels
    BrtColors
    BrtLogLevels
    BrtData
    BrtError
Add data in feedbacks
Handle errors
Frameworks integration
Contributing
Having troubles?

Install

In command line

npm install @bruit/component --save

Or by directly modifying your index.html file

<script src="https://unpkg.com/@bruit/component/dist/bruit.js"></script>

---

Usage

Simply add the following tag wherever you want in your project

<bruit-io> element to click </bruit-io>

with properties :

• config (required)
• data (optional)
• dataFn (optional)
• onError (event) (optional)

integration code examples :

              

Configuration

bruit-io Web Component has a config attribute, which takes a value of BrtConfig type.

BrtConfig

Describes the options for the bruit-io component

interface BrtConfig {
  apiKey: string;
  form: Array<BrtField>;
  labels?: BrtLabels;
  logLevels?: BrtLogLevels;
  maxLogLines?: number;
  colors?: BrtColors;
  closeModalOnSubmit?: boolean;
  apiUrl?: string;
}

Attribute	Type	Description	Mandatory	Default value
apiKey	string	your personal api key (create an api key)	yes	-
form	array<BrtField>	inputs list for the generated form	yes	-
labels	BrtLabels	describes the labels of the modal (title / button / ...)	no	see
logLevels	BrtLogLevels	Used to filter the logs to send by their level (debug, warn, error, etc)	no	see
maxLogLines	number	Defines the number of log lines to send in the feedback	no	100
colors	BrtColors	Allows to pick your colors in the modal theming	no	see
closeModalOnSubmit	boolean	true to have modal closed automatically on submit (feedback is sent in background)	no	false
apiUrl	string	Allows to use some third party backend for feedback processing	no	https://api.bruit.io/feedback

• Typescript import :

import { BrtConfig } from '@bruit/component';

BrtField

Describes both the fields displayed in the popup form and the users' answers.

interface BrtField {
  id?: string;
  label: string;
  type: string;
  required?: boolean;
  value?: any;
}

Attribute	Type	Description	Mandatory
id	string	Unique identifier for the field	no
label	string	Placeholder / label for the field	yes
type	BrtFieldType	The input type of the field	yes
required	boolean	true to make the field required to send the feedback	no
value	any	The value typed by the user	no

BrtConfig.form must contain one BrtField with id="agreement" and type="checkbox", used to check whether personal data should be sent with the feedback.

There are special values for the id attribute:

• agreement: sets the field to use to check whether user agrees to send his personal data

• title: sets the field used to display the title of feedback

• Typescript import:

import { BrtField } from '@bruit/component';

BrtLabels

Used to describe the texts displayed in the modal.

interface BrtLabels {
  title?: string;
  introduction?: string;
  button?: string;
}

Attribute	Description	Default value
title	Defines the title of the modal	bruit.io
introduction	Defines the description text	send a feedback
button	Defines the text of the submit button	send

• Typescript import:

import { BrtLabels } from '@bruit/component';

BrtColors

🎨 If you feel like an artist, you may use BrtColors to change the theme of the modal.

This gives the possiblity to change the header, body, background, errors and focus colors.

Only hexadecimal values are allowed here.

interface BrtColors {
  header?: string;
  body?: string;
  background?: string;
  errors?: string;
  focus?: string;
}

Attribute	Description	Default value
header	the modal's header color	#2D8297
body	the color for the background of the modal	#eee
background	the color used to dim what's behind the modal	#444444ee
errors	the text color to use for errors	#c31313
focus	the color to use on focused field	#1f5a6

• Typescript import:

import { BrtColors } from '@bruit/component';

BrtLogLevels

By default, all log levels (log, warn, errors, ...) are sent in the feedback. BrtLogLevels allows to disable specific ones.

To disable a type, just set with the related type to false in the logLevels section:

{
  "apiKey": "xxxxxxxxxx",
  "form": ["..."],
  "logLevels": {
    "log": false,
    ...
  }
}

interface BrtLogLevels {
  log?: boolean;
  debug?: boolean;
  info?: boolean;
  warn?: boolean;
  error?: boolean;
  network?: boolean;
  click?: boolean;
  url?: boolean;
}

• special types:

  • network type is for your fetch and xmlHttpRequest calls.
  • click type is for mouse click event.
  • url type log all url changing

• Typescript import:

import { BrtLogLevels } from '@bruit/component';

Automatically add data in the feedback

It is possible to automatically had technical data in the feedback, for example the version number of your application, the identifier of the user sending the feedback, etc.

If you have data that can be retrieved synchronously, you can use data.

For asynchronous data, you can use dataFn.

data

data property is used for send synchronous data.

Just give him an BrtData array.

dataFn

dataFn property is used for send asynchronous data.

Give him an Promise of BrtData array. Your promise will be called upon to submit the feedback.

BrtData

• Format :

interface BrtData {
  label: string;
  type?: string;
  value: any;
  id?: string;
}

• import if using Typescript :

import { BrtData } from '@bruit/component';

Handle errors

event

bruit-io emit onError event when an error occured.

An error is composed by a code and a text. it is of type BrtError.

more information about errors

BrtError

• Format :

interface BrtError {
  code: number;
  text: string;
}

• import if using Typescript :

import { BrtError } from '@bruit/component';

Framework integrations

JavaScript

Integrating bruit-io component to a project without a JavaScript framework is straight forward. If you're using a simple HTML page, you can add bruit component via a script tag.

<!DOCTYPE html>
<html lang="en">
<head>
  <script src="https://unpkg.com/@bruit/component/dist/test-components.js"></script>
</head>
<body>
  <bruit-io></bruit-io>
  <script>
    var bruitCmp = document.querySelector('bruit-io');
    bruitCmp.config = {
      apiKey: 'xxxxxxxxxxxxxxxxx',
      form: [...]
    };
  </script>
</body>
</html>

from stencil documentation

Angular

Using bruit-io component within an Angular CLI project is a two-step process. We need to:

1. Include the CUSTOM_ELEMENTS_SCHEMA in the modules that use the components
2. Call defineCustomElements(window) from main.ts (or some other appropriate place)

Including the Custom Elements Schema

Including the CUSTOM_ELEMENTS_SCHEMA in the module allows the use of the web components in the HTML markup without the compiler producing errors. Here is an example of adding it to AppModule:

import { BrowserModule } from '@angular/platform-browser';
import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core';
import { AppComponent } from './app.component';

@NgModule({
  declarations: [AppComponent],
  imports: [BrowserModule],
  bootstrap: [AppComponent],
  schemas: [CUSTOM_ELEMENTS_SCHEMA]
})
export class AppModule {}

The CUSTOM_ELEMENTS_SCHEMA needs to be included in any module that uses custom elements.

Calling defineCustomElements

Bruit component include a main function that is used to load the components in the collection. That function is called defineCustomElements() and it needs to be called once during the bootstrapping of your application. One convenient place to do this is in main.ts as such:

import { enableProdMode } from '@angular/core';
import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';

import { AppModule } from './app/app.module';
import { environment } from './environments/environment';

import { defineCustomElements } from '@bruit/component/dist/loader';

if (environment.production) {
  enableProdMode();
}

platformBrowserDynamic()
  .bootstrapModule(AppModule)
  .catch(err => console.log(err));
defineCustomElements(window);

Using bruit-io in your angular component

<bruit-io [config]="bruitConfig" [data]="bruitData" [dataFn]="bruitDataPromise()" (onError)="handleBruitError($event)"></bruit-io>

public bruitConfig: BrtConfig = {
  apiKey:"xxxxxxxxxxx",
  form:[...]
};

public bruitData: Array<BrtData> = [
  {
    label:"version",
    value: environment.version
  }
];

constructor(private api : ApiService){}

bruitDataPromise():Promise<Array<BrtData>>{
  return this.api.getUser().then( user =>
    [
      {
        label: "user id",
        value: user.id
      },
      {
        label: "user email",
        value: user.email
      }
    ]
  );
}

handleBruitError(error: BrtError){
  ...
}

from stencil documentation

React

With an application built using the create-react-app script the easiest way to include the bruit-io component is to call defineCustomElements(window) from the index.js file.

import React from 'react';
import ReactDOM from 'react-dom';
import './index.css';
import App from './App';
import registerServiceWorker from './registerServiceWorker';

import { defineCustomElements } from '@bruit/component/dist/loader';

ReactDOM.render(<App />, document.getElementById('root'));
registerServiceWorker();
defineCustomElements(window);

from stencil documentation

Vue

In order to use the bruit-io component within the Vue app, the application must be modified to define the custom elements and to inform the Vue compiler which elements to ignore during compilation. This can all be done within the main.js file. For example:

import Vue from 'vue';
import App from './App.vue';
import { defineCustomElements } from '@bruit/component/dist/loader';

Vue.config.productionTip = false;
Vue.config.ignoredElements = [/bruit-\w*/];

defineCustomElements(window);

new Vue({
  render: h => h(App)
}).$mount('#app');

from stencil documentation

Contributing

Contributing to Bruit.io may involve writing TypeScript, TSX, Stencil, SCSS or Markdown depending on the component you are working on. We are looking for help in any of these areas!

Having troubles ?

• issues Github
• StackOverflow