garakh/kladrapi-jquery

jQuery виджет "КЛАДР в облаке"

Виджет jQuery UI для автодополнения адреса при вводе. Виджет унаследован от $.ui.autocomplete, в качестве источника данных используется сервис [kladr-api.ru] 1

Опции виджета

• token - токен для доступа к сервису [kladr-api.ru] 1, по умолчанию равен null
• key – ключ для доступа к сервису [kladr-api.ru] 1, по умолчанию равен null
• type – тип объектов для подстановки, по умолчанию $.ui.kladrObjectType.REGION
• parentType – тип родительского объекта для ограничения области поиска, по умолчанию $.ui.kladrObjectType.REGION
• parentId – код родительского объекта для ограничения области поиска, по умолчанию равен null - область поиска не ограничивается
• withParents – получить объект вместе с родителями, по умолчанию false
• limit – количество выводимых в выпадающем списке элементов
• label = function( obj, query) { return label; } – функция для получения подписей, в качестве параметров принимает obj – объект КЛАДР, query – текущее значение поля ввода
• value = function( obj, query) { return label; } – функция для получения подставляемых значений, в качестве параметров принимает obj – объект КЛАДР, query – текущее значение поля ввода
• select = function( event, ui ){} – функция вызываемая при событии выбора пользователем значения для автодополнения, в поле ui.item.obj – передаётся выбранный пользователем объект КЛАДР

Перечисление $.ui.kladrObjectType

• $.ui.kladrObjectType.REGION - область, регион
• $.ui.kladrObjectType.DISTRICT - район
• $.ui.kladrObjectType.CITY - населённый пункт
• $.ui.kladrObjectType.STREET - улица
• $.ui.kladrObjectType.BUILDING - дом, строение

Формат объекта КЛАДР

{
	id: "2900000100000", // Код объекта
	name: "Архангельск", // Название объекта
	zip: "163000",       // Почтовый индекс объекта
	type: "Город",       // Тип объекта (подпись) полностью
	typeShort: "г",      // Тип объекта (подпись) коротко
	parents: [           // Массив родительских объектов
		{
			id: "2900000000000",
			name: "Архангельская",
			zip: null,
			type: "Область",
			typeShort: "обл"
		}
	]
}

Служебная функция $.kladrCheck

Функция $.kladrCheck( options, callback ) проверяет существование объекта с параметрами options. Если объект существует, он возвращается в функцию callback. В качестве options принимает объект с параметрами запроса.

Список возможных параметров:

• token - токен для доступа к сервису
• key – ключ для доступа к сервису
• type – тип объекта
• value – название объекта
• parentType – тип родительского объекта
• parentId – код родительского объекта

Служебная функция $.kladrapi

Функция $.kladrapi( options, callback ) делает запрос к сервису [kladr-api.ru] 1, результат возвращает в функцию callback. В качестве options принимает объект с параметрами запроса.

Список возможных параметров:

• token - токен для доступа к сервису
• key – ключ для доступа к сервису
• regionId – код региона
• districtId – код района
• cityId – код города
• streetId – код улицы
• buildingId – код строения
• query – строка для поиска по названию
• contentType – тип объекта для поиска
• withParent – вернуть объекты вместе с родителями, если 1 то в каждый объект будет добавлено поле parents содержащее список объектов-родителей объекта
• limit – ограничение количества возвращаемых объектов, по умолчанию равно 2000

Примеры

Простое автодополнение города

$( "input" ).kladr({
        token: '51dfe5d42fb2b43e3300006e',
        key: '86a2c2a06f1b2451a87d05512cc2c3edfdf41969',
        type: $.ui.kladrObjectType.CITY
});

Автодополнение городами из Архангельской области (код КЛАДР 2900000000000)

$( "input" ).kladr({
        token: '51dfe5d42fb2b43e3300006e',
        key: '86a2c2a06f1b2451a87d05512cc2c3edfdf41969',
        type: $.ui.kladrObjectType.CITY,
        parentType: $.ui.kladrObjectType.REGION,
        parentId: "2900000000000"
});

Автодополнение городами России, со сменой подписи при выборе города

$( "input" ).kladr({
        token: '51dfe5d42fb2b43e3300006e',
        key: '86a2c2a06f1b2451a87d05512cc2c3edfdf41969',
        type: $.ui.kladrObjectType.CITY,
        select: function( event, ui ) {
                $( "label" ).text( ui.item.obj.type );
        }
});

Более подробные примеры можно посмотреть в папке examples

Лицензия

Решение распространяется под лицензией «Общественное достояние» (Public Domain) и может быть свободно используемо любым лицом без выплат авторских вознаграждений.

kladrapi-jquery's Issues

Весь адрес передать в форме

В расширенном примере есть текстовое представление адреса и выбранный объект, как вставить эти значения
Код:
Почтовый индекс:
регион
Название:
Тип: дом
Тип коротко:

в input type="hidden" , чтобы я смог передать эти значения скрипту PHP?

[enhancement] Add missing bower.json.

Hey, maintainer(s) of garakh/kladrapi-jquery!

We at VersionEye are working hard to keep up the quality of the bower's registry.

We just finished our initial analysis of the quality of the Bower.io registry:

7530 - registered packages, 224 of them doesnt exists anymore;

We analysed 7306 existing packages and 1070 of them don't have bower.json on the master branch ( that's where a Bower client pulls a data ).

Sadly, your library garakh/kladrapi-jquery is one of them.

Can you spare 15 minutes to help us to make Bower better?

Just add a new file bower.json and change attributes.

{
  "name": "garakh/kladrapi-jquery",
  "version": "1.0.0",
  "main": "path/to/main.css",
  "description": "please add it",
  "license": "Eclipse",
  "ignore": [
    ".jshintrc",
    "**/*.txt"
  ],
  "dependencies": {
    "<dependency_name>": "<semantic_version>",
    "<dependency_name>": "<Local_folder>",
    "<dependency_name>": "<package>"
  },
  "devDependencies": {
    "<test-framework-name>": "<version>"
  }
}

Read more about bower.json on the official spefication and nodejs semver library has great examples of proper versioning.

NB! Please validate your bower.json with jsonlint before commiting your updates.

Thank you!

Timo,
twitter: @versioneye
email: [email protected]
VersionEye - no more legacy software!