ws-address-search v1.2.3

General info

For changelog, see CHANGELOG.md file

If you are integrating this component in a React app, see "How to integrate with a react app" below. Otherwise, see "How to integrate (non-react app)".

How to integrate (non-react app)

Adding the component

You need to add the CSS and script tags with the address autocomplete component like this:

<link
  rel="stylesheet"
  type="text/css"
  href="https://s3-eu-west-1.amazonaws.com/ws-address-search/prod/1.0.0/css/ws-addr-search.css"
/>
<script   
  src="https://s3-eu-west-1.amazonaws.com/ws-address-search/prod/1.0.0/js/ws-addr-search.min.js?api-key=YOUR_API_KEY">
</script>

Make sure to include your API key in the end.

And, where you want the autocomplete component, you should add a div like this:

<div data-role="ws-address-search"></div>

Once the page loads, the component will be automatically rendered inside this div.

Styling

The component is included with a basic "compressed" stylesheet. In case you need to customize it, we can provide the scss file for customization.

Configurations

After the inclusion of the library, you can define some configurations using WSAddressSearch.config object, like this:

WSAddressSearch.config = {
  "carrierUuid": "123-321-312-121"
  "api-key": ""
}

carrierUuid

Set this config to filter the results for only a given carrier UUID (instead of the result for all carriers)

Events

After the inclusion of the library, you can listen for events in the component using

WSAddressSearch.addEventListener('event', function(value) {
  // Do whatever is needed
});

Where 'event' can be one of the following event types:

address-changed

Every time the user types something, this event will be triggered with one parameter:

{
  "street": "Corso Italia, Milano, Milano",
  "number": "20"
}

The content is exactly what user typed.

address-selected

Once the user finishes typing and selecting both the street and the number, right before the component calls the API to fetch availability, this event is triggered.

This event is useful to show a loading animation or something similar to the user, in order to let him know that the availability is being fetched.

The callback function will be called with the following parameter:

{
  "street": {"id": 146223, "description": "Corso Italia, Milano, Milano"},
  "number": {"id": "22", "description":"22"}
}

The content is the address components in Walletsaver's system.

landline-availability-ready

This event is triggered once the availability of landlines of carriers is ready.

The JSON is the complete availability. It includes:

• Carrier summary: The list of carriers, max speed per technology and list of available technologies
• Services available: Services that provides the technologies, with details about max speed, estimated speed, cabinet and central position and distance, when available.

Here is an example of event received by the callback:

{
  "carriers":[
    {
      "carrier":{
        "name":"Wind Infostrada",
        "img":"https://walletsaver-filesupload.s3.amazonaws.com:443/media/carrier_imgs/infostrada_300x300.png",
        "url":"http://bit.ly/infostrada_ws"
      },
      "max_speeds":{
        "fiber":0,
        "adsl":20480
      },
      "technologies":{
        "ADSL":true,
      }
    },
    {
      "carrier":{
        "name":"Vodafone",
        "img":"https://walletsaver-filesupload.s3.amazonaws.com:443/media/carrier_imgs/Vodafone_300x300.png",
        "url":"http://bit.ly/1ZOmJfH"
      },
      "max_speeds":{
        "fiber":0,
        "adsl":20480
      },
      "technologies":{
        "ADSL":true,
      }
    },
    {
      "carrier":{
        "name":"TIM",
        "img":"https://walletsaver-filesupload.s3.amazonaws.com:443/media/carrier_imgs/TIM_300x300.png",
        "url":"http://bit.ly/1YoWtKc"
      },
      "max_speeds":{
        "fiber":1024000,
        "adsl":20480
      },
      "technologies":{
        "FTTH":true,
        "ADSL":true
      }
    },
    {
      "carrier":{
        "name":"Tre",
        "img":"https://walletsaver-filesupload.s3.amazonaws.com:443/media/carrier_imgs/Tre_300x300.png",
        "url":"http://bit.ly/tre-from-app"
      },
      "max_speeds":{
        "fiber":0,
        "adsl":20480
      },
      "technologies":{
        "ADSL":true,
      }
    },
    {
      "carrier":{
        "name":"Fastweb",
        "img":"https://walletsaver-filesupload.s3.amazonaws.com:443/media/carrier_imgs/Fastweb_300x300.png",
        "url":"http://bit.ly/fast-tariffa"
      },
      "max_speeds":{
        "fiber":0,
        "adsl":20480
      },
      "technologies":{
        "ADSL":true,
      }
    },
    {
      "carrier":{
        "name":"Tiscali Mobile",
        "img":"https://walletsaver-filesupload.s3.amazonaws.com:443/media/carrier_imgs/Tiscali_NEW_300x300.png",
        "url":"http://bit.ly/tisca-from-app"
      },
      "max_speeds":{
        "fiber":1024000,
        "adsl":20480
      },
      "technologies":{
        "FTTH":true
      }
    }
  ]
}

How to integrate with a react app

1. In your app project, run yarn add ws-address-search-web
2. Import the address search component:

   import { AddressSearch } from 'ws-address-search';

3. Place the component where you wish to use it:

   <div>
     <AddressSearch
       apiKey="YOUR_API_KEY
       carrierUuid="123-321-123"
       onAddressChange={this.onAddressChange.bind(this)}
       onAddressSelected={this.onAddressSelected.bind(this)}
       onLandlineAvailabilityReady={this.onLandlineAvailabilityReady.bind(this)}
       className="additional-css-class"
       streetInputText="Default street name"
       numberInputText="22"
     />
   </div>

   Properties:
   • apiKey: Mandatory. The API key used to connect to backend services
   • carrierUuid: Optional. Use this attribute to filter for specific carrier's availability
   • onAddressChange: Callback to be called when user types something in the input boxes
   • onAddressSelected: Callback to be called when the user finishes selecting an address
   • onLandlineAvailabilityReady: Callback that will receive the API data for availability
   • className: Additional CSS classes to style the component
   • streetInputText: Initial text of street field (optional)
   • numberInputText: Initial text of civic number field (optional)
4. You also need to add the styles to your project. The stylesheet is provided in this package as a SCSS file. You can just import it in your own SCSS stylesheet, as following: @import "ws-address-search/lib/js/components/styles.scss";. Then, customise the stylesheet it as you need.

5. And implement the methods to listen for the events that will happen in the AddressSearch component, like this:

   onAddressChange({ typed }) {
     console.log('address changed: ', typed.street, typed.number);
   }
   
   onAddressSelected({ street, number }) {
     console.log('address selected', street, number);
   }
   
   onLandlineAvailabilityReady(availabilityData) {
     console.log('availability data', availabilityData);
   }

   The availabilityData provided by the onLandlineAvailabilityReady callback has the same format as the API.