Some marker text.
' + } + ] +}); +``` + +That's all! + + +## Parameters description + + +### `jQuery.fn.ddMap(params)` + +* `params` + * Desctription: The parameters. + * Valid values: `objectPlain` + * **Required** + +* `params.markers` + * Desctription: Array of markers to be put on the map. + * If there is more than one marker, the map will be auto-scaled to make all the markers visible. + * Also, a pair of coordinates still can be passed (like it was in 1.2 and earlier). + * Valid values: `array` + * **Required** + +* `params.markers[i]` + * Desctription: A marker data. + * Valid values: `objectPlain` + * **Required** + +* `params.markers[i].latLng` + * Desctription: Marker coordinates (latitude and longitude). + * Valid values: `array` + * **Required** + +* `params.markers[i].content` + * Desctription: Content of marker popup. HTML tags are supported. + * Valid values: `string` + * Default value: `''` + +* `params.apiKey` + * Desctription: Yandex Maps API key. + _For now it is working without key, but Yandex mark it as required, so it is recommended to set it._ + * Valid values: `string` + * Default value: — + +* `params.defaultZoom` + * Desctription: Default map zoom. + * Valid values: `integer` + * Default value: `15` + +* `params.defaultType` + * Desctription: Default map type. + * Valid values: + * `'map'` — schematic map + * `'satellite'` — satellite map + * `'hybrid'` — hybrid map + * Default value: `'map'` + +* `params.scrollZoom` + * Desctription: Allow zoom by mouse wheel. + * Valid values: `boolean` + * Default value: `false` + +* `params.mapCenterOffset` + * Desctription: Center offset of the map with respect to the center of the map container in pixels. + * Valid values: `array` + * Default value: `[0, 0]` + +* `params.markerOptions` + * Desctription: Marker options. + * Valid values: `objectPlain` + * Default value: `{}` + +* `params.controls` + * Desctription: An array of controls to be added onto the map. + * Valid values: `array` + * Default value: `[{name: 'zoomControl'},{name: 'typeSelector'},{name: 'fullscreenControl'},{name: 'geolocationControl'},{name: 'rulerControl'}]` + +* `params.mapOptions` + * Desctription: Represents Yandex map options to be passed to the constructor. + * Valid values: `objectPlain` + * Default value: `{suppressMapOpenBlock: true}` + + +## Events description + +All events are triggered at the main element to which `jQuery.fn.ddMap` has been applied. + +* `ddBeforeInit` — Before initialisation (when the map API is ready, immediately before the map constructor is called). +* `ddAfterInit` — After initialisation. + + +## Links + +* [Home page](https://code.divandesign.ru/jquery/ddmap) +* [Telegram chat](https://t.me/dd_code) +* [GitHub](https://github.com/DivanDesign/jQuery.ddMap) + + + \ No newline at end of file diff --git a/README_ru.md b/README_ru.md new file mode 100644 index 0000000..5b2365a --- /dev/null +++ b/README_ru.md @@ -0,0 +1,162 @@ +# jQuery.ddMap + +Библиотека jQuery, позволяющая подключить и использовать интерактивную карту на странице простым способом. + +Сейчас работает только с Яндекс Картами, но в будущем, вероятно, добавим также Google Maps и OpenStreetMap. + +Фичи: +* Можно не думать о подключении скрипта Яндекс Карт, библиотека сделает это автоматически. +* Вам даже не нужно беспокоиться о размере контейнера, библиотека поставит размер по умолчанию, если он нулевой. +* Если используется более одного маркера, карта будет автоматически масштабироваться, чтобы все маркеры были видны. +* Размер карты будет автоматически обновляться при каждом срабатывании события `resize` на главном контейнере. + + +## Использует + +* [jQuery](https://jquery.com/) >= 3.5.0 (не тестировался с более ранними версиями) +* [JS API Яндекс Карт](https://yandex.ru/dev/maps/jsapi/doc/2.1/) >= 2.1 (подключится автоматически, если отсутствует на странице) + + +## Usage + + +### 1. Подключаем JS на странице + +```html + + + + + +``` + +Можно не думать о подключении скрипта Яндекс Карт, библиотека сделает это автоматически. + + +### 2. Добавляем контейнер карты в любое удобное место на странице + +```html + + + +``` + +Вам даже не нужно беспокоиться о размере контейнера, библиотека поставит размер по умолчанию, если он нулевой. + + +### 3. Запускаем `jQuery.fn.ddMap` + +```js +$('.map').ddMap({ + //Маркеров на карту можно добавить несколько + markers: [ + //Как минимум один обязателен + { + //Координаты обязательны + latLng: [ + 51.532098, + -0.178100 + ], + //Контент опционален, можно опустить + content: 'Some marker text.
' + } + ] +}); +``` + +Вот и всё! + + +## Описание параметров + + +### `jQuery.fn.ddMap(params)` + +* `params` + * Описание: Параметры. + * Допустимые значения: `objectPlain` + * **Обязателен** + +* `params.markers` + * Описание: Массив маркеров для размещения на карте. + * Если задать несколько маркеров, карта будет автоматически смаштабирована, чтобы они все были видны. + * Кроме того, вместо массива маркеров по-прежнему можно передавать простую пару координат (как это было в 1.2 и более ранних версиях). + * Допустимые значения: `array` + * **Обязателен** + +* `params.markers[i]` + * Описание: Данные маркера. + * Допустимые значения: `objectPlain` + * **Обязателен** + +* `params.markers[i].latLng` + * Описание: Координаты маркера (широта и долгота). + * Допустимые значения: `array` + * **Обязателен** + +* `params.markers[i].content` + * Описание: Содержимое всплывающего окна маркера. HTML-теги поддерживаются. + * Допустимые значения: `string` + * Значение по умолчанию: `''` + +* `params.apiKey` + * Описание: API-ключ Яндекс Карт. + _Пока что работает и без ключа, но Яндекс декларирует его обязательным, так что рекомендуется использовать._ + * Допустимые значения: `string` + * Значение по умолчанию: — + +* `params.defaultZoom` + * Описание: Дефолтный масштаб карты. + * Допустимые значения: `integer` + * Значение по умолчанию: `15` + +* `params.defaultType` + * Описание: Дефолтный тип карты. + * Допустимые значения: + * `'map'` — схема + * `'satellite'` — спутник + * `'hybrid'` — гибрид + * Значение по умолчанию: `'map'` + +* `params.scrollZoom` + * Описание: Разрешить масштабирование колесом мыши? + * Допустимые значения: `boolean` + * Значение по умолчанию: `false` + +* `params.mapCenterOffset` + * Описание: Смещение центра карты относительно центра контейнера карты в пикселях. + * Допустимые значения: `array` + * Значение по умолчанию: `[0, 0]` + +* `params.markerOptions` + * Описание: Опции маркеров. + * Допустимые значения: `objectPlain` + * Значение по умолчанию: `{}` + +* `params.controls` + * Описание: Массив контролов карты. + * Допустимые значения: `array` + * Значение по умолчанию: `[{name: 'zoomControl'},{name: 'typeSelector'},{name: 'fullscreenControl'},{name: 'geolocationControl'},{name: 'rulerControl'}]` + +* `params.mapOptions` + * Описание: Опции, которые будут переданы в конструктор Яндекс карты. + * Допустимые значения: `objectPlain` + * Значение по умолчанию: `{suppressMapOpenBlock: true}` + + +## Описание событий + +Все события срабатывают на основном элементе, к которому был применен `jQuery.fn.ddMap`. + +* `ddBeforeInit` — Перед инициализацией (когда API карты готов, непосредственно перед вызовом конструктора карты). +* `ddAfterInit` — После инициализации. + + +## Ссылки + +* [Home page](https://code.divandesign.ru/jquery/ddmap) +* [Telegram chat](https://t.me/dd_code) +* [GitHub](https://github.com/DivanDesign/jQuery.ddMap) + + + \ No newline at end of file diff --git a/jQuery.ddMap.js b/jQuery.ddMap.js new file mode 100644 index 0000000..0a35f28 --- /dev/null +++ b/jQuery.ddMap.js @@ -0,0 +1,309 @@ +/** + * jQuery.ddMap + * @version 2.0 (2023-05-22) + * + * @see {@link README.md} + * + * @link https://code.divandesign.ru/jquery/ddmap + * + * @copyright 2013–2023 [Ronef]{@link https://Ronef.ru } + */ + +(function($){ + class ddMap { + static isStaticInited = false; + + static initStatic(params){ + var theClass = this; + + if (!theClass.isStaticInited){ + theClass.isStaticInited = true; + + //If Yandex Maps API is not included yet + if (typeof ymaps == 'undefined'){ + var apiSrc = '//api-maps.yandex.ru/2.1/?lang=' + navigator.language; + + if (params.apiKey.length > 0){ + apiSrc += '&apikey=' + params.apiKey; + } + + $('head').append(''); + } + } + } + + constructor(props){ + var + theInstance = this, + theClass = theInstance.constructor + ; + + theInstance.markers = new Array(); + theInstance.$element = 'map'; + theInstance.defaultZoom = 15; + theInstance.defaultType = 'map'; + theInstance.scrollZoom = false; + theInstance.mapCenterOffset = false; + theInstance.markerOptions = {}; + theInstance.controls = [ + {name: 'zoomControl'}, + {name: 'typeSelector'}, + {name: 'fullscreenControl'}, + {name: 'geolocationControl'}, + {name: 'rulerControl'} + ]; + theInstance.mapOptions = { + suppressMapOpenBlock: true + }; + + theInstance.apiConnectionAttempts = 0; + + theInstance.setProps(props); + + theClass.initStatic({ + apiKey: + typeof props.apiKey == 'undefined' ? + '' : + props.apiKey + }); + + theInstance.constructor_init(); + } + + constructor_init(){ + var theInstance = this; + + //If Yandex map API is not loaded yet + if (typeof ymaps == 'undefined'){ + theInstance.apiConnectionAttempts++; + + //Try again later but 10 attempts as maximum + if (theInstance.apiConnectionAttempts < 10){ + setTimeout( + theInstance.constructor_init.bind(theInstance), + ( + 500 + + //Await + 100 ms after each attempt + theInstance.apiConnectionAttempts * 100 + ) + ); + } + }else{ + ymaps.ready(function(){ + var + //Подготавливаем точки + geoObjects = theInstance.prepareMarkers(), + //Количество точек + geoObjects_len = geoObjects.getLength() + ; + + //Если точки заданы + if (geoObjects_len > 0){ + theInstance.$element = $(theInstance.$element); + + theInstance.$element.trigger('ddBeforeInit'); + + //Delete all children + theInstance.$element.empty(); + + //Установим высоту у элемента, если она не задана + if (theInstance.$element.height() == 0){ + theInstance.$element.height(400); + } + + //Создаём карту + var + map = new ymaps.Map( + theInstance.$element.get(0), + { + center: geoObjects.get(0).geometry.getCoordinates(), + zoom: theInstance.defaultZoom, + type: 'yandex#' + theInstance.defaultType, + controls: [] + }, + theInstance.mapOptions + ) + ; + + //Если заданы котролы + if(Array.isArray(theInstance.controls)){ + theInstance.controls.forEach( + control => + { + if(control.name){ + //Добавляем их + map.controls.add( + control.name, + control.options + ); + } + } + ); + } + + //Если зум не нужен + if (!theInstance.scrollZoom){ + //Выключим масштабирование колесом мыши (т.к. в 2.1 по умолчанию он включён) + map.behaviors.disable('scrollZoom'); + } + + //Добавляем метки на карту + map.geoObjects.add(geoObjects); + + //Если меток несколько + if (geoObjects_len > 1){ + //Если элемент с картой скрыт + if (theInstance.$element.is(':hidden')){ + //При первом изменении размера (иначе, если карта была скрыта, выйдет плохо) + map.events.once( + 'sizechange', + function(){ + //Надо, чтобы они все влезли + map.setBounds(geoObjects.getBounds()); + } + ); + }else{ + //Надо, чтобы они все влезли + map.setBounds(geoObjects.getBounds()); + } + } + + //Если нужно смещение центра карты + if ( + Array.isArray(theInstance.mapCenterOffset) && + theInstance.mapCenterOffset.length == 2 + ){ + var position = map.getGlobalPixelCenter(); + + map.setGlobalPixelCenter([ + position[0] - theInstance.mapCenterOffset[0], + position[1] - theInstance.mapCenterOffset[1] + ]); + } + + theInstance.$element + .on( + 'resize', + () => { + map.container.fitToViewport(); + } + ) + .data( + 'ddMap', + {map: map} + ) + .trigger('ddAfterInit') + ; + } + }); + } + } + + prepareMarkers(){ + var + theInstance = this, + geoObjects = new ymaps.GeoObjectCollection() + ; + + if (!Array.isArray(theInstance.markers)){ + return geoObjects; + } + + //Если передана просто пара координат + if ( + theInstance.markers.length == 2 && + $.isNumeric(theInstance.markers[0]) && + $.isNumeric(theInstance.markers[1]) + ){ + //Значит точка одна + geoObjects.add( + new ymaps.Placemark( + theInstance.markers, + {}, + theInstance.markerOptions + ) + ); + }else{ + //Переберём все точки + theInstance.markers.forEach( + markerData => { + //Если координаты заданы + if ( + $.isPlainObject(markerData) && + Array.isArray(markerData.latLng) && + markerData.latLng.length == 2 + ){ + //Создаём метку + geoObjects.add( + new ymaps.Placemark( + markerData.latLng, + { + balloonContent: + typeof markerData.content == 'string' ? + $.trim(markerData.content) : + '' + }, + theInstance.markerOptions + ) + ); + } + } + ); + } + + return geoObjects; + } + + //This method from jQuery.ddUI + /** + * @method setProps + * @version 1.1 (2023-04-22) + * + * @desc Sets the ojbect properties. + * + * @param [props] {objectPlain} — Object props values. + * @param props[propName] {mixed} — Key is property name, value is value. + * + * @returns {void} + */ + setProps(props){ + var theInstance = this; + + if ($.isPlainObject(props)){ + Object.entries(props).forEach( + ([ + propName, + propValue + ]) => + { + //If the property exists + if (typeof theInstance[propName] != 'undefined'){ + //Plain objects are extended, others are owerwrited + if ($.isPlainObject(theInstance[propName])){ + $.extend( + theInstance[propName], + propValue + ); + }else{ + theInstance[propName] = propValue; + } + } + } + ); + } + } + }; + + $.fn.ddMap = function(params){ + return $(this).each(function(){ + new ddMap( + $.extend( + params, + { + $element: this + } + ) + ) + }); + }; +})(jQuery); \ No newline at end of file diff --git a/jQuery.ddMap.min.js b/jQuery.ddMap.min.js new file mode 100644 index 0000000..c0a65d6 --- /dev/null +++ b/jQuery.ddMap.min.js @@ -0,0 +1,2 @@ +/* jQuery.ddMap v2.0 (2023-05-22) | © https://Ronef.ru */ +!function(e){class t{static isStaticInited=!1;static initStatic(t){if(!this.isStaticInited&&(this.isStaticInited=!0,"undefined"==typeof ymaps)){var n="//api-maps.yandex.ru/2.1/?lang="+navigator.language;t.apiKey.length>0&&(n+="&apikey="+t.apiKey),e("head").append('