@homeboxio/react-ui v1.0.32

Homebox React UI

A set of React components for powering React user interfaces that interact with the Homebox platform.

Install

npm install --save @homeboxio/react-ui

Demo

npm run start

# In a new terminal:
cd ./example
npm run start

\<AddressFinder \/>

An input to find a property address & match to national energy metering databases (ECOES & DES).

Example Usage

import React, { Component } from 'react'

import { AddressFinder } from '@homeboxio/react-ui'

class AddressFinder extends Component {
  render() {
    return (
      <AddressFinder
        address={{ addressLine1: "Flat A", addressLine2: "10 Testing Road", postcode: "OX11AA" }}
        partnerId="testing-account"
        mode="sandbox"
      />
    );
  }
}

Props

* = required

setAddress(address)* function

A callback function which receives address details of the property / contact address.

setAsset(asset, assetLabel)* function

A callback function which receives full gas & electricity meter asset objects.

setBillingAddress(billingAddress)* function

A callback function which receives billing address details, if an alternate billing address is set.

setBillingAddressStatus(status)* function

A true/false value indicating whether there is an alternative billing address.

setCustomAssetProperty(value, property)* function

A callback for when a custom asset property (e.g MPAN, MPRN, meter serial numbers) are set.

defaultAddress object

An address object, used to pre-populate property / contact address data with the following shape:

{
  addressLine1: 'String', // Required
  addressLine2: 'String',
  postcode: 'String', // Required
  locality: 'String', // Town / city
  region: 'String',
}

defaultBillingAddress object

An address object, used to pre-populate billing address data, with the following shape:

{
  addressLine1: 'String', // Required
  addressLine2: 'String',
  postcode: 'String', // Required
  locality: 'String', // Town / city
  region: 'String',
}

partnerId string

Your partner ID. The component will not function without a valid partner ID. Please contact the Homebox team to have one generated at hi (at) homebox.co.uk

environment string

The environment mode. Possible values:

• staging (default)
• live

fuelType string

The type of energy fuels the user has. Possible values:

• electricityOnly
• dualFuel (default)
• gasOnly (not currently supported)

showMPXNInputs boolean

Display optional MPAN & MPRN inputs when collecting a freetext address.

showMSNInputs boolean

Display optional electricity meter serial number & gas meter serial number inputs when collecting a freetext address.

\<AddressFinderConnected \/>

Automatic bindings to a Redux store that follows Homebox's data model patterns.

Example Usage

import React, { Component } from 'react'

import { AddressFinderConnected } from '@homeboxio/react-ui'

class AddressFinderConnected extends Component {
  render() {
    return (
      <AddressFinderConnected
        serviceIndex={this.props.serviceIndex}
        switchIndex={this.props.switchIndex}
        spacesServiceUpdate={spacesServiceUpdate}
        accountUpdate={accountUpdate}
        spacesSwitchesUpdate={spacesSwitchesUpdate}
        showMSNInputs={true}
      />
    );
  }
}

function mapStateToProps(state) {
  return {
    spaces: state.spaces,
  };
}

export default connect(mapStateToProps)(AddressFinderConnected);

Props

The following props are inherited from AddressFinder and can also be passed to AddressFinderConnected:

• defaultAddress
• defaultBillingAddress
• partnerId
• environment
• fuelType
• showMPXNInputs
• showMSNInputs

serviceIndex number

The array index position of the current service within the spaces.services[n] array.

switchIndex number

The array index position of the current switch within the spaces.services[n].switches[n] array.

spacesServiceUpdate* function

A redux action creator function that accepts the following params:

• serviceIndex
• update

example:

spacesServiceUpdate(serviceIndex, update) => ( ... )

accountUpdate* function

A redux action creator function that accepts the following params:

-update

example:

accountUpdate(update, _dataPersistence) => ( ... )

spacesSwitchesUpdate* function

A redux action creator function that accepts the following params:

• serviceIndex
• switchIndex
• update

example:

spacesSwitchesUpdate(serviceIndex, switchIndex, update) => ( ... )

UX Information

Validation

When implementing the AddressFinder within a form, it's nescessary to validate that the user has selected an address externally.

Example of validation for the AddressFinderConnected component:

onSubmit() {
  // Address Finder validation.
  let addressSet = false;
  const thisService = this.props.spaces.services[this.props.serviceIndex];
  if (thisService.assets.electricity && thisService.assets.electricity.assetDetails && thisService.assets.electricity.assetDetails.AddressDetails && thisService.assets.electricity.assetDetails.AddressDetails.length > 0) {
    if (thisService.preferences.type === 'electricityOnly') {
      addressSet = true;
    } else {
      // Assume dual fuel, check gas is set as well.
      if (
        thisService.assets.gas && thisService.assets.gas.assetDetails
        && (thisService.assets.gas.assetDetails.AddressDetails && thisService.assets.gas.assetDetails.AddressDetails.length > 0 || thisService.assets.gas.assetDetails.value && thisService.assets.gas.assetDetails.value === 'addressNotFound')
      ) {
        addressSet = true;
      }
    }
  } else if (
    thisService.assets.gas && thisService.assets.gas.assetDetails && thisService.assets.gas.assetDetails.AddressDetails && thisService.assets.gas.assetDetails.AddressDetails.length > 0
    && thisService.preferences.type === 'gasOnly'
  ) {
    // Gas only (not yet fully supported).
    addressSet = true;
  } else {
    // Assets not set, check for manual address input.
    if (this.props.thisSwitch.submittedData.myHome && this.props.thisSwitch.submittedData.myHome.address) {
      const customAddress = this.props.thisSwitch.submittedData.myHome.address;
      if (customAddress.addressLine1 && customAddress.locality && customAddress.postcode) {
        addressSet = true;
      }
    }
  }

  if (!addressSet) {
    errors.myHome.addressPicker.addError('You must select your address');
  }
}

Pre-populated Data Matching

Address information passed to the components will be used to attempt to automatically match entries in ECOES & DES. This is especially useful when you already have some idea of the address of the user.

e.g the following data will yield an exact match for both electricity and gas:

{
  addressLine1: 'Flat 11 33 Mill Lane',
  postcode: 'NW61NY',
  locality: 'London'
}

//-> "FLAT 11 THE MANSIONS;33 MILL LANE LONDON NW6 1NY"(ECOES)
//-> "11 THE MANSIONS FLAT 11 THE MANSIONS 33 MILL LANE LONDON NW6 1NY" (DES)

Homebox's address matching algorithm is trained on a variety of complex & unusual addreses, e.g apartment & flats, scottish style addresses etc.

When an exact match is found, an alternate display is shown with the matched address and the option to 'edit' the address instead of the usual address dropdown.

If multiple possible results are matched, then the full address dropdown is displayed.

\<BankDetails \/> (coming soon)

Inputs for entering bank information (sort code & account number) to set up direct debits.

Additional Notes

Bootstraped with create-react-library.

Local Development:

npm link ../path/to/host/app/node_modules/react
npm link ../path/to/host/app/node_modules/react-dom

Publishing:

npm run build && npm publish