Skip to content

Latest commit

 

History

History
317 lines (281 loc) · 14.8 KB

README_RU.md

File metadata and controls

317 lines (281 loc) · 14.8 KB

coordinates-picker

Данный модуль позволяет отобразить на карте (Google Maps) местоположение введённого адреса, а так же сохранить координаты найденного места в отдельное поле в произвольном формате.

Параметры

Параметр Тип Описание
fields* jQuery Поля формы из которых составляется адрес. Конечный адрес получается путём конкатенации полей выборки, разделяемых запятой.
container* jQuery Элемент div в котором будет отображаться карта.
coordinates* jQuery Поле формы, в которое будут помещаться координаты адреса. Если данное поле в момент инициализации содержит данные, то место по этим координатам будет показано и отмечено маркером.
format string Формат, в котором координаты буду сохраняться в текстовом поле. По умолчанию установлен формат lng lat, где: lat - широта, lng - долгота. Данный формат позволяет легко подготовить поле для его сохранения в СУБД как объект POINT: PointFromText('POINT(".$coordinates.")').
center google.maps.LatLng|Array Координаты центра при инициализации карты. Используются, если при инициализации модуля все поля адреса и поле координат являются пустыми.
selectValue boolean По умолчанию плагин берёт значение для элементов select не методом val(), а извлекает текст из выбранной опции. Так сделано потому, что в большинстве случаев тэг option в атрибуте value содержит некие идентификаторы, а не отображаемые значения. Например: <option value="1">Россия</option>. Установка этого параметра в false отменяет такое поведение.
zooms object Объект значений уровней мастабов, который может содержать свойства:
  • initial (инициализация),
  • country (точность до страны),
  • locality (точность до города)
  • route (точность до улицы),
  • street_address (точность до дома).
marker object Объект параметров для маркера. (Параметры соответствуют Google Maps API).
map object Объект параметров для карты. (Параметры соответствуют Google Maps API).

Методы

Метод Возвращаемое значение Описание
getMap() google.maps.Map Возвращает объект карты.
getMarker() google.maps.Marker|null Возвращает объект маркера (если маркера не существует, возвращается null).
getPosition() google.maps.LatLng|null Возвращает объект широты и долготы или null.
getPoint(format) string Возвращает координаты найденной точки в указаном формате. Если необязательный параметр format не передан, то координаты форматируются в соответствии с настройками формата при инициализации. (Может быть пустой строкой, если маркера не существует).

События

Событие Описание
viewchange Событие срабатывает после смены вида карты (масштаба и/или центра). Ручное манипулирование картой не учитывается.
coordschange Событие срабатывает после определения/изменения координат указанного места. Событие содержит свойства marker и position.
geocodingstart Событие срабатывает во время запуска процесса геокодирования, которое в свою очередь запускается после каждого изменения адресного поля. Событие содержит свойство address.
geocodingend Событие срабатывает по завершении процесса геокодирования. Событие содержит свойство address. Так же событие содержит свойства status и results.

Свойства событий

Свойство Тип Событие Описание
map google.maps.Map все события Объект карты google.maps.Map
mapCenter google.maps.LatLng все события Объект широты и долготы google.maps.LatLng
mapZoom integer все события Текущий уровень масштаба
marker google.maps.Marker|null coordschange Объект маркера google.maps.Marker или null
position google.maps.LatLng|null coordschange Объект широты и долготы google.maps.LatLng или null
address string geocodingstart, geocodingend Адрес для начатого или завершённого процесса геокодирования.
status string geocodingend Статус процесса геокодирования. Соответствует свойству status объекта google.maps.Geocoder.
results object geocodingend Результаты процесса геокодирования. Соответствует свойству results объекта google.maps.Geocoder.

Примеры подключения

Модуль можно загрузить одним из трёх способов:

  • скопировать код из репозитория в свой проект
  • получить код из CDN:
<script type="text/javascript" src="//cdnjs.cloudflare.com/ajax/libs/coordinates-picker/1.0.0/coordinates-picker.js"></script>
<script type="text/javascript" src="//cdnjs.cloudflare.com/ajax/libs/coordinates-picker/1.0.0/coordinates-picker.min.js"></script>
<!-- страница проекта на cdnjs.com: https://cdnjs.com/libraries/coordinates-picker -->
  • установить модуль через Bower:
bower install coordinates-picker

Для наглядности в примерах будет использоваться следующая структура проекта:

├── assets
│   ├── images
│   │   └── marker.png
│   └── scripts
│       ├── amd
│       │   ├── main.js
│       │   ├── require.config.js
│       │   └── requirejs.async.js
│       ├── CoordinatesPicker.js
│       └── main.js
└── index.php

Модуль имеет зависимости от jQuery и Google Maps, так же модуль поддерживает AMD загрузку. Поэтому подключение модуля может осуществляться одним из двух способов:

Обычный способ

Фрагмент файла index.html

<script type="text/javascript" src="//cdnjs.cloudflare.com/ajax/libs/jquery/1.11.1/jquery.min.js"></script>
<script type="text/javascript" src="//maps.google.com/maps/api/js?sensor=false&amp;language=ru"></script>
<script type="text/javascript" src="/assets/scripts/CoordinatesPicker.js"></script>
<script type="text/javascript" src="/assets/scripts/main.js"></script>

AMD (используя RequireJS)

Фрагмент файла index.html

<script data-main="/assets/scripts/amd/main" src="//cdnjs.cloudflare.com/ajax/libs/require.js/2.1.11/require.min.js"></script>
<script src="/assets/scripts/amd/require.config.js"></script>

Файл /assets/scripts/amd/require.config.js

require.config({
    paths: {
        async: 'requirejs.async',
        coordinatespicker: '../CoordinatesPicker',
        jquery: '//cdnjs.cloudflare.com/ajax/libs/jquery/1.11.1/jquery.min',
        googlemaps: 'https://maps.google.com/maps/api/js?sensor=false&amp;language=ru'
    }
});

define('googlemaps', ['async!googlemaps'], function() {
    return window.google;
});

Фрагмент файла /assets/scripts/amd/main.js

require(['jquery', 'googlemaps', 'coordinatespicker'], function($, google, coordinatesPicker) {
    // см. "Пример использования"
});

Пример использования

Фрагмент файла index.html

<form id="institution-form">
    <select id="country" name="country" class="address-part">
        <option value="">Страна</option>
        <option value="1">Россия</option>
        <option value="2">США</option>
        <option value="3">Польша</option>
        <option value="4">Казахстан</option>
        <option value="5">Монголия</option>
    </select>
    <input type="text" id="city" name="city" class="address-part" placeholder="Город"/>
    <input type="text" id="street" name="street" class="address-part" placeholder="Улица"/>
    <input type="text" id="house" name="house" class="address-part" placeholder="Дом"/>
    <input type="text" id="coordinates" name="coordinates" readonly/>
</form>

<div>
    <div style="width: 500px; height: 500px;"></div>
</div>

Использование модуля в файле /assets/scripts/main.js или /assets/scripts/amd/main.js

// При AMD загрузке вместо BarinBritva.CoordinatesPicker необходимо использовать имя, 
// данное при объявлении зависимости, в даннном примере - coordinatesPicker
var coordinatesPicker = new BarinBritva.CoordinatesPicker({
    fields: $('.address-part'),
    container: $('#map'),
    coordinates: $('#coordinates'),
    format: 'lng,lat',
    center: new google.maps.LatLng(53.517, 49.417),
    zooms: {
        initial: 9,
        country: 11,
        locality: 14,
        route: 16,
        street_address: 18
    },
    marker: {
        draggable: true,
        animation: null,
        icon: '/assets/images/marker.png'
    },
    map: {
        disableDefaultUI: false
    }
});

Демо

Демо модуля можно посмотреть здесь.