KLADR form integration

Synopsis

This module provides form integration with the KLADR API for Russian location codes. These codes are used, for example, by a number of shipping companies to determine price and schedule.

The module provides callbacks for autocomplete in forms, as well as a string-to-KLADR function for retrieving autocompleted data.

Because this is a dev release, the localization file is not available on localize.drupal.org. You can download it below in the attachments and import it under admin/config/regional/translate/import.

Requirements

No module dependencies. However, this module does not provide standalone functionality, but integrates with your address form.

Other requirements:

We hope that the "security advisory" will go away after first audit of the module. The module is built to security standards to the best of our knowledge.

Similar projects

There is a project https://drupal.org/project/kladr, but it has no recent releases and appears to be inactive.

Restrictions

If you need KLADR from text addresses (e.g. saved in Ubercart config earlier), it is
highly recommended to reenter the values after enabling this module to ensure that the
KLADR search will work on the string.

Known problems

Mozilla and some other browsers do not allow disabling browser-based autocomplete. This can cause the street field, for example, to return options consistent with the previous city field value, but not with the present one. If the user enters additional characters (so that the query is new to browser-based autocomplete), then the autocomplete defaults to the Drupal autocomplete and this code. We are actively working to fix this.

Usage

The variables need to be set up at admin/config/kladr/settings in order to enable the module to connect into the form fields.

There are also the following functions provided:

• kladr_form_code_from_name($city, $street = ''): Return the KLADR for the city or city+street. If not found, NULL is returned.
• hook_kladr_form_city_search($country, $str): Some systems extend KLADR and generate their own codes for places in other countries. This hook will be called at the beginning of kladr_form_autocomplete_city to handle such cases. The return value determines what kladr_form_autocomplete_city does further. Args are as follows:
  • The code for selected $country from your module. You need to test this and determine if Russian Federation is selected or not.
  • City search $str

  Your function needs to return an empty array if search defaults to the KLADR module; i.e., Russian Federation; otherwise array (your_module_key => array (city => city, ...)). The inner array can be empty if no cities are found.

• hook_kladr_form_street_search($country, $city, $str): similar to hook_kladr_form_city_search, but the strings for city and street are provided. The behavior is like with hook_kladr_form_city_search