Перегляд вихідного коду сторінки Шаблон:Mapframe для карток/документація

{{підсторінка документації}}
<!-- РЕДАГУЙТЕ ДОКУМЕНТАЦІЮ ШАБЛОНУ НИЖЧЕ ЦЬОГО РЯДКА -->
{{Високий ризик|220000+}}
{{Lua|Модуль:Mapframe для карток}}
{{Sister project|image=[[File:Openstreetmap logo.svg|40x40px]]|text=Цей шаблон використовує [[OpenStreetMap]].}}
{{Uses Wikidata|P1332|P1333|P1334|P1335|P625|P2046}}

== Опис ==
Цей шаблон створено за допомогою мови [[:mw:Extension:Scribunto/Lua reference manual/uk|Lua]], відповідним йому модулем є [[Модуль:Mapframe для карток]]. Цей шаблон призначено для вставки інтерактивних віконець із мапою [[OpenStreetMap]] до [[Шаблон:Картка|шаблонів-карток]] географічних об'єктів, зокрема країн та регіонів, наприклад {{tl|Картка країни}} або {{tl|Адміністративна одиниця}}. Такі віконця уможливлює встановлене у рушії MediaWiki розширення [[:mw:Help:Extension:Kartographer|«Kartographer»]]. Для вставки віконець із інтерактивними мапами використовується тег <code>mapframe</code>, а цей шаблон повертає код виду:

<code><nowiki><mapframe width=300 height=300 zoom=4 longitude=30 latitude=50 align=center frameless>{"type": "ExternalData","service": "geoshape","ids": "Q212","properties": {"fill-opacity": 0.3}}</mapframe></nowiki></code>

Всередині тега задається додаткова інформація у форматі [[JSON]]. Цей шаблон також відображує контур географічного об'єкта на мапі, за його наявності, і в цій додатковій інформації якраз вказується елемент [[Вікідані|Вікіданих]] для якого треба взяти відповідний йому контур.

Також, додається шаблон {{tl|Якір}}, який додає невидиму мітку, що надає можливість посилатися на мапу з довільного місця даної або іншої сторінки, дописавши в кінець [[Уніфікований локатор ресурсів|URL-адреси]] сторінки <code>#map-osm</code>. Таким чином, можна зробити [[#map-osm|посилання]] на перше використання мапи на цій сторінці.

== Як працює ==
Для роботи віконця із мапою, і відповідно, для роботи шаблону, необхідною інформацією є географічні координати центра мапи та масштаб. Спочатку перевіряється чи були задані координати та масштаб в аргументах при виклику шаблону. Якщо так, то вони використовуються, якщо ні, то ці дані будуть отримані із Вікіданих. Для цього перевіряється чи був заданий аргумент шаблону в якому вказано елемент Вікіданих. Якщо елемент було вказано, то дані беруться для цього елементу, якщо ні, то використовується елемент для поточної сторінки. Якщо вказані координати всіх крайніх точок географічного об'єкту ({{Q|P1332}}, {{Q|P1333}}, {{Q|P1334}} та {{Q|P1335}}), то координати центру для мапи отримуються через обчислення середніх значень координат крайніх точок. Для широти обчислюється середнє значення крайніх північної та південної точок, а для довготи середнє значення довготи крайніх західної та східної точок. Пораховані таким чином координати для географічних об'єктів, через які проходить [[180-й меридіан]], можуть бути некоректними, і в такому випадку координати треба задати вручну. Масштаб також рахується через ці крайні точки за формулою:

<math>\left \lfloor \log_{\frac{1}{2}} \left ( \left ( \frac{\max(|n-s|,|w-e|)}{360} \right ) * \left ( \frac{300}{mapsize} \right ) - 0.2 \right ) \right \rfloor</math>

де n та s - широта північної та південної точок, w та e - довгота західної та східної точок. mapsize - висота мапи у пікселях якщо більшою виявилась різниця між північною та південною точками, ширина мапи якщо більшою є різниця між західною та східною точками.

Якщо крайні точки не задано, то координати беруться із властивості {{Q|P625}} (середнє значення крайніх точок точніше, оскільки значення властивості P625 не завжди є близьким до геометричного центру географічного об'єкта), а масштаб вираховується із значення площі що зберігається у властивості {{Q|P2046}} (хоча це не підрахунок, а скоріше, груба оцінка, до того ж для острівних країн та країн близьких до полюсів значення буде ще менш точним) за формулою:

<math>\left \lfloor 15 - \log_{4}(2.5*S) \right \rfloor</math>

де S - площа географічного об'єкту в км<sup>2</sup>. Якщо і ці властивості не задані, то сторінка додається до прихованої категорії [[:Категорія:Вікідані:P625:відсутня]] та/або [[:Категорія:Вікідані:P2046:відсутня]], а мапа не відображується. Якщо для поточної сторінки не існує елемента Вікіданих і він не вказаний в аргументі, або якщо цей елемент з якихось причин не вдається завантажити, сторінка додається до прихованої категорії [[:Категорія:Сторінки із некоректними мапами]]. В таких випадах слід додати необхідні дані до Вікіданих або створити елемент, або ж задати необхідні дані вручну в аргументах.

== Аргументи ==
{| class="wikitable"
|-
! Аргумент
! Опис
! Допустимі значення
! Значення за замовчуванням
|-
| '''широта'''
| Географічна широта центру мапи у вигляді цілого числа або числа із десятковою крапкою. Координати у вигляді ''50°27′00″ пн. ш.'' не допускаються. Використовується тільки разом з аргументом "довгота".
| Ціле число або число із десятковою крапкою, додатнє чи від'ємне, наприклад <code>30</code> або <code>-45</code> або <code>12.345678</code>.
| Береться із Вікіданих
|-
| '''довгота'''
| Географічна довгота центру мапи у вигляді цілого числа або числа із десятковою крапкою. Координати у вигляді ''30°31′25″ сх. д.'' не допускаються. Використовується тільки разом з аргументом "широта".
| Ціле число або число із десятковою крапкою, додатнє чи від'ємне, наприклад <code>30</code> або <code>-45</code> або <code>12.345678</code>.
| Береться із Вікіданих
|-
| '''масштаб'''
| Масштаб мапи у вигляді цілого числа від 0 до 19, де 0 це мапа усього світу, а 19 це мапа зі стороною приблизно 70 м, тобто чим більше число, тим мапа "наближеніша" і менша площа відображується на мапі, чим менше число, тим мапа "віддаленіша" і більша площа відображується. Масштаб 0 відповідає проміжку у 360 градусів, масштаб 1 у 180 градусів, масштаб 2 у 90 градусів, і так далі аж до масштабу 19 із проміжком у 2.472 секунд.
| Ціле число від ''0'' до ''19''.
| Береться із Вікіданих
|-
| '''ширина'''
| Ширина віконця із мапою.
| Ціле додатне число.
| 300
|-
| '''висота'''
| Висота віконця із мапою.
| Ціле додатне число.
| 300
|-
| '''елемент'''
| Елемент Вікіданих для якого брати контур географічного об'єкта та з якого отримувати необхідні дані, якщо вони не вказані в інших аргументах. Якщо для поточної сторінки не існує елемента Вікіданих, то аргумент є обов'язковим, інакше повертається помилка.
| Буква ''Q'' і ціле число, наприклад <code>Q212</code>.
| Елемент для поточної сторінки.
|-
| '''рамка'''
| Чи відображувати рамку навколо мапи?
| Будь-яке значення щоб відображувати рамку.
| Рамка не відображується
|-
| '''вирівнювання'''
| По якій стороні вирівнювати мапу (вона має бути зліва, справа чи по центру).
| <code>left</code>, <code>right</code> або <code>center</code>.
| center
|-
| '''текст'''
| Текстовий підпис під мапою. Якщо текст вказано, рамка теж буде показуватись, незалежно від того що вказано в аргументі "рамка".
| Будь-який текст, в тому числі із вікірозміткою.
| Текст не відображується.
|-
| '''контур'''
| Посилання на контур географічного об'єкту на Вікісховищі, наприклад [[:commons:Data:Ukraine.map]], щоб використати його замість контура із OSM.
| Назва файла на Вікісховищі із роширенням ''.map'' без префікса ''Data:''.
| Контур береться із OSM.
|-
| '''префікс'''
| Текст, який відображатиметься перед шаблоном, якщо шаблон відображається. Якщо шаблон не відображається, то і цей текст не відображатиметься.
| Будь-який текст, в тому числі із вікірозміткою.
| Текст не відображується.
|-
| '''постфікс'''
| Текст, який відображатиметься після шаблону, якщо шаблон відображається. Якщо шаблон не відображається, то і цей текст не відображатиметься.
| Будь-який текст, в тому числі із вікірозміткою.
| Текст не відображується.
|-
| '''перелік'''
| Використовується, якщо потрібно відобразити на мапі більше одного контура. Перелічуються елементи Вікіданих (Q + число) через крамку з комою. Після елементу Вікіданих після коми, але перед крапкою з комою, можна додати коментар, який буде проігнорований модулем, наприклад можна написати просто "Q212;", а можна із коментарем - "Q212 UKR;".
| Елементи Вікіданих розділені через крапку з комою.
| geomask
|-
| '''geo'''
| Тип контуру, що відобразиться на мапі. geomask - заливка поза межами контуру, geoshape - заливка всередині контуру, geoline - лінія.
| <code>geomask</code>, <code>geoshape</code> або <code>geoline</code>.
| geomask
|-
| '''no_p625'''
| Категорія, до якої треба додати сторінку, якщо не вдалося знайти для неї географічні координати.
| Назва категорії, з префіксом "Категорія:".
| Категорія:Вікідані:P625:відсутня
|-
| '''no_p2046'''
| Категорія, до якої треба додати сторінку, якщо не вдалося знайти для неї площу, а тому і масштаб.
| Назва категорії, з префіксом "Категорія:".
| Категорія:Вікідані:P2046:відсутня
|}

== Використання ==
Цей шаблон призначено для використання у шаблонах-картках про географічні об'єкти. Для цього треба додати виклик шаблону до тексту шаблона-картки. При цьому треба зберегти можливість передавати аргументи зі сторінки, до якої включений шаблон-картка, до цього шаблону, але при цьому шаблон-картка є посередником. Тому в шаблоні-картці треба викликати цей шаблон таким чином:

<code><nowiki>{{Mapframe для карток|широта={{{mapframe_широта|}}}|довгота={{{mapframe_довгота|}}}|масштаб={{{mapframe_масштаб|}}}|ширина={{{mapframe_ширина|}}}|висота={{{mapframe_висота|}}}|елемент={{{mapframe_елемент|}}}|рамка={{{mapframe_рамка|}}}|вирівнювання={{{mapframe_вирівнювання|}}}|текст={{{mapframe_текст|}}}}}</nowiki></code>

тобто передати далі у цей шаблон всі аргументи, що були вказані у виклику шаблону-картки на сторінці. Якщо задавати аргументи для цього шаблону на сторінці, що включає шаблон-картку, то назви аргументів матимуть префікс <code>mapframe_</code> для уникнення колізії з назвами вже існуючих в шаблоні-картці аргументів, тобто, наприклад, щоб в статті [[Бразилія]] вказати масштаб мапи рівним трьом, треба у виклику шаблона {{tl|Картка країни}} вказати аргумент <code>|mapframe_масштаб=3</code>.

Щоб додати можливість вимкнення відображення мапи, до шаблону-картки можна додати код із перевіркою аргументу "no_mapframe":

<code><nowiki>{{#if:{{{no_mapframe|}}}||{{Mapframe для карток|широта={{{mapframe_широта|}}}|довгота={{{mapframe_довгота|}}}|масштаб={{{mapframe_масштаб|}}}|ширина={{{mapframe_ширина|}}}|висота={{{mapframe_висота|}}}|елемент={{{mapframe_елемент|}}}|рамка={{{mapframe_рамка|}}}|вирівнювання={{{mapframe_вирівнювання|}}}|текст={{{mapframe_текст|}}}}} }}</nowiki></code>

Якщо необхідно щоб розмір мапи включеної до картки був відмінним від 300, можна задати інше значення за замовчуванням, наприклад 250:

<code><nowiki>|ширина={{{mapframe_ширина|250}}}|висота={{{mapframe_висота|250}}}</nowiki></code>

Часто, необхідно вказати початок нового рядка та комірки таблиці перед мапою. Тоді можна скористатися параметром "префікс", який відобразиться якщо відобразиться і сам мапа. Якщо мапа не відображається через брак інформації для її відображення, то і цей префікс не відобразиться.

<pre><nowiki>|префікс={{!}}-
{{!}} colspan="2" {{!}} </nowiki></pre>

Протягом деякого часу після додавання виклику цього шаблону до шаблона-картки, на сторінках що використовують цей шаблон-картку, замість мапи може відображуватись прозорий прямокутник, але це тимчасово, і мапа з'явиться через декілька годин. Те саме стосується сторінок, куди виклик цього шаблону вставлений напряму.

== Приклади ==
В статті [[Чехія]] в шаблоні-картці {{tl|Картка країни}}, буде відображатись віконце із мапою. Без вказання жодних аргументів, всі дані будуть взяті із елемента {{Q|213}}:

{{Mapframe для карток|елемент=Q213}}

В деяких випадках, наприклад при використанні шаблону-картки {{tl|Картка:Державний кордон}} у статті [[Словацько-український кордон]], аргументи необхідно задавати вручну:

{{Mapframe для карток|geo=geoshape|широта=48.7|довгота=22.3|масштаб=8|елемент=Q2630766}}

<center><code><nowiki>{{Mapframe для карток|широта=48.7|довгота=22.3|масштаб=8}}</nowiki></code></center>

Можна задавати також відображення рамки, вирівнювання та текст підпису:

{{Mapframe для карток|елемент=Q170036|рамка=1|вирівнювання=left|текст=Київська область}}

<br clear="all"/><code><nowiki>{{Mapframe для карток|елемент=Q170036|рамка=1|вирівнювання=left|текст=Київська область}}</nowiki></code>

Можна використовувати контур із Вікісховища замість контура із OSM:

{| class="wikitable"
|-
! Контур із OSM
! Контур із Вікісховища
|-
| {{Mapframe для карток|елемент=Q483599|широта=45.2|довгота=36|масштаб=6|geoshape=1}}
| {{Mapframe для карток|елемент=Q159|широта=45.2|довгота=36|масштаб=6|контур=Russia.map}}
|-
| <center><code><nowiki>{{Mapframe для карток|елемент=Q159}}</nowiki></code></center>
| <center><code><nowiki>{{Mapframe для карток|контур=Russia.map}}</nowiki></code></center>
|}

Можна використовувати одразу декілька контурів:

{{Mapframe для карток|елемент=Q458|рамка=1|вирівнювання=left|текст=Європейський Союз|geo=geoshape|перелік=Q27 IRL;Q28 HUN;Q29 ESP;Q31 BEL;Q32 LUX;Q33 FIN;Q34 SWE;Q35 DEN;Q36 POL;Q37 LIT;Q38 ITA;Q40 AUT;Q41 GRE;Q45 POR;Q55 NED;Q142 FRA;Q145 GBR;Q183 DEU;Q191 EST;Q211 LAT;Q213 CZE;Q214 SVK;Q215 SLO;Q218 ROM;Q219 BUL;Q224 CRO;Q229 CYP;Q233 MLT}}

<br clear="all"/><code><nowiki>{{Mapframe для карток|рамка=1|вирівнювання=left|текст=Європейський Союз|перелік=Q27 IRL;Q28 HUN;Q29 ESP;Q31 BEL;Q32 LUX;Q33 FIN;Q34 SWE;Q35 DEN;Q36 POL;Q37 LIT;Q38 ITA;Q40 AUT;Q41 GRE;Q45 POR;Q55 NED;Q142 FRA;Q145 GBR;Q183 DEU;Q191 EST;Q211 LAT;Q213 CZE;Q214 SVK;Q215 SLO;Q218 ROM;Q219 BUL;Q224 CRO;Q229 CYP;Q233 MLT}}</nowiki></code>

== Категорії спостереження ==
* [[:Категорія:Сторінки із некоректними мапами]]
* [[:Категорія:Шаблони, в яких використовується mapframe]]
* [[:Категорія:Вікідані:P625:відсутня]]
* [[:Категорія:Вікідані:P2046:відсутня]]

== Див. також ==
* [[:mw:Help:Extension:Kartographer]]
* [https://www.openstreetmap.org/ OpenStreetMap]
* [[:mw:Extension:Scribunto/Lua reference manual/uk]]
* [[:mw:Extension:Wikibase Client/Lua]]
* [[Шаблон:Карта розташування]]

<includeonly>
<!-- ДОДАВАЙТЕ КАТЕГОРІЇ НИЖЧЕ ЦЬОГО РЯДКА, ІНТЕРВІКІ ДОДАВАЙТЕ НА ВІКІДАНИХ -->
[[Категорія:Шаблони]]
[[Категорія:Шаблони:Географія:Карти]]
[[Категорія:Шаблони карт розташування]]
</includeonly>