Skip to content

Latest commit

 

History

History
120 lines (87 loc) · 5.75 KB

README.md

File metadata and controls

120 lines (87 loc) · 5.75 KB
Raw

PCF AddressFinder Widget

The PCF AddressFinder Widget is a PowerApps Component Framework (PCF) control for Dynamics 365 and Common Data Service (CDS) the uses the AddressFinder JavaScript Widget to search for New Zealand addresses.

Demo

Getting Started

To get a local copy up and running, follow these steps...

Prerequisites

Installation

  1. Signup for a free AddressFinder plan and get an API key
  2. Clone the repo
git clone https://github.com/ryanmichaeljames/pcf-addressfinder-widget.git
  1. Navigate to the src folder
cd src
  1. Install the NPM packages.
npm install

Resources

The following resources should be of help when contributing:

Usage

To install and use the AddressFinder Widget control within your Dynamics 365 or CDS instance, follow these steps...

Installation

  1. Download the latest release.
  2. Import the solution AddressFinderWidget_x_x_managed.zip file into your Dynamics 365 or CDS instance.
  3. Add the AddressFinder Widget control to the desired entity form.
  4. Add your AddressFinder API key to the API Key property. If you don't already have an API key you can register for a free account that gives you 500 free lookups a month.
  5. Map the entity's address attributes to the AddressFinder Widget's address properties.

There is a know issue where you cannot map account and contact address attributes to a PCF control's properties. Until this issue is resolved by Microsoft you can use the FormXml Manager plugin in the XrmToolBox to map the address attributes to the AddressFinder Widget control's properties. See Binding to Address Fields in a PCF Control.

Optional Properties

The following AddressFinder options are optional.

Property Type Default Description
Country Code String NZ The code of the country to search against. Supported country codes are NZ and AU.
Option: Empty Content String No addresses were found. This could be a new address, or you may need to check the spelling. Message to display to users when there are no found addresses or locations.
Option: Ignore Returns Boolean true Ignore the use of the enter key when no list item is selected.
Option: Max Results Integer 10 Maximum number of results to display.
Option: Show Addresses Boolean true Set to false to hide address results.
Option: Show Locations Boolean false Set to true to return location (street, suburb, city and region) results.
Option: Show Nearby Boolean false Enable the nearby address helper (uses device's GPS to suggest addresses at current location). This feature is only available for New Zealand addresses.
Option: Show Points of Interest Boolean false Set to true to return points of interest (e.g. hospitals, schools and churches) results. This feature is only available for New Zealand addresses.

For more information regarding the AddressFinder options see the options section of the AddressFinder Widget documentation.

New Zealand vs Australian addresses

By default, the AddressFinder Widget control will return New Zealand addresses, even if the Country Code input property is not set. To return Australian addresses the Country Code property must be set to AU.

There are a few subtle differences in the properties that are populated between New Zealand and Australian addresses. This is due to the AddressFinder API returning different properties in the search responses for each country. As a result, the following output properties are only populated by their respective countries.

Property Country
City New Zealand
Suburb New Zealand
Locality Australia
State/Territory Australia

Roadmap

See the issues for a list of proposed features (and known issues).

Contributing

Any contributions are more than welcome. 😄

  1. Fork the project
  2. Create a feature branch
git checkout -b feature/my-feature
  1. Commit your changes
git commit -m 'Added my feature'
  1. Push the feature branch to origin
git push origin feature/my-feature
  1. Open a pull request

Versioning

This project uses SemVer for versioning. For the versions available, see tags.

License

This project is distributed under the MIT License. See LICENSE more information.

Acknowledgements