Skip to content

Latest commit

 

History

History
210 lines (171 loc) · 15.5 KB

README.md

File metadata and controls

210 lines (171 loc) · 15.5 KB
Raw

jQuery плагин для kladr-api.ru

Плагин для автодополнения полей адреса при вводе.
В качестве источника данных используется сервис [kladr-api.ru].

Архитектура

  • $.fias — ( статичный объект ) предоставляет методы и свойства для работы с сервисом.
  • $('input').fias — ( плагин jQuery ) плагин для автодополнения адреса.
  • $('input').fiasZip — ( плагин jQuery ) плагин для полей с почтовым индексом.

Свойства объекта $.fias

  • url — url сервиса, по умолчанию [http://kladr-api.ru/api.php].
  • token — токен (для доступа к платным серверам)
  • timeout — таймаут для запросов (по умолчанию 3000)
  • type — перечисление используемых типов объектов. Список значений: region (область, регион), district (район), city (населённый пункт), street (улица), building (строение).
  • typeCode — перечисление используемых типов населённых пунктов. Список значений: city (город), settlement (посёлок), village (деревня, село).
  • validate = function (query) {} — выполняет проверку корректности объекта запроса.
  • api = function (query, callback) {} — непосредственно выполняет запрос к сервису. В качестве параметров принимает объект запроса и функцию, которой будет передан ответ сервиса.
  • check = function (query, callback) {} — проверяет существование объекта. В качестве параметров принимает объект запроса и функцию, которой будет передан объект (если он существует) либо false.
  • setValues = function (values, selector) {} — устанавливает значения для полей, к которым подключён плагин $('input').fias. В качестве параметра values принимает массив объектов КЛАДР или объект вида {'тип объекта' => название или id объекта}. Второй параметр аналогичен параметру функции getInputs.
  • setDefault = function (param1, param2) {} — устанавливает значения по умолчанию для параметров плагина $('input').fias. В качестве параметров принимает аналогично плагину либо объект со списком изменяемых параметров, либо пару "параметр - новое значение параметра".
  • getDefault = function (param) {} — возвращает значение по умолчанию для параметра плагина $('input').kladr. В качестве параметра принимает название параметра плагина.
  • getInputs = function (selector) {} — возвращает jQuery коллекцию полей ввода, к которым был подключён плагин $('input').fias. В качестве параметра принимает селектор, DOM элемент или же объект jQuery, в котором будет выполнен поиск соответствующих полей, по умолчанию body.
  • buildAddress = function (objs) {} — строит строку адреса на основании массива объектов КЛАДР.
  • getAddress = function (selector, build) {} — возвращает строку адреса на основании полей ввода, к которым был подключён плагин $('input').fias. Первый параметр аналогичен параметру функции getInputs. В качестве второго параметра принимает функцию, которой будет собираться строка адреса, по умолчанию buildAddress.

Параметры плагина $('input').fias

  • token — токен для доступа к сервису. На бесплатном тарифе можно не указывать.
  • type — тип подставляемых объектов, по умолчанию null.
  • typeCode — тип подставляемых населённых пунктов, по умолчанию null. Может быть использован только если type == 'city'.
  • parentType — тип родительского объекта, по умолчанию null.
  • parentId — идентификатор родительского объекта, по умолчанию null.
  • limit — количество отображаемых в выпадающем списке объектов, по умолчанию 10.
  • oneString — включить ввод адреса одной строкой, по умолчанию false.
  • withParents — получить объект вместе с родителями, по умолчанию false.
  • parentInput — селектор, DOM элемент или же объект jQuery, в котором находится поле ввода родительского объекта, по умолчанию null.
  • verify — проверять введённые данные, по умолчанию false.
  • spinner — отображать ajax-крутилку, по умолчанию true.
  • current — текущий, выбранный объект КЛАДР, только для чтения.
  • controller - контроллер плагина, только для чтения.

Методы плагина $('input').fias

  • source = function (query) { return objects; } — функция для получения списка объектов отображаемых при автодополнении. В качестве параметра принимает объекта запроса. По умолчанию запрашивает данные у сервиса [kladr-api.ru] Может быть переопределена для получения объектов из другого источника.
  • labelFormat = function (obj, query) { return label; } — функция для форматирования значений в списке. В качестве параметров принимает obj — объект КЛАДР, query – объект запроса.
  • valueFormat = function (obj, query) { return label; } — функция для форматирования подставляемых в поле ввода значений. В качестве параметров принимает obj – объект КЛАДР, query – объект запроса.
  • showSpinner = function ($spinner) {} — функция, выводящая ajax-крутилку. В качестве параметра принимает jQuery объект ajax-крутилки.
  • hideSpinner = function ($spinner) {} — функция, скрывающая ajax-крутилку. В качестве параметра принимает jQuery объект ajax-крутилки.

События плагина $('input').fias

Во все события в качестве контекста (this) передаётся текущее поле ввода.

В обработчиках событий ...Before (openBefore, closeBefore) объявленных как параметр плагина ( $('').fias({openBefore: function () {}}) ) можно отменить действие плагина, если в функции вернуть false ( $('').fias({openBefore: function () { return false; }}) ).

  • openBefore = function () {} — возникает перед открытием списка объектов. Доступно как событие kladr_open_before поля ввода.
  • open = function () {} — открыт список объектов. Доступно как событие kladr_open поля ввода.
  • closeBefore = function () {} — возникает перед закрытием списка объектов. Доступно как событие kladr_close_before поля ввода.
  • close = function () {} — закрыт список объектов. Доступно как событие kladr_close поля ввода.
  • sendBefore = function (query) {} — возникает перед отправкой запроса к сервису. В параметре передаётся объект запроса. Доступно как событие kladr_send_before поля ввода.
  • send = function () {} — отправлен запрос к сервису. Доступно как событие kladr_send поля ввода.
  • receive = function () {} — получен ответ от сервиса. Доступно как событие kladr_receive поля ввода.
  • selectBefore = function () {} — возникает перед изменением текущего объекта. Доступно как событие kladr_select_before поля ввода.
  • select = function (obj) {} — выбран объект в списке. В параметре передаётся текущий, выбранный объект КЛАДР. Доступно как событие kladr_select поля ввода.
  • checkBefore = function () {} — возникает перед проверкой введённых пользователем данных. Вызывается только если параметр verify = true. Доступно как событие kladr_check_before поля ввода.
  • check = function (obj) {} — проверен введённый пользователем объект. Вызывается только если параметр verify = true. В параметре передаётся текущий объект КЛАДР. Доступно как событие kladr_check поля ввода.
  • change = function (obj) {} — изменился текущий объект (current). В параметре передаётся текущий объект КЛАДР. Доступно как событие kladr_change поля ввода.

Методы контроллера плагина $('input').kladr

  • setValueByName = function (name) { return controller; } — устанавливает значение поля ввода. В качестве параметра принимает имя объекта.
  • setValueById = function (id) { return controller; } — устанавливает значение поля ввода. В качестве параметра принимает id объекта.
  • setValueByObject = function (obj) { return controller; } — устанавливает значение поля ввода. В качестве параметра принимает объект КЛАДР.
  • setValue = function (value) { return controller; } — устанавливает значение поля ввода. Если в качестве параметра передана строка, значение будет установлено методом setValueByName. Если передано число методом setValueById, если объект методом setValueByObject.
  • clear = function () { return controller; } — очищает поле ввода.

Пример использования контроллера можно посмотреть в папке [examples] 3.

Плагин $('input').fiasZip

Плагин $('selector').kladrZip выполняет проверку введённого пользователем почтового индекса. В случае если введённый индекс соответствует реальному адресу, плагин подставляет объекты этого адреса в другие поля формы (см. пример формы для ввода адреса в папке [examples] 3).

Параметры:

$('selector').fiasZip(selector, onFoundCallback(obj));
  • selector — DOM элемент или же объект jQuery, в котором будет выполнен поиск соответствующих полей адреса, по умолчанию body.
  • onFoundCallback(obj) — коллбек вызывается, когда по индексу найден адрес. obj — объект с адресом

Структура папок, файлов

  • jquery.fias.min.js — Минимифицированный код плагина
  • jquery.fias.min.css — Минимифицированные стили
  • examples — Примеры
  • images — Изображения плагина
  • src — Исходный код плагина

Примеры

Автодополнение для ввода адреса одной строкой:

$('input').fias({
	oneString: true
});

Автодополнение городами России:

$('input').fias({
    type: $.fias.type.city
});

Изменение подписи при выборе района:

$('input').fias({
    type: $.fias.type.district,
    select: function(obj){
        $('label').text(obj.type);
    }
});

Проверка вводимого пользователем почтового индекса

$('input').fiasZip('form');

Более подробные примеры можно найти в папке [examples] 3.

Лицензия

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