Version 2.0

CHANGELOG.md

@@ -0,0 +1,59 @@
+# jQuery.ddMap changelog
+
+
+## Version 2.0 (2023-05-22)
+* \* The library has been renamed from `ddYMap` to `ddMap`: `jQuery.fn.ddYMap` → `jQuery.fn.ddMap`.
+* \+ You may not to think about including Yandex Map script, the library will do it automatically.
+* \+ The map size will be automatically updated each time the `resize` event will be triggered on the main container.
+* \+ All children of the main element will be deleted during initialisation.
+* \+ If Yandex Map API is not loaded, the script will await it.
+* \* Parameters:
+	* \+ `params.apiKey`: The new parameter. Yandex Maps API key. For now it is working without key, but Yandex mark it as required, so it is recommended to set it.
+	* \* The following have been renamed:
+		* \* `params.placemarks` → `params.markers`.
+		* \* `params.placemarkOptions` → `params.markerOptions`.
+	* \- `params.zoom`, `params.latLng`: The outdated names are no longer supported, use `params.defaultZoom` and `params.placemarks` instead.
+* \+ Events → `ddBeforeInit`: The new event.
+* \+ README, README_ru.
+* \+ CHANGELOG, CHANGELOG_ru.
+* \* Attention! Backward compatibility is broken.
+
+
+## Version 1.4 (2015-07-23)
+* \+ Parameters → `controls`: The new optional parameter. It is an array of controls to be added onto the map.
+* \+ Parameters → `mapOptions`: The new optional parameter. It represents yandex map [options](https://tech.yandex.com/maps/doc/jsapi/2.1/ref/reference/Map-docpage/#param-options) to be passed to the constructor.
+
+
+## Version 1.3.1 (2014-07-24)
+* \* Hidden map with the several placemarks will be positioned on the first show.
+* \* Empty height of the map element will be set to `400px`.
+
+
+## Version 1.3 (2014-07-10)
+* \* **Be advised!** The [2.1](http://api.yandex.ru/maps/api21.xml) version of Yandex Maps API is used!
+* \+ The new `geolocation` and `full screen` controls have been added onto map.
+* \* Parameters → `placemarks`:
+	* \* The parameter has been renamed from `latLng` (the old name is still can be used, but it's recommended to use the new one).
+	* \+ Now can be either an array of placemarks or a pair of coordinates. Each placemark can have its position as well as a tip that appears when clicked. The parameter can be, as before, a coordinate pair for the map center.
+* \+ The map object (an instance of `ymaps.Map`) is now stored inside of the 'ddYmap' property of the map container (the one that `jQuery.fn.ddYMap` is applied to) via the jQuery.fn.data method of JQuery.
+* \+ Events → `ddAfterInit`: The new event. It's attached to the map container and will be triggered after the map has been initialized.
+
+
+## Version 1.2 (2014-06-05)
+* \+ Parameters → `mapCenterOffset`: The new optional parameter. It allows center offset of the map to be set in pixels with respect to the center of the map container.
+* \* Parameters → `defaultZoom`: The parameter has been renamed from `zoom` (the old name is still can be used, but it's recommended to use the new one).
+
+
+## Version 1.1 (2014-03-16)
+* \+ The `jQuery.fn.ddYMap` method has been added. The internal method `jQuery.ddYMap.init` is not recommended to use.
+* \+ The `params.defaultType` parameter which allows to set default map type has been added.
+* \- The redundant parameter `params.elementId` has been removed.
+* \* The internal variable `elementId` has been ranamed as `element`.
+
+
+## Version 1.0 (2013-07-12)
+* \+ The first release.
+
+
+<link rel="stylesheet" type="text/css" href="https://raw.githack.com/DivanDesign/CSS.ddMarkdown/master/style.min.css" />
+<style>ul{list-style:none;}</style>

CHANGELOG_ru.md

@@ -0,0 +1,59 @@
+# jQuery.ddMap changelog
+
+
+## Версия 2.0 (2023-05-22)
+* \* Библиотека переименована из `ddYMap` в `ddMap`: `jQuery.fn.ddYMap` → `jQuery.fn.ddMap`.
+* \+ Можно не думать о подключении скрипта Яндекс Карт, библиотека сделает это автоматически.
+* \+ Размер карты будет автоматически обновляться при каждом срабатывании события `resize` на главном контейнере.
+* \+ Все дочерние элементы главного элемента будут удалены во время инициализации.
+* \+ Скрипт будет дожидаться загрузки API Яндекс Карт по необходимости.
+* \* Параметры:
+	* \+ `params.apiKey`: Новый параметр. API-ключ Яндекс Карт. Пока что работает и без ключа, но Яндекс декларирует его обязательным, так что рекомендуется использовать.
+	* \* Следующие переименованы:
+		* \* `params.placemarks` → `params.markers`.
+		* \* `params.placemarkOptions` → `params.markerOptions`.
+	* \- `params.zoom`, `params.latLng`: Устаревшие названия больше не поддерживаются, используйте вместо них `params.defaultZoom` и `params.placemarks`.
+* \+ Событие → `ddBeforeInit`: Новое событие.
+* \+ README, README_ru.
+* \+ CHANGELOG, CHANGELOG_ru.
+* \* Внимание! Обратная совместимость нарушена.
+
+
+## Версия 1.4 (2015-07-23)
+* \+ Параметры → `controls`: Новый необязательный параметр. Массив элементов управления картой.
+* \+ Параметры → `mapOptions`: Новый необязательный параметр. [Опции карты](https://tech.yandex.ru/maps/doc/jsapi/2.1/ref/reference/Map-docpage/#param-options), которые будут переданы в конструктор.
+
+
+## Версия 1.3.1 (2014-07-24)
+* \* Если меток несколько и карта изначально скрыта, то позиционирование делается при первом показе.
+* \* Если у элемента с картой не задана высота, она выставляется в `400px`.
+
+
+## Версия 1.3 (2014-07-10)
+* \* **Внимание!** Используется API Яндекс Карт версии [2.1](http://api.yandex.ru/maps/api21.xml)!
+* \+ Добавлены новые элементы управления на карту: геолокация и полноэкранный режим.
+* \* Параметры → `placemarks`:
+	* \* Параметр переименован из `latLng` (старое имя пока поддерживается, но не рекомендуется к использованию).
+	* \+ Теперь принимает массив меток, а не просто пару координат. У каждой метки можно задать не только позицию, но и всплывающую при клике подсказку (балун). Параметр, как и раньше, может принимать и просто пару координат центра карты.
+* \+ Объект карты (экземпляр `ymaps.Map`) записывается в data 'ddYMap' контейнеру с картой (к которому применён `jQuery.fn.ddYMap`).
+* \+ События → `ddAfterInit`: Новое событие. Вызывается у контейнера с картой после инициализации.
+
+
+## Версия 1.2 (2014-06-05)
+* \+ Параметры → `mapCenterOffset`: Новый необязательный параметр. Позволяет задать смещение центра карты относительно центра контейнера в пикселях.
+* \* Параметры → `defaultZoom`: Параметр переименован из `zoom` (старое имя пока поддерживается, но не рекомендуется к использованию).
+
+
+## Версия 1.1 (2014-03-16)
+* \+ Добавлен метод `jQuery.fn.ddYMap`, внутренний метод `jQuery.ddYMap.init` не рекомендуется к использованию.
+* \+ Добавлен параметр `params.defaultType`, позволяющий задать тип карты по умолчанию.
+* \- Параметр `params.elementId` удалён за ненадобностью.
+* \* Внутренняя переменная `elementId` переименована в `element`.
+
+
+## Версия 1.0 (2013-07-12)
+* \+ Первый релиз.
+
+
+<link rel="stylesheet" type="text/css" href="https://raw.githack.com/DivanDesign/CSS.ddMarkdown/master/style.min.css" />
+<style>ul{list-style:none;}</style>

README.md

@@ -1,5 +1,163 @@
-# jQuery.ddYMap
+# jQuery.ddMap
 
-A jQuery library that allows Yandex.Maps to be rendered on a page in a simple way.
-___
-Visit the following [link](http://code.divandesign.biz/jquery/ddymap) to read the documentation, instructions & changelog.
+A jQuery library that allows Yandex Maps to be rendered on a page in a simple way.
+
+Right now the library works only with Yandex Maps, but in the future we are likely to add Google Maps and OpenStreetMap as well.
+
+Features:
+* You may not to think about including Yandex Map script, the library will do it automatically.
+* You don't even have to worry about the container size, the lib will set default size if it is zero.
+* If more than one marker is used, the map will be automatically scaled so that all markers are visible.
+* The map size will be automatically updated each time the `resize` event will be triggered on the main container.
+
+
+## Requires
+
+* [jQuery](https://jquery.com/) >= 3.5.0 (not tested with older versions)
+* [Yandex Maps JS API](https://yandex.com/dev/maps/jsapi/doc/2.1/) => 2.1 (will be included automatically if missing on a page)
+
+
+## Usage
+
+
+### 1. Include JS on page
+
+```html
+<!-- Required libs -->
+<script src="jQuery-3.5.0.min.js"></script>
+
+<!-- jQuery.ddMap -->
+<script src="jQuery.ddMap-2.0.0.min.js"></script>
+```
+
+You may not to think about including Yandex Map script, the library will do it automatically.
+
+
+### 2. Add a map container wherever you like on a page
+
+```html
+<body>
+	<div class="map"></div>
+</body>
+```
+
+You don't even have to worry about the container size, the lib will set default size if it is zero.
+
+
+### 3. Run `jQuery.fn.ddMap`
+
+```js
+$('.map').ddMap({
+	//You can add several markers if you want
+	//If there is more than one marker, the map will be auto-scaled to make all the markers visible
+	markers: [
+		//At least one marker is required
+		{
+			//Geo position is required
+			latLng: [
+				51.532098,
+				-0.178100
+			],
+			//Content is optional, you can avoid it
+			content: '<p>Some marker text.</p>'
+		}
+	]
+});
+```
+
+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)
+
+
+<link rel="stylesheet" type="text/css" href="https://raw.githack.com/DivanDesign/CSS.ddMarkdown/master/style.min.css" />