DOCSEARCHbyAlgolia
Submit Docs

libaddressinput

repository·master·Indexed 20 days ago

https://github.com/google/libaddressinput

C++ and Java libraries that use Google's Address Data Service metadata to help developers build country-specific postal address input forms and perform address validation. The Java implementation includes a ready-to-use Android UI address input widget and AddressAutocompleteController, while the C++ version provides portable UI layout information and validation without a built-in UI or networking layer.

Tokens
6.4K
Snippets
22
Records
31
Agent score
69%

What's inside libaddressinput

  1. Overview of C++ libaddressinput

    master

    The C++ version of libaddressinput provides UI layout information and validation for address input forms.

    Important Architectural Constraints:

    • No UI: The library does not provide a user interface. The consumer is responsible for implementing the UI that uses the library's layout information.
    • No Networking/Storage: The library does not handle networking or disk storage. The consumer must provide the mechanisms to download data from the internet and store it on disk.
    • Extensibility: When including the library, you can override dependencies and include directories in libaddressinput.gypi to link against your own third-party libraries.

  2. Overview of libaddressinput

    master

    libaddressinput is a project providing two distinct libraries (C++ and Java) designed to help developers collect and handle postal addresses globally. It utilizes address metadata from Google's Address Data Service to:

    1. Generate Address Forms: Determine which input fields are required for a correct address form based on the selected country.
    2. Validate Addresses: Identify input errors such as missing required fields or invalid values.

    Key Capabilities:

    • Country-specific field requirements.
    • Real-time address validation.
    • Support for global postal address formats.

  3. Use libaddressinput in Java/Android

    master

    The Java implementation is optimized for Android but is not strictly tied to it.

    • Android: Includes a ready-to-use Android UI address input widget.
    • Java SE: Non-UI code and tests can be run in a standard Java SE environment.
    • Other Java Environments: The library is designed to be easily adaptable to other Java-based platforms.

  4. Build and run libaddressinput tests on Android

    master

    You can build the project and run tests using Gradle via the command line.

    To build the package: gradlew build

    To build the library and run tests on a connected Android device or emulator: gradlew connectedAndroidTest

    To view test runner logs, use adb logcat.

    # Build the package
./gradlew build

# Build and run tests on a connected device/emulator
./gradlew connectedAndroidTest

# View logs
adb logcat

  5. Use libaddressinput in C++

    master

    The C++ implementation is written in portable C++11 and is used in projects like Chromium. You can find the source code for the C++ library within the Chromium repository.

    https://chromium.googlesource.com/chromium/src/+/master/third_party/libaddressinput/

  6. Build and run tests for libaddressinput common parts

    master

    The non-UI components of libaddressinput are managed using the Gradle build automation tool. You can build the project and execute tests using either Android Studio or the provided Gradle Wrapper scripts (gradlew for Unix-based systems or gradlew.bat for Windows).

    To verify your installation and ensure the environment is working correctly, run the build and test commands.

    ##### On Linux / Unix / Mac
```bash
./gradlew build
./gradlew test
    On Windows
    gradlew.bat build
gradlew.bat test

  7. Integrate libaddressinput into an Android App

    master

    Follow these steps to include the libaddressinput widget and common libraries in your Android project:

    1. Clone the repository: Clone libaddressinput from GitHub.
    2. Build the artifacts: Navigate to the root folder and run ./gradlew build.
    3. Copy the libraries: Copy the generated .aar and .jar files to your project's libs folder:
      • Widget: android/build/outputs/aar/android-release.aar
      • Common libraries: common/build/libs/common.jar
    4. Import modules: Add both modules as dependencies in your Android project (use the Android Studio 'Add your library as a dependency' guide if needed).
    cd libaddressinput/
./gradlew build

# Replace 'path/to/project' with your actual project path
cp android/build/outputs/aar/android-release.aar path/to/project/app/libs/
cp common/build/libs/common.jar path/to/project/app/libs/

  8. Prerequisites for building libaddressinput for Android

    master

    To build the library and run tests on Android, you need the following environment setup:

    1. Android Studio: Recommended for development.
    2. Android SDK Tools: Set the ANDROID_HOME environment variable to the root of your SDK.
    3. Required SDK Packages:
      • Tools/Android SDK Platform-tools (Rev. 35.0.1)
      • Android 14 (API 34)
      • Extras/Android Support Library

  9. Install dependencies for C++ libaddressinput

    master

    To build the C++ version of libaddressinput, you need to install several build tools and libraries. On Debian-like distributions, you can install the required packages using apt-get.

    Required Dependencies:

    • GYP: Generates build files (version must be at least 0.1~svn1395).
    • Ninja: Executes the build files.
    • GTest: Used for unit tests.
    • Python: Used by GRIT for localization file generation.
    • RE2: Used for validating postal code formats (version must be at least 20140111+dfsg-1).
    sudo apt-get install gyp ninja-build libgtest-dev python3 libre2-dev

  10. Build the C++ libaddressinput library

    master

    Building the library is a two-step process: first, use gyp to generate the Ninja build files, then use ninja to execute the build.

    To ensure gyp generates Ninja files, you must set the GYP_GENERATORS environment variable to 'ninja'.

    If you need to override paths defined in the .gyp files (for example, to point to custom locations for gtest), set the GYP_DEFINES environment variable before running the gyp command.

    # Standard build process
export GYP_GENERATORS='ninja'
gyp --depth .
ninja -C out/Default

# Building with custom dependency paths
export GYP_DEFINES="gtest_dir='/xxx/include' gtest_src_dir='/xxx'"
gyp --depth .
ninja -C out/Default

  11. Understand AddressUiComponent in Android

    master

    In the Android implementation of libaddressinput, an AddressUiComponent represents a single input element within an address widget UI. It abstracts the underlying Android View (such as an EditText, AutoCompleteTextView, or Spinner) to provide a consistent interface for managing address fields.

    Key characteristics:

    • UI Types: A component can be an EDIT type (a text box) or a SPINNER type (a drop-down menu).
    • Dynamic Behavior: The component type is determined by the number of candidates available. If initializeCandidatesList is called with more than one candidate, the component automatically switches to UiComponent.SPINNER.
    • Field Hierarchy: Components can have a parentId. When a parent component is updated (e.g., a Country change), its dependent child components (e.g., Admin Area or Locality) should be updated accordingly. The library handles common dependencies like DEPENDENT_LOCALITY depending on LOCALITY, LOCALITY depending on ADMIN_AREA, and ADMIN_AREA depending on COUNTRY.

  12. Use AddressAutocompleteController for Android address autocomplete

    master

    The AddressAutocompleteController manages the lifecycle of address autocomplete in an Android UI. It connects an AutoCompleteTextView to an AddressAutocompleteApi for fetching predictions and a PlaceDetailsApi for retrieving full address data when a user selects a prediction.

    To use it, instantiate the controller with the required APIs, attach it to your AutoCompleteTextView using setView(), and provide an OnAddressSelectedListener to handle the resulting AddressData.

    // Assuming context, autocompleteApi, and placeDetailsApi are already initialized
AddressAutocompleteController controller = new AddressAutocompleteController(
    context, 
    autocompleteApi, 
    placeDetailsApi
);

controller.setView(myAutoCompleteTextView)
          .setOnAddressSelectedListener(addressData -> {
              // Handle the selected address data here
              Log.d("App", "Selected address: " + addressData.toString());
          });