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) и может быть свободно используемо любым лицом без выплат авторских вознаграждений.