Wikivoyage:Gadget-ListingEditor.js

Dieser Artikel enthält technische Hintergrundinformationen zum Skript Gadget-ListingEditor.js. Dieser formularbasierte vCard-Editor kann zum Erstellen, Bearbeiten und Löschen von vCard-Einträgen benutzt werden.

Die Vorlage {{vCard}} gehört zu den komplexesten Vorlagen dieses Wikis. Etwa 40 Parameter lassen sich spezifizieren. Für Autoren ohne Kenntnis der Wikisoftware und ihrer Syntax stellt die Spezifikation eine immense Herausforderung dar. Mit einem Eingabeformular soll dem entgegengewirkt werden.

Zu diesem Zweck wurde am 25. Juni 2017 die Version 2.1 vom englischen Wikivoyage übernommen, musste aber für den Einsatz auf dem deutschen Wikivoyage stark angepasst bzw. erweitert werden.

Für die Benutzung des Editors gibt es auch Hilfestellungen.

Benötigte Bibliotheken

• Mediawiki, mediawiki.util
• jQuery core
• jQuery UI
• jQuery Chosen
• MediaWiki:Gadget-ListingEditor.css
• MediaWiki:Gadget-InitListingTools.js

Weitere Dokumente

• Hilfe:Erstellen einer VCard
• Versionsgeschichte ListingEditor.js

Verwendbarkeit

Unterstützte Skins

Vector, MinervaNeue, MonoBook

Noch nicht unterstützte Skins

wegen fehlender jQuery UI: Minerva

Eignung für andere Wikis

Wikivoyage/de, Wikivoyage/eo, Wikivoyage/es

Eignung für mobile Geräte

nein, wegen fehlender jQuery-Bibliotheken.

Aufruf

Der Aufruf erfolgt durch das Skript Gadget-InitListingTools.js.

Module

Das Skript ist in vier Module unterteilt:

Config

Dient hauptsächlich der Sprachanpassung. Die Variablen werden von den anderen Modulen genutzt.

Callbacks

Stellt Initialisierungs- und Prüffunktionen in der jeweiligen Sprachversion zur Verfügung.

ListingEditor.Callbacks.CREATE_FORM_CALLBACKS: Funktionen werden bei der Eröffnung des Editor-Dialogs aufgerufen.

ListingEditor.Callbacks.SUBMIT_FORM_CALLBACKS: Funktionen werden nach dem Drücken des Übernahme-Schalters, aber vor der Fehlerprüfung ausgeführt. So wird z. B. das Datum der letzten Änderung angepasst.

ListingEditor.Callbacks.VALIDATE_FORM_CALLBACKS: Funktionen zur Überprüfung der Eingaben.

SisterSite

Stellt Funktionen zur Anbindung an Schwester-Wikis bereit. Über die Ajax-Schnittstelle können Daten aus diesen Wikis für den Editor bereit gestellt werden.

Core

Kernfunktionen einschließlich der Initialisierung.

Initialisierung

ListingEditor.Core.init() bzw. ListingEditor.Core.initListingEditor() führt nach Abschluss des Ladens der Artikelseite folgende Arbeitsschritte durch:

1. Test, ob sich Seite überhaupt für den vCard-Editor eignet.
2. Die mit einer h2- bzw. h3-Überschrift versehenen Abschnitte werden ein ein neu angelegtes div-Tag mit den Klassen voy-h2-section bzw. voy-h3-section. Diese Wrapper-Tags dienen dem schnelleren Zugriff auf diese Abschnitte bzw. deren {{vCard}}s/Listings und schaffen die Voraussetzung, dass neue vCards am Abschnittsende eingefügt werden können.
3. h2-Überschriften, die in der Variablen ListingEditor.Config.SECTION_TO_TEMPLATE_TYPE genannt sind, und deren h3-Unterüberschriften erhalten den Schalter „vCard hinzufügen“. Dies muss für jeden Skin in unterschiedlicher Weise realisiert werden. (siehe auch den folgenden Abschnitt).
   1. Vector: Suche nach $(parentHeading).next('.mw-editsection'). Der Schalter „vCard hinzufügen“ wird hinter den „Bearbeiten-Schalter“ hinzugefügt.
   2. Minerva: Suche nach $(parentHeading).next('span'). Der Schalter „vCard hinzufügen“ wird als Bild-Symbol hinter das „Bearbeiten-Symbol“ hinzugefügt.
4. Die vCards/Listings erhalten den Schalter „Bearbeiten“. Er wird in das vCard-Tag <span class="listing-metadata-items"> eingefügt. Dieses Tag könnte zusätzlich das Datum der letzten Änderung erhalten.
5. Aus der ersten vCard werden die Werte data-currency (Landeswährung) und data-country-calling-code (Ländervorwahl) ausgelesen und in das body-Tag kopiert. Über die Wikidata-Id des Artikels wird aus Wikidata, wenn vorhanden, die Ortsvorwahl bezogen und als data-local-calling-code (Ortsvorwahl) in das body-Tag kopiert.

Mit window.suppressListingEditor = true; kann man den vCard-Editor ausschalten. Hierfür gibt es auch ein passendes Helferlein unter den „Bearbeitungswerkzeuge“. Hauptzweck ist der Test einer anderen experimentellen Version des Editors.

Im Hauptnamensraum und im Benutzernamensraum dürfen h2- und h3-Überschriften nicht in andere Tags wie <div> eingebettet werden!

Probleme mit dem Wrapper-Tag

Das Wrapper-Tag wird benötigt, um zum einen die zur vCard zugehörige section-Nummer und zum anderen die aktuelle vCard-Nummer in dieser section zu bestimmen.

Das Einfügen des Wrapper-Tags verändert natürlich den Quelltext. Das Einfügen geschieht nicht korrekt in die DOM-Hierarchie, sondern Start- und Endtag werden an „beliebige“ Stellen gepackt. Bisher sind folgende Problemfälle bekannt:

1. Im HTML-Code gibt es gelegentlich h1-, h2- und h3-Tags ohne den Bearbeiten-Link. Diese Tags sollten beim Wrappen nicht berücksichtigt werden. – Gelöst
2. Ein div-Tag, das die Überschriftentags umspannt, stört das korrekte Einfügen des Wrappers.

Als sichtbare Störung werden Links aus dem nach dem Wrapper befindlichen Absätzen entnommen und vor den Absatz positioniert.

Schalter [ vCard hinzufügen ]

Der Schalter [ vCard hinzufügen ] wird nur an ausgewählten Überschriften angefügt. Damit soll bewirkt werden, dass nur in diesen Abschnitten und Unterabschnitten {{vCard}}s ergänzt werden können bzw. dass andere Absätze keinesfalls eine {{vCard}} erhalten. In der Konfigurationsvariablen ListingEditor.Config.SECTION_TO_TEMPLATE_TYPE sind die Überschriften definiert, die den Schalter [ vCard hinzufügen ] bekommen sollen und zusätzlich der Standardtyp für die Vorlage {{vCard}}. Momentan sind folgende Überschriften möglich: Anreise, Mobilität, Sehenswürdigkeiten, Aktivitäten, Einkaufen, Küche, Nachtleben, Unterkunft, Lernen, Arbeiten, Sicherheit, Gesundheit und Praktische Hinweise.

Um Ortsartikel von Regionenartikeln unterscheiden zu können, wird nach Überschriften gesucht, die in Regionenartikeln vorkommen können, aber niemals in Ortartikeln vorkommen. Wird eine solche Überschrift gefunden, erhält keine der Überschriften den Schalter [ vCard hinzufügen ]. Diese Ausschlussliste wird in der Variablen ListingEditor.Config.DISALLOW_ADD_LISTING_IF_PRESENT definiert und enthält die Überschriften Orte, Weitere Ziele, Städte, Regionen und Inseln.

Öffnen des vCard/Listing-Editors

Erster Schritt

1. Nach Drücken der „vCard hinzufügen“- oder „Bearbeiten“-Schalter wird die Funktion ListingEditor.Core.initListingEditorDialog() aufgerufen.
2. Es erfolgt die Dialog-Ausschrift „Starte vCard-Editor…“.
3. Im Fall von „vCard hinzufügen“ wird aus der Überschrift ein geeigneter Typ bestimmt (z. B. Sehenswürdigkeiten -> see).
4. Es wird die nächsthöhere h3- oder h2-Überschrift gesucht und dessen section-Nummer bestimmt.
5. „Bearbeiten-Schalter gedrückt“: ListingEditor.Core.findListingIndex() ermittelt die Nummer der angewählten vCard in der section aus dem HTML-Quelltext.
6. Es werden die Werte für Währung (data-currency) und Landesvorwahl (data-country-calling-code) aus der vCard selbst oder dem body-Tag geladen.
7. Es wird die Ortsvorwahl (data-local-calling-code) aus dem body-Tag geladen.
8. Es wird eine Ajax-Anfrage gestartet, die den Quelltext der vorher bestimmten section liefern soll.
   1. Es ist dabei kein Fehler aufgetreten: Es wird die Funktion ListingEditor.Core.openListingEditorDialog() aufgerufen. Die Daten wurden in der Variablen sectionText hinterlegt.
   2. Die Dialog-Ausschrift „Starte vCard-Editor…“ wird entfernt. Es wird eine Fehlermeldung zur Ajax-Initialisierung („Fehler: vCard-Editor kann nicht vorausgefüllt werden.“) ausgegeben.

Zweiter Schritt

1. ListingEditor.Core.openListingEditorDialog() fordert den Ressource jquery.ui an.
2. Aus sectionText werden die Kommentare entfernt.
3. Nun werden die Daten bereitgestellt:
   1. „vCard hinzufügen“: Leeres Array listingTemplateAsMap, nur Typ (aus der Überschrift bestimmt), wird gesetzt.
   2. „Bearbeiten“: Über den im ersten Schritt bestimmten listingIndex wird der WikiSyntax-Quelltext der zugehörigen Vorlage {{vCard}}/Listing ausgewählt. Die einzelnen Vorlagenparameter werden in das Array listingTemplateAsMap übernommen. Der Type der Einrichtung wird ausgelesen.
4. ListingEditor.Core.createForm() legt Formularelemente an und befüllt sie.
5. Aufruf der ListingEditor.Callbacks.CREATE_FORM_CALLBACKS.
6. Formular-Dialog wird unter Nutzung der Formularelemente angelegt und angezeigt.
7. Aktionsschalter und Lizenztext werden eingefügt.

Variablen ListingEditor.Config

	var VERSION = '2.x-de';
	var LANG = 'de';
	var COMMONS_URL = '//commons.wikimedia.org';
	var WIKIDATA_URL = '//www.wikidata.org';
	var WIKIPEDIA_URL = '//de.wikipedia.org';
	var WIKIDATA_SITELINK_WIKIPEDIA = 'dewiki';
	var TRANSLATIONS =
	var YES_ARRAY = { 'y': '', 'yes': '', 'j': '', 'ja': '', 'true': '' };
	var NO_ARRAY = { 'n': '', 'no': '', 'nein': '', 'false': '' };
	var WIKIDATA_CLAIMS =
	var REGEX =
	var FIELDS =
	var MAX_DIALOG_WIDTH = 1200;
	var ALLOW_UNRECOGNIZED_PARAMETERS = true;
	var SECTION_TO_TEMPLATE_TYPE =
	var COORD_LETTERS =
	var DEFAULT_LISTING_TEMPLATE = 'vCard';
	var DEFAULT_TEMPLATE_NO_TYPE = true;
	var LISTING_TYPE_PARAMETER = 'type';
	var LISTING_CONTENT_PARAMETER = 'description';
	var EDIT_LINK_CONTAINER_SELECTOR = 'span.listing-metadata-items';
	var SKIP_DEFAULT = true;
	var LISTING_TEMPLATE_PARAMETERS =
	var HIDE_AND_SHOW =
	var LISTING_TEMPLATES =
	var EDITOR_FORM_SELECTOR = '#listing-editor';
	var EDITOR_CLOSED_SELECTOR = '#input-closed';
	var EDITOR_SUMMARY_SELECTOR = '#input-summary';
	var EDITOR_MINOR_EDIT_SELECTOR = '#input-minor';
	var DEFAULT_PLACEHOLDERS =
	var GROUP_PROPERTIES =
	var LISTING_TYPE_OPTIONS =
	var INTL_CURRENCIES = [ '€', '$', '£', '¥', '₩' ];
	var EDITOR_FORM_HTML =

	// expose public members
	return {
		VERSION: VERSION,
		LANG: LANG,
		COMMONS_URL: COMMONS_URL,
		WIKIDATA_URL: WIKIDATA_URL,
		WIKIPEDIA_URL: WIKIPEDIA_URL,
		WIKIDATA_SITELINK_WIKIPEDIA: WIKIDATA_SITELINK_WIKIPEDIA,
		WIKIDATA_CLAIMS: WIKIDATA_CLAIMS,
		TRANSLATIONS: TRANSLATIONS,
		MAX_DIALOG_WIDTH: MAX_DIALOG_WIDTH,
		DISALLOW_ADD_LISTING_IF_PRESENT: DISALLOW_ADD_LISTING_IF_PRESENT,
		DEFAULT_LISTING_TEMPLATE: DEFAULT_LISTING_TEMPLATE,
		DEFAULT_TEMPLATE_NO_TYPE: DEFAULT_TEMPLATE_NO_TYPE,
		LISTING_TYPE_PARAMETER: LISTING_TYPE_PARAMETER,
		LISTING_CONTENT_PARAMETER: LISTING_CONTENT_PARAMETER,
		DEFAULT_PLACEHOLDERS: DEFAULT_PLACEHOLDERS,
		HIDE_AND_SHOW: HIDE_AND_SHOW,
		EDIT_LINK_CONTAINER_SELECTOR: EDIT_LINK_CONTAINER_SELECTOR,
		ALLOW_UNRECOGNIZED_PARAMETERS: ALLOW_UNRECOGNIZED_PARAMETERS,
		SECTION_TO_TEMPLATE_TYPE: SECTION_TO_TEMPLATE_TYPE,
		LISTING_TEMPLATES: LISTING_TEMPLATES,
		LISTING_TEMPLATE_PARAMETERS: LISTING_TEMPLATE_PARAMETERS,
		EDITOR_FORM_SELECTOR: EDITOR_FORM_SELECTOR,
		EDITOR_CLOSED_SELECTOR: EDITOR_CLOSED_SELECTOR,
		EDITOR_SUMMARY_SELECTOR: EDITOR_SUMMARY_SELECTOR,
		EDITOR_MINOR_EDIT_SELECTOR: EDITOR_MINOR_EDIT_SELECTOR,
		LISTING_TYPE_OPTIONS: LISTING_TYPE_OPTIONS,
		GROUP_PROPERTIES: GROUP_PROPERTIES,
		EDITOR_FORM_HTML: EDITOR_FORM_HTML,
		YES_ARRAY: YES_ARRAY,
		NO_ARRAY: NO_ARRAY,
		COORD_LETTERS: COORD_LETTERS,
		REGEX: REGEX,
		FIELDS: FIELDS,
	};

Funktionen ListingEditor.Core

	listingEditorAllowedForCurrentPage()
	createForm(mode, listingParameters, listingTemplateAsMap)
	wrapContent()
	addListingButtons()
	insertAddListingPlaceholder(parentHeading): appending the "add listing" link text to a heading
	addEditButtons()
	isInline(entry): return true;
	findSectionHeading(element)
	findSectionIndex(heading)
	findListingIndex(sectionHeading, clicked)
	replaceSpecial(str)
	getListingTypesRegex()
	getListingWikitextBraces(listingIndex)
	checkYesNo(value)
	wikiTextToListing(listingTemplateWikiSyntax)
	listingTemplateToParamsArray(listingTemplateWikiSyntax)
	findPatternMatch(value, startPattern, endPattern)
	initListingEditorDialog(mode, clicked)
	openListingEditorDialog(mode, sectionNumber, listingIndex, listingType)
	stripComments(text)
	restoreComments(text, resetReplacements)
	getListingInfo(type)
	isCustomListingType(listingType)
	validateForm()
	formToText(mode, listingTemplateWikiSyntax, listingTemplateAsMap, sectionNumber)
	showPreview(listingTemplateAsMap)
	formToPreview(listingTemplateAsMap)
	refreshPreview(listingTemplateAsMap)
	hidePreview()
	editSummarySection()
	getSectionName()
	updateSectionTextWithAddedListing(originalEditSummary, listingWikiText, listing)
	updateSectionTextWithEditedListing(originalEditSummary, listingWikiText, listingTemplateWikiSyntax)
	closeForm(selector)
	progressForm(selector, text)
	saveForm(summary, minor, sectionNumber, cid, answer)
	saveFailed(msg)
	captchaDialog(summary, minor, sectionNumber, captchaImgSrc, captchaId)
	listingToStr(listing)
	isElementEmpty(element)
	rtrim(str)
	trimDecimal(value, precision)
	initListingEditor()

Kategorien

• Wartungskategorie: Keine