Available from 2.5.0

AddressForm

Overview

AddressForm is a component that enables users to enter a postal address in a standardized way. It can optionally be configured to interface with an address verification and autocompletion service, for example Smarty.

You can use the form to capture a new address, or edit an existing one.

AddressForm provides the following:

• Input fields for up to eight fields of address information.
• Configurable order and presence for each field.
• A drop-down input field to select between states and country sub-divisions.
• An address autocompletion screen where users can select from a drop-down list of addresses suggested by an external service.
• Text and style configurability.

Visual reference

Usage

Initialize AddressForm using AddressFormFactory and AddressFormConfiguration.

When the form is initialized using an existing address, it is configured to edit the address. If no address is provided, the bank customer can provide a new address.

You can also use AddressSuggestionConfiguration to include an address autocomplete component that enables the user to type a partial address and select the correct address from the suggestions provided.

Add an address form to your view

The AddressForm component is provided as a view controller and must be included within your view as a child view controller. The following is a simple example of how it can be configured:

private lazy var states = [
    (abbreviation: "AK", name: "Alaska"),
    (abbreviation: "AL", name: "Alabama"),
    (abbreviation: "AR", name: "Arkansas"),
    (abbreviation: "AS", name: "American Samoa"),
    (abbreviation: "AZ", name: "Arizona"),
    (abbreviation: "CA", name: "California")
]

private lazy var formConfiguration: AddressFormConfiguration = {
    .init(strings: .init(address1InputTitle: "Street address",
                         address2InputTitle: "Apartment or suite",
                         cityInputTitle: "Town/City",
                         stateInputTitle: "State",
                         stateInputPlaceholder: "Select a state",
                         zipInputTitle: "ZIP Code",
                         searchInputPlaceholder: "Start typing your address"),
         availableStates: states)
}()

private lazy var addressFormController: AddressForm = {
    AddressFormFactory.build(formConfiguration: formConfiguration)
}()

override func loadView() {
    ...

    view.addSubview(addressFormController.view)

    addChild(addressFormController)
    addressFormController.didMove(toParent: self)
}

You can also configure the form to edit an existing address as follows:

struct MyAddressType: AddressFormValues {
    ...
}

private lazy var addressFormController: AddressForm = {
    AddressFormFactory.build(formConfiguration: formConfiguration,
                             address: myAddress)
}()

The Address Form contains of five address fields, and another three extra fields are hidden by default. The order and presence can be customised by providing visibleFields array in configuration. There is a possibility to put two fields in one row by wrapping them into a compound:

private lazy var addressFormController: AddressFormConfiguration = {
    let visibleFields: [AddressField] = [
            .addressLine1,
            .addressLine2,
            .city,
            .compound(.subDivision, .zip),
            .extra1,
            .extra2,
            .extra3
        ]
    return AddressFormConfiguration(strings: addressFormStrings,
                                    availableSubDivisions: sortedStates,
                                    visibleFields: visibleFields)
}()

Support autocomplete

To use the address autocomplete functionality, you must configure AddressSuggestionConfiguration and implement AddressSearchResultsProvider. This implementation interfaces to an external service that returns a list of suggested addresses for a given search term. The address suggestion is incomplete if there is more than one entry in it, and it can be used to find all it's secondary addresses (apartments, suites). If user selects the suggestion with entries the Address Form wouldn't be populated. Instead corresponding request would be sent, and the secondary addresses would replace search results.

class AddressService: AddressSearchResultsProvider {
    func search(query: String, completion: @escaping (AddressAutocompleteResult) -> Void) {
        ...
    }

    func searchApartments(selection: AddressSuggestion, query: String, completion: @escaping AddressSuggestionCompletion) {
        ...
    }
}

...

let suggestionProvider = AddressService()

private lazy var suggestionConfiguration: AddressSuggestionConfiguration = {
    .init(suggestionProvider: suggestionProvider,
          strings: .init(addressNotFound: "Address not found? Enter manually",
                         searchBarPlaceholder: "Start typing your address"))
}()

private lazy var addressFormController: AddressForm = {
    AddressFormFactory.build(formConfiguration: formConfiguration,
                             suggestionConfiguration: suggestionConfiguration
}

Styling

The following shared styles are used with the address form:

• DesignSystem.shared.styles.textInput
• DesignSystem.shared.styles.searchInput

The following shared styles are used on the autocomplete screen:

• DesignSystem.shared.styles.searchBar
• DesignSystem.shared.styles.tableView
• DesignSystem.shared.styles.tableViewCell
• DesignSystem.shared.styles.tableViewLinkCell