jquery.kladr/README.md

jQuery Kladr

jQuery Kladr
================================================================================

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

Архитектура
--------------------------------------------------------------------------------

* **$.kladr** - ( *статичный объект* ) предоставляет методы и свойства для работы 
с сервисом.
* **$('input').kladr** - ( *плагин jQuery* ) плагин для автодополнения адреса.
* **$('input').kladrZip** - ( *плагин jQuery* ) плагин для полей с почтовым индексом.

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

* **url** - url сервиса, по умолчанию [http://kladr-api.ru/api.php] [2].
* **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').kladr*. В качестве параметра *values* принимает массив объектов КЛАДР или объект вида
*{'тип объекта' => название или id объекта}*. Второй параметр аналогичен параметру функции *getInputs*.
* **setDefault** *= function (param1, param2) {}* - устанавливает значения по умолчанию
для параметров плагина *$('input').kladr*. В качестве параметров принимает аналогично плагину либо объект
со списком изменяемых параметров, либо пару "параметр - новое значение параметра".
* **getDefault** *= function (param) {}* - возвращает значение по умолчанию для параметра плагина *$('input').kladr*.
В качестве параметра принимает название параметра плагина.
* **getInputs** *= function (selector) {}* - возвращает jQuery коллекцию полей ввода, к которым был
подключён плагин *$('input').kladr*. В качестве параметра принимает селектор, DOM элемент или же объект jQuery, в котором
будет выполнен поиск соответствующих полей, по умолчанию *body*.
* **buildAddress** *= function (objs) {}* - строит строку адреса на основании массива объектов КЛАДР.
* **getAddress** *= function (selector, build) {}* - возвращает строку адреса на основании полей ввода,
к которым был подключён плагин *$('input').kladr*. Первый параметр аналогичен параметру функции *getInputs*. В качестве второго
параметра принимает функцию, которой будет собираться строка адреса, по умолчанию *buildAddress*.

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

* **token** - токен для доступа к сервису, по умолчанию *null*.
* **key** - ключ для доступа к сервису, по умолчанию *null*.
* **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').kladr
--------------------------------------------------------------------------------

* **source** *= function (query) { return objects; }* - функция для получения
списка объектов отображаемых при автодополнении. В качестве параметра принимает
объекта запроса. По умолчанию запрашивает данные у сервиса [kladr-api.ru] [1].
Может быть переопределена для получения объектов из другого источника.
* **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').kladr
--------------------------------------------------------------------------------

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

В обработчиках событий **...Before** (*openBefore*, *closeBefore*) объявленных как параметр плагина
( *$('').kladr({openBefore: function () {}})* ) можно отменить действие плагина, если в функции
вернуть **false** ( *$('').kladr({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').kladrZip
-------------------------------------------------------------------------------

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

В качестве параметра принимает селектор, DOM элемент или же объект jQuery, в котором
будет выполнен поиск соответствующих полей адреса, по умолчанию *body*.

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

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


Примеры
--------------------------------------------------------------------------------

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

`````javascript
$('input').kladr({
	oneString: true
});
`````

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

`````javascript
$('input').kladr({
    type: $.kladr.type.city
});
`````

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

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

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

`````javascript
$('input').kladrZip('form');
`````

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


Загрузка
-------------------------------------------------------------------------------

Загрузить последнюю версию плагина себе в проект можно с помощью Bower:

`````bash
bower install jquery.kladr
`````

Сборка своей версии плагина
-------------------------------------------------------------------------------

Клонируем репозиторий плагина:

`````bash
git clone git://github.com/garakh/kladrapi-jsclient.git
`````

После внесения изменений, выполняем сборку плагина с помощью следующей команды:

`````bash
npm run build
`````

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

[1]: http://kladr-api.ru/ "КЛАДР API"
[2]: https://kladr-api.ru/api.php "API"
[3]: https://github.com/garakh/kladrapi-jsclient/tree/master/examples "Examples"