@backbone.one/bb1-web-components

v4.3.0

Published

a day ago

0High
0Medium
0Low

ins

chrimishere

ylruiz

devliba

EnergyCalculator Web Component Documentation

EnergyCalculator Web Component Documentation

Installation

To install the BB1EnergyCalculator web component, you need to use npm. Run the following command in your project directory:

npm i @backbone.one/bb1-web-components

Usage

After installing the package, you can use the bb1-energy-calculator web component in your project. Follow the steps below to integrate it into your application.

Import the Component
Import the @backbone.one/bb1-web-components web component in your JavaScript or TypeScript file:
```
import '@backbone.one/bb1-web-components';
```

Add the Component to Your HTML

You can now use the bb1-energy-calculator component in your HTML. Here is an example of how to include it in your HTML file:

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Your Page</title>
    <style>
      bb1-energy-calculator {
        --font-family: Verdana;
        --color: #4c4343;
        --household-selected-bg-color: rgba(255, 0, 0, 0.4);
        --household-selected-color: rgba(0, 0, 0, 1);
        --submit-color: #f0f2f8;
        --submit-bg-color: #e83f3f;
      }
    </style>
  </head>
  <body>
    <bb1-energy-calculator
      offer-service-api-key="your-api-key"
      calculator-link="https://your-domain.com/#/energy-calculator"
      target="_blank"
      translations='{"key": "value"}'
      onsubmit="handleSubmit"
      onerror="handleError"
    ></bb1-energy-calculator>
  </body>
</html>

How it works?

The bb1-energy-calculator web component is designed to calculate energy consumption based on user inputs such as household size, annual consumption, ZIP code, and grid operator. It dynamically adapts to different screen sizes and provides a seamless user experience across devices.

Layout behavior

The bb1-energy-calculator component dynamically adjusts its layout based on the width of its container to ensure optimal usability across devices.

Narrow Layout

Container Width: Typically below 896px.

Appearance:

Inputs are stacked vertically for better readability on smaller screens.
Household size buttons are displayed in a single row with reduced spacing.
The grid operator input and submit button are placed below the other inputs.

Use Case: Ideal for mobile devices or embedded widgets with limited horizontal space.

Wide Layout

Container Width: Typically 896px or wider.

Appearance:

Inputs are arranged in a horizontal grid for efficient use of space.
Household size buttons are displayed in a single row with adequate spacing.
The grid operator input is placed alongside other inputs, and the submit button is aligned to the right.

*Use Case: Ideal for desktop applications or full-screen displays.*

Attributes

The bb1-energy-calculator component accepts the following attributes:

- `offer-service-api-key` (string): The API key for the offer service.
- `calculator-link` (string?): The URL to the tariff calculator that will be opened when the form is submitted. If not provided, no calculator will be opened.
- `target` (string?): Specifies where to open the `calculator-link`. Accepts values like `_blank`, `_self`, `_parent`, or `_top`. Defaults to `_self` if not provided.
- `translations` (object): A JSON object containing translation keys and values.
- `onsubmit` (function(event: SubmitEvent): void?): A JavaScript function to handle the form submission.
- `onerror` (function(error: ErrorEvent): void?): A JavaScript function to handle errors.
- `is-loading` (string): "true" or "false". If "true", the component will display a loading spinner and disable the submit button.
- `is-disabled` (string): "true" or "false". If "true", the component will disable the submit button.
- `value` (object?): An object containing the value of the form fields. The object should have the following keys:
    - `size` (string?)
    - `householdSize` (string?) - Supported but recommended to use size instead.
    - `consumption` (string?)
    - `zipCode` (string?)
    - `gridOperatorId` (string?).
- `customer-type` (string?): "home" | "business". The default value is set to home. When **home**, not set or set incorrectly, the component will display the home customer form. When **business** is set the form for business customer will be displayed.

Value Example

Home customer type

<bb1-energy-calculator
  offer-service-api-key="pMCg87z6VqlZOp93BpNQAQ9f1rImNRoM2sn6PNBluJCkjulMIWUlCfenDIDSlojZ"
  value='{"consumption": 9999, "size": "5+", "zipCode": "8200", "gridOperatorId": 11601}'
  onsubmit="handleSubmit"
  onerror="onError"
>
</bb1-energy-calculator>

Business customer type

<bb1-energy-calculator
  offer-service-api-key="pMCg87z6VqlZOp93BpNQAQ9f1rImNRoM2sn6PNBluJCkjulMIWUlCfenDIDSlojZ"
  value='{"consumption": 9999, "size": "large", "zipCode": "8200", "gridOperatorId": 11601}'
  onsubmit="handleSubmit"
  onerror="onError"
  customer-type="business"
>
</bb1-energy-calculator>

Translations

The translations attribute accepts a JSON object with the following keys:

title (string?): The title of the calculator. If not provided, no title will be displayed.
subTitle (string?): The subtitle of the calculator. If not provided, no subtitle will be displayed.
householdSize (string): The label for the household size input.
businessSize (string): The label for the business size input.
small (string): The level for small business size selection.
medium (string): The level for medium business size selection.
large (string): The level for large business size selection.
annualConsumption (string): The label for the annual consumption input.
zip (string): The label for the ZIP code input.
zipPlaceholder (string): The placeholder for the ZIP code input.
gridOperator (string): The label for the grid operator input.
gridOperatorPlaceholder (string): The placeholder for the grid operator input.
gridOperatorInfo (string): The info text for the grid operator input.
submit (string): The text for the submit button.

Event Listeners

To add event listeners to the bb1-energy-calculator web component, you can use the following example:

HTML File: Add the component to your HTML and define the event listeners.

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Your Page</title>
    <style>
      bb1-energy-calculator {
        --font-family: Verdana;
        --color: #4c4343;
        --household-selected-bg-color: rgba(255, 0, 0, 0.4);
        --submit-color: #f0f2f8;
        --submit-bg-color: #e83f3f;
      }
    </style>
  </head>
  <body>
    <bb1-energy-calculator
      id="energyCalculator"
      offer-service-api-key="your-api-key"
    ></bb1-energy-calculator>

    <script>
      const energyCalculator = document.getElementById('energyCalculator');

      energyCalculator.addEventListener('submit', (event) => {
        console.log('Submitted data:', event.detail);
      });

      energyCalculator.addEventListener('error', (event) => {
        console.log('Error happened:', event.detail);
      });
    </script>
  </body>
</html>

React Component: If you are using React, you can add the event listeners in a useEffect hook.

import React, { useEffect, useRef } from 'react';
import '@backbone.one/bb1-web-components';
import { SubmitEvent, ErrorEvent } from '@backbone.one/bb1-web-components'

const EnergyCalculatorComponent = () => {
  const calculatorRef = useRef(null);

  useEffect(() => {
    const calculatorElement = calculatorRef.current;

    const handleSubmit = (event: SubmitEvent) => {
      console.log('Submitted data:', event.detail);
    };

    const handleError = (event: ErrorEvent) => {
      console.log('Error happened:', event.detail);
    };

    calculatorElement.addEventListener('submit', handleSubmit);
    calculatorElement.addEventListener('error', handleError);

    return () => {
      calculatorElement.removeEventListener('submit', handleSubmit);
      calculatorElement.removeEventListener('error', handleError);
    };
  }, []);

  return (
    <bb1-energy-calculator
      ref={calculatorRef}
      offer-service-api-key="your-api-key"
    ></bb1-energy-calculator>
  );
};

export default EnergyCalculatorComponent;

Styling

You can customize the appearance of the bb1-energy-calculator web component using CSS variables.

Example:

bb1-energy-calculator {
  --font-family: Verdana;
  --color: #4c4343;
  --household-selected-bg-color: rgba(255, 0, 0, 0.4);
  --household-selected-color: rgba(0, 0, 0, 1);
  --submit-color: #f0f2f8;
  --submit-bg-color: #e83f3f;
}

bb1-energy-calculator::part(title) {
  font-size: 24px;
  font-weight: bold;
}

bb1-energy-calculator::part(subtitle) {
  font-size: 18px;
  color: #666;
}

--font-family: Sets the font family for the component.
--color: Sets the text color for the component.
--household-selected-bg-color: Sets the background color for the selected household size button.
--household-selected-color: Sets the text color for the selected household size button.
--submit-color: Sets the text color for the submit button.
--submit-bg-color: Sets the background color for the submit button.
::part(title): Styles the title part of the component.
::part(subtitle): Styles the subtitle part of the component.

Typescript Support

The bb1-energy-calculator component is written in TypeScript and includes type definitions for the attributes and events. You can use these types to ensure type safety in your application.

Import the types in your TypeScript file:

import '@backbone.one/bb1-web-components'; // Import the component
import {
  SubmitEvent,
  ErrorEvent,
  Translations,
} from '@backbone.one/bb1-web-components'; // Import the types