Шаблон:Mapframe для карток/документація

Опис

Цей шаблон створено за допомогою мови Lua, відповідним йому модулем є Модуль:Mapframe для карток. Цей шаблон призначено для вставки інтерактивних віконець із мапою OpenStreetMap до шаблонів-карток географічних об'єктів, зокрема країн та регіонів, наприклад {{Картка країни}} або {{Адміністративна одиниця}}. Такі віконця уможливлює встановлене у рушії MediaWiki розширення «Kartographer». Для вставки віконець із інтерактивними мапами використовується тег mapframe, а цей шаблон повертає код виду:

<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>

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

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

Як працює

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

$\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$

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

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

$\left\lfloor 15-\log _{4}(2.5*S)\right\rfloor$

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

Аргументи

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

Використання

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

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

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

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

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

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

|ширина={{{mapframe_ширина|250}}}|висота={{{mapframe_висота|250}}}

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

|префікс={{!}}-
{{!}} colspan="2" {{!}} 

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

Приклади

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

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

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

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

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

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

Контур із OSM	Контур із Вікісховища
{{Mapframe для карток|елемент=Q159}}	{{Mapframe для карток|контур=Russia.map}}

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

{{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}}

Категорії спостереження

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

Див. також

• mw:Help:Extension:Kartographer
• OpenStreetMap
• mw:Extension:Scribunto/Lua reference manual/uk
• mw:Extension:Wikibase Client/Lua
• Шаблон:Карта розташування