Address

This component is used to display and store an address. As the user enters an address, suggestions will be made for them to select to help speed up the process and ensure an accurate address is entered.

Each field can be configured in the field definition to be required or not.

The Building Name, Civic ID, Municipality, and Regional District fields can be disabled in the field definition if some of those fields are not applicable to you.

IMPORTANT NOTE:
To use the address component, you generate and use your own API key to interact with Google’s Places and Geocoding APIs. Refer to the Google API Key for Address Component article to learn how to generate a key for yourself.

Once you have an API key, you need to add it to the UX-WASM-XX project. Open the following file in the UX-WASM-XX project, wwwroot/index.html.

Update the following script tag in the head and replace YourAPIKey with your key.

<script src="https://maps.googleapis.com/maps/api/js?key=YourAPIKey&libraries=places&v=weekly"></script>

MAUI Variations

The address component is enhanced to provide additional features if the user is using the MAUI application.

Once there is a valid address and there are coordinates available for the address the Display On Map button will be visible, the outcome of selecting this button is different when on the MAUI application opposed to the website.

MAUI App Behavior

When the Display On Map button is selected the devices default map application will be opened and directions to the address from the users current location will be displayed. If the users current location is not available then the address location is displayed on the map without directions.

Website Behavior

When the Display On Map button is selected a popup window will be displayed with a map and a pin with the location of the address. The pin can be moved to adjust the address coordinates if they’re slightly off by dragging and dropping. If the pin is moved the coordinates will be updated once the instance is saved.

Component Code

The code for this component is separated into regions to improve navigation and make it easy to follow this documentation.

Variables

These are all the variables that are used within the component. Comments are added to indicate what their purpose is.

Initialization

OnAfterRenderAsync(bool firstRender)

This method is called after the component has finished rendering. The code within checks if this is the first time the component has been rendered. If it is the first time it’s been rendered, then it initializes the DotNetObjectReference variable which will be an object reference to this component.

Then using JS Interop there is a call to the helper.js class located in the UX-WASM-Components project. Within the helper.js class the initAutocomplete function is called.

This allows address suggestions to appear as the user enters an address.

OnParametersSetAsync()

This method is triggered immediately after the component has been initialized, it is also triggered if this is an existing component that is being re-rendered because its parent component has updated.

Its purpose is to pull values and populate the component variables from the FieldUX and FieldDefinition parameters. To populate the ValueUX fields the data is pulled from DataChanges or DataDB properties of the current instance.

Update Values

ValueChanged(bool resetCoordinates)

This method is called anytime one of the address fields is updated. If the field is modifiable then It will validate the entered value. If the input is valid then ChangeXML() is called.

This method also requires a bool value to be passed, if the value passed is true then the coordinates of the current address are wiped. This is to ensure that if the user manually updates the address that the saved coordinates won’t still point to the old address, new coordinates must be generated.

ChangeXML()

This method is used to pull the current values from the address fields to generate XML. Once generated the XML is added to the instances DataChanges.

This is an example of the XML structure that is saved:

<AddressField>
    Martin Tower, 123 Melrose St, Brooklyn, NY, United States, 11206
    <BuildingName>Martin Tower</BuildingName>
    <Street>123 Melrose St</Street>
    <LineTwo>Unit 447</LineTwo>
    <Municipality>East Center</Municipality>
    <RegionalDistrict>East Center</RegionalDistrict>
    <City>Brooklyn</City>
    <Region>NY</Region>
    <Country>United States</Country>
    <PostalCode>11206</PostalCode>
    <CivicID>0092883</CivicID>
    <Latitude>40.69978469999999</Latitude>
    <Longitude>-73.9333123</Longitude>
</AddressField>

GetCoordinates()

This method is called when the Get Address Coordinates button is selected. If the field is modifiable it will attempt to take the Street, City, Province/State, and Country fields to locate the address and retrieve the coordinates for it using the Geocoding API.

If those fields all have values then a call to the helper.js class is made and the initGetAddressCoordinates function is called.

IMPORTANT NOTE: If an address is selected from the autocomplete menu the coordinates will automatically be pulled. Only if the address is manually entered or modified will the Get Address Coordinates button be available. The address can only be displayed on a map if valid coordinates can be found.

ShowMap()

This method is called when the Display On Map button is selected. It will display the address on a map.

When viewing from the website a call to the helper.js class is made and the initMap function is called. This will open a popup window with the location of the address on a map. The pin can be repositioned to update the address coordinates if it’s slightly off position.

When viewing from a MAUI application, selecting the Display On Map button will open the devices default map application with directions to the address from the users current location. If the users current location isn’t available then the address location will be displayed on the map with no directions.

JSInvokable UpdateAddressCoordinates(string coordinatesJSON, string status = “”)

This method is used to update the address coordinates when either a call is made to get new coordinates or the pin on the map is repositioned. This method is called from the helper.js classes initMap and initGetAddressCoordinates functions.

The function accepts a string that will contain the coordinates in JSON format and an optional string that will contain the status of the operation.

If the returned status is not an empty string or OK, then an error has occurred and description of what failed will be logged along with a generic error notification displayed to the user. If the operation was successful then the coordinates of the address are updated and the changes are added to the instances DataChanges ready to be saved.

JSInvokable UpdateAddress(string addressJSON)

This method is used to update the address fields when a suggested address was selected. This method is only called from the helper.js class’s initAutocomplete function located in the UX-WASM-Components project. When called it receives a JSON string that contains all the information about the selected address.

This method simply breaks apart the JSON and creates a GoogleAddress object, then uses the GoogleAddress’s properties to populate the address components fields. It also makes a call to ValueChanged() to indicate the fields have been updated so the new data will be added to the instances DataChanges ready to be saved.