Find your place with the LocationPicker from the PnP reusable React controls

Introduction

Proceeding with the appointments with the PnP React controls today I want to talk about the LocationPicker control.

If you’re interested you can find the code of this sample here.

Visual interface

As usual I’ve prepared a sample solution to demonstrate the various possible configurations of the control.

Starting with an overview of the web part here’s what we’re about to explore:

The minimal configuration instance is the instance that requires the minimum configuration to work.

The control renders a text box where the user can type the name of the address of the place that is being searched for, for example if the user is searching for “London City Airport” this can be the resulting UI:

When searching for a place the list of suggested results will be constantly updated after each key stroke.

Once that the user has found and selected the wanted place the control will be updated and will show a nice UI to represent the selection:

The LocationPicker control supports the ability to specify a default value, for example if I specify “Notre-Dame de Paris” as default value the result would be the following:

Errors happens, we all know that, and in those cases the control allows to specify the error message to be shown to the user. Specifying the error message would also change the border of the control to red:

Frequently, customization is key, the LocationPicker control offers a couple of properties to specify custom strings such as a custom label string and also a custom place holder:

One last thing that can be handy is the ability to disable the control. Say that you want to show a previously selected location without the possibility to change that selection:

Now that you have an idea of the resulting UI let’s deep dive into the code section to see how to achieve those results.

Show me the code

Prerequisites

To use the PnP React controls, first you need to install the package:

npm install @pnp/spfx-controls-react --save --save-exact

After the installation of the package you can proceed with the following instructions to use the LocationPicker control.

To use the control you first need to import it and that can be done as following:

import { LocationPicker, ILocationPickerItem } from "@pnp/spfx-controls-react/lib/LocationPicker";

Second thing to do is to declare a property, in the components properties, to pass the web part context to the component. In the sample this is achieved as follows:

import { WebPartContext } from "@microsoft/sp-webpart-base";

export interface IPnPLocationPickerProps {
  context: WebPartContext;
}

After importing the control and preparing the component properties you can start to use it. Let’s cover each of the instances in a little bit more detail.

Minimal configuration

The control offers the ability to be used specifying only the web part context. Each of the instances that we will cover has the context property set in the same way.

So, let’s see how is this control instantiated:

<LocationPicker context={context as any} />

Default value

The control exposes a property named defaultValue, this property allows a default selection of a specific location.

<LocationPicker
  context={context as any}
  defaultValue={this._getLocationByCoordinates()} />

The value for the defaultValue property must be an object of type ILocationPickerItem, this item must have two properties set and those are DisplayName and EntityType. If you prefer you can also specify the coordinates or the address line. In the sample solution, for the default value, I’ve defined the coordinates property:

private _getLocationByCoordinates(): ILocationPickerItem {
    return {
      DisplayName: "Notre-Dame de Paris",
      EntityType: "TouristAttraction",
      Coordinates: {
        Latitude: 48.8533,
        Longitude: 2.3491
      }
    };
  }

Error message

When needed, it’s possible to define an error message to be displayed. Setting this value to a value different than an empty one renders the control with a red border and also adding the error message in red at the bottom of the control itself. To add the error message simply set the property errorMessage with the error that you want to display to the user:

<LocationPicker
  context={context as any}
  errorMessage={strings.ErrorMessageText} />

Custom strings

One customization option offered by the control is the possibility to set a custom label and also a custom placeholder. Those two strings can be set using the properties label and placeholder:

<LocationPicker
  context={context as any}
  label={strings.CustomStrings.Label}
  placeholder={strings.CustomStrings.Placeholder} />

OnChange

One of the properties that you will most probably use is the onChange property. This specific property accepts a method which receive an ILocationPickerItem object and can perform whatever operation needed on that object.

<LocationPicker
  context={context as any}
  onChange={this._onChange} />

In the sample solution I just displayed, in the browser’s console, the value that is selected in the control:

private _onChange(newValue: ILocationPickerItem): void {
  console.log(newValue);
}

For example, in case the user is searching for the “Statue of Libery” string and select the suggested result, the onChange method would receive the following object:

{
    "EntityType": "LocalBusiness",
    "LocationSource": "Bing",
    "LocationUri": "https://www.bingapis.com/api/v6/localbusinesses/YN873x113882895?setLang=en-IN",
    "UniqueId": "https://www.bingapis.com/api/v6/localbusinesses/YN873x113882895?setLang=en-IN",
    "IsPreviouslyUsed": false,
    "DisplayName": "Statue of Liberty",
    "Address": {
        "Street": "Liberty Is",
        "City": "New York",
        "State": "NY",
        "CountryOrRegion": "United States",
        "PostalCode": "10004"
    },
    "Coordinates": {
        "Latitude": 40.6892,
        "Longitude": -74.0445
    }
}

Just for reference, if the user types a name or an address that has no suggestion in the control, it is possible to force the use of the inserted text as value that will be used. In case of forcing the value inserted from the user-typed text, the resulting object will have its EntityType property set to Custom and the DisplayName set to the text specified by the user:

{
  "DisplayName": "Tatooine, Outher Rim",
  "EntityType": "Custom"
}

Disabled control

In case you want to only display a certain value and not let the user change it, it’s possible to use the disabled property and set it to true. This will prevent every UI operation from changing the control value.

<LocationPicker
  context={context as any} 
  disabled={true}
  defaultValue={this._getLocationByAddress()} />

Conclusions

The LocationPicker control is a nice user experience addition in those cases when you want to allow the user to select a place specifying the address.

The UI is nice and the control is easily instantiated and used, I think you should keep it in mind for your next form that will include an address.

I didn’t cover fully the control properties, if you’re interested in knowing more you can have a look at the official documentation here.

Hope this helps!