No description or website provided.
JavaScript CSS
Latest commit c37ba01 Sep 11, 2013 @xescoder xescoder Merge pull request #12 from xescoder/master
edit README.md

README.md

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

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

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

  • token - токен для доступа к сервису kladr-api.ru, по умолчанию равен null
  • key – ключ для доступа к сервису kladr-api.ru, по умолчанию равен 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, результат возвращает в функцию 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) и может быть свободно используемо любым лицом без выплат авторских вознаграждений.