Wikivoyage:Listing editor

From Wikivoyage
Jump to navigation Jump to search

This is a form-based listing editor that can be used to add and edit listings. See also Wikivoyage:Listings.

How to use

Each listing can be described by entering the following into the listings form.

  • Name: the name of the hotel, bar, restaurant, museum, or whatever. Recommended.
  • Alt: an alternative name, either in the local language or just an alternative. Optional.
  • Website: the URL for the official Web site for this attraction (see external links for more guidelines). Recommended.
  • Address: a street address for finding the attraction, for places where this is meaningful. Recommended.
  • Directions: additional brief directions besides the street address, such as cross streets, nearby subway or bus stations. Optional.
  • Phone: a phone number for making reservations or getting more information. Recommended.
  • Tollfree: a toll-free phone number, if available. Optional.
  • Email: an email address for making reservations or getting more information. Optional.
  • Latitude: Decimal latitude (GPS coordinates) for map output. Recommended.
  • Longitude: Decimal longitude (GPS coordinates) for map output. Recommended.
    • Note: lat and long should have the same number of decimal places (using trailing zeroes if applicable). If one is present, so should the other be. Click on the link to GeoMap for easy access to a OSM-based locator. Google Maps coordinates are highly discouraged.
  • Hours: opening hours of the attraction, when applicable. Recommended.
  • Price: price of a room, or price of a drink, or price of an average meal, or price of admission. Recommended.
  • Wikidata: the Wikidata page for the attraction, if one exists. This field should only be used if a record for the specific location exists—for example, a link to the Wikidata record for the Raffles Hotel would be appropriate, but a link for the McDonald's company Wikidata page is not.
  • Wikipedia: the Wikipedia page for the attraction, if one exists. Again, do not provide a value to a brand or company page; only provide a value if a Wikipedia page for the specific location exists.
  • Image: an image on Commons that will be displayed for the listing's point of interest on the dynamic map. Note that the value specified should exclude the "File:" namespace for the image ("Example.png", not "File:Example.png"). Like the Wikidata and Wikipedia fields, do not provide generic images; only provide an image if it is of the specific location.
  • Update shared fields using values from Wikidata: This link is only present if a Wikidata value has been entered. If clicked it will sync any existing values in the fields marked with the Wikidata logo with values from the shared Wikidata record.
  • Mark the listing as up-to-date?: check this checkbox if the information in the listing has been verified as being up-to-date; doing so will cause the "last edit" date for the listing to update to the current date. Optional.
  • Delete this listing?: check this checkbox if the business is no longer in operation, and the listing will be removed from the article. Optional.
  • Edit summary: a brief description of the changes being made that will be recorded in the article history. Recommended.
  • Minor change?: a checkbox that can be used to indicate that an edit is minor, such as when fixing a typo. Optional.

There are several other parameters described at Wikivoyage:Listings.


Before opening listing editor
After clicking the edit button for a listing

Forms are familiar features to users, allowing for specific parameters to be shown or hidden, and providing extra functionality like links to help pages. The editor allows for flexibility of templates, relying more heavily on wikitext instead of the actual HTML structure. It targets listings with span class="vcard", and their corresponding names (span class="org"), addresses (span class="label") and alternative nicknames (span class="nickname"). Targeted geocoding can be achieved by including <span id="geodata">lat; long</span> inside a separate {{geo}} or quickbar template.

  • Adds [add listing] buttons to second and third-level headings of articles without 'Cities' or 'Other destinations' (will add listing to topics with 'See', 'Do', 'Buy', 'Eat', 'Sleep' and 'Connect' headings', even travel topics)
  • Assigns type based on heading names
  • Adds grey edit button to listings
  • Opens form that lists parameters of the {{listing}} template.
  • Automatic edit summary

Bugs and feedback

Feel free to report bugs here. Try and describe the odd behaviour, and if possible, give an example listing or article where this occurs.

  • The "wrapContent" method can cause problems with complex HTML around headings. For an example see the "collapse" link at WV:Votes for deletion#Archving.
  • Wrong listing is selected when edit button is clicked on an old version of page: If I view an old copy of a page, which has subsequently had new listings added above the one I am trying to edit, the editor brings up the wrong listing. That is, if I select the nth listing on an old page, the editor selects the nth listing of the current page. Peter Chastain (talk) 13:36, 16 January 2016 (UTC)[reply]
A somewhat related issue: If I begin to edit a listing with the listing editor, and then someone else edits and saves the article, and I then save my changes, the other editor's changes are lost. Peter Chastain (talk) 20:02, 16 January 2016 (UTC)[reply]

Feature requests

Please discuss feature requests at Wikivoyage talk:Listing editor prior to adding below so that others can provide feedback and suggestions.

  • Mobile support. Allow the listing editor to be used on mobile devices.
  • Better geocoding. Make it easier to integrate GeoMap and enter latitude/longitude, perhaps a single line rather than two text inputs, or even the ability to launch a small OpenStreetMap popup to click the point.
  • Loading times. The listing editor has the equivalent load time of editing a section plus additional time for creating and opening the form. The script runs sequentially, waiting for the API to return the section to be edited, then creates the form. Technically the form could be created during the wait instead of after (might reduce loading time by 20-30%).

How to install

  • Try testing as a non-default gadget for testing before sitewide implementation in Mediawiki namespace.
  • Add the following to MediaWiki:Gadgets-definition, this makes the gadget default. Note: name of gadget must match script files
* ListingEditor[ResourceLoader|default|dependencies=mediawiki.util,jquery.ui.dialog]|ListingEditor.js|ListingEditor.css



The ListingEditor.Config module contains parameters that must be customized for each language.

Strings that must be translated into the local language.
Maximum allowed width of the listing editor (specified in pixels)
Flag indicating whether or not the listing editor should automatically strip out template parameters that it does not recognize when a listing is saved. The list of "recognized" parameters are configured in the LISTING_TEMPLATES configuration array.
Array that specifies what listing template should be used for each article section. Note that the array matches by section ID, so underscores are required instead of spaces.
A list of JQuery selectors that, if matched, will prevent the listing editor from adding "add listing" links to any section on the page. Useful for preventing "add listing" links from being added to country or region articles.
The name of the default listing template. On English Wikivoyage the default listing template is Template:Listing.
Listing template parameter indicating the template type. On English Wikivoyage this is the "type" parameter.
Listing template parameter indicating the template content. On English Wikivoyage this is the "content" parameter.
Template:Listing must be configured with an HTML element that will contain "edit listing" links, and this parameter specifies a JQuery selector that matches that HTML element.
This configuration object links the listing editor HTML (as specified in the EDITOR_FORM configuration value) to the wiki syntax used as the template parameters. A single configuration array can be specified if all listing templates behave the same, or multiple arrays can be specified to support different behavior for different templates - for example, on English Wikivoyage a separate SLEEP_TEMPLATE_PARAMETERS array is configured to support the fact that the sleep template uses "checkin" and "checkout" instead of "hours.
This array links each supported template type to its configuration object. For example, template "listing" uses LISTING_TEMPLATE_PARAMETERS.
A JQuery selector that will match the listing editor UI specified in EDITOR_FORM.
A JQuery selector that will match the listing editor UI specified in EDITOR_FORM corresponding to the input indicating that a listing should be removed from the site.
A JQuery selector that will match the listing editor UI specified in EDITOR_FORM corresponding to the edit summary input field.
A JQuery selector that will match the listing editor UI specified in EDITOR_FORM corresponding to the checkbox indicating that an edit is a minor edit.
The HTML to use for the listing editor UI.


Different language versions may wish to implement custom functionality, which is supported via the ListingEditor.Callbacks module. There are currently three types of callbacks supported:

Called when the listing editor UI is created. The default configuration includes callbacks that initialize the geomap and currency symbol functionality.
Called when the listing editor form is submitted but prior to validating the data. The default configuration includes callbacks that process the "last edit" date.
Called when the listing editor form is submitted and after the submit form callbacks have been invoked. Validator functionality includes verifying that a listing is not empty, and that any entered email address is valid. If a validator returns a non-empty message string then that value will be displayed to the user and the form will not be submitted.


v2.4.2 Changes

  • Fix "Add trailing period in content" when "?" or "!" is present

v2.4.1 Changes

  • Added link to commons to easily access, see and compare images in "WD sync" window
  • Avoid false positive when compare two images where the local one is written with underscores in place of spaces
  • Coords in decimal format cannot exceed 6 digits (note: 6 digits have an accuracy of ~11 cm)

v2.4 Changes

  • Table to Div form conversion
  • DMS notation supported (used in it:voy & de:voy)
  • Restore geomap-link functionality and update in realtime the coords. Use the best available coords between listing and article one
  • Close sync form when main listing editor form is closed
  • Skip validation form process upon deletion request
  • Allow edit summary also during ADD phase to provide credit or other info
  • Fix lint & HTML errors generated dynamically
  • Coords nullify link removed
  • Add trailing period in content
  • Update or hide correctly Wikipedia/Commons links after WD sync
  • Prevent editing issues when '$&' sequence is present in the listing
  • Prevent JS error when first listing value has no parameter
  • Wmflabs -> toolforge URL migration to avoid useless redirect
  • Use of global/local variables in place of hard coding
  • CSS & style cleanup
  • Minor cleanups

v2.3 Changes

  • Import shortcut for national currency, national calling code and local calling code from Italian Wikivoyage
  • Fix multilingual incompatibility between updateWikidataSharedFields and the older quickUpdateWikidataSharedFields
  • Minor cleanups

v2.2 Changes

  • Create bidirectional Wikidata Sync window with reference support
  • Automatically fill IATA code for airports if Alt is empty
  • Sync directions with Wikidata
  • Trim period from price and address
  • Import preview functionality from German Wikivoyage
  • Add button to get Wikidata ID from given Wikipedia article
  • Add button to replace coordinates with NA
  • Fx linterrors by phasing out <p> in favor of <br>
  • Minor cleanup of template format
  • Display color in type selectors
  • Detect RTL text in alt field
  • Support go as listing type

v2.1 Changes

  • Wikidata & Wikipedia fields added.
  • The Wikidata, image, and Wikipedia fields will now autocomplete, with lookups done by searching the relevant site.
  • Latitude, longitude, official link, wikipedia link, and image can be populated with the values stored at Wikidata by clicking on the "Update shared fields using values from Wikidata" link.
  • The "image" field is now shown by default.
  • Several cleanups to the underlying code.
  • Fix a bug where listing types were not handled in a case-insensitive way, prventing editing of templates using types such as "Do".

v2.0.x Changes

  • Fix a bug where editing inline listings containing newlines was not working correctly.
  • Make VisualEditor work with listing editor - phab:T122454.
  • Fix bug where non-standard "type" attributes are deleted (example: "type=go").
  • Do not leave excess newlines when deleting a listing if there is a newline before and after the listing.
  • The listing edit summary should use the name of the section being edited, not the type of the listing being edited.
  • Fix a bug that prevented deletion of listings containing duplicate dollar signs ("$$").
  • Editing from a "diff" page will no longer reload the diff page when saving an edit, but will instead take the user to the page's canonical URL so that they can see their changes.
  • Fix bug where deletion failed when a listing was part of a definition list (example: *: {{listing}})

v2.0 Changes

  • Update the listing editor dialog UI to provide more space for field entry, and to responsively collapse from two columns to one on small screens.
  • Use mw.Api().postWithToken instead of $.ajax to hopefully fix session token expiration issues.
  • Add support for editing of multi-paragraph listings.
  • Do not delete non-empty unrecognized listing template values (wikipedia, phoneextra, etc) when editing if the ALLOW_UNRECOGNIZED_PARAMETERS flag is set to true.
  • If listing editor form submit fails, re-display the listing editor form with the content entered by the user so that work is not lost.
  • Replace synchronous $.ajax call with asynchronous.
  • Allow edit summaries and marking edits as minor when editing listings.
  • Move 'add listing' link within the mw-editsection block.
  • Automatically replace newlines in listing content with <p> tags.
  • Fix bug where HTML comments inside listing fields prevented editing.
  • Provide configuration options so that some fields can be displayed only if they have non-empty values (examples: "fax" in the default configuration).
  • Add basic email address validation.
  • A failed captcha challenge no longer causes further captcha attempts to fail.
  • Significant code reorganization.

v1.4.0 Changes

  • CAPTCHA dialog on addition of new external links for anon IPs
  • Shows edit buttons depending on protection level

v1.3.5 Changes

  • Added ability to remove closed listings
  • Fix fourth-level heading glitch
  • Fix [add listing] to screen-only in CSS
  • Fixed label bug (input-type instead of form-type)
  • Warn about external link
  • Add breakpoints <br> in place of newlines in the content description

v1.3.3 Changes

  • Slight adjustment for headings with special characters

v1.3.2 Changes

  • Adjusted for other language headings and types

v1.3.1 Changes

  • Corrected for single-line listings
  • Fixed single parameter bug

v1.3.0 Changes

  • Added link to help page
  • Added geomap link for address/name
  • Fixed whitespace bug

v1.2.8 Changes

  • Get uncached version

v1.2.6 Changes

  • Converted to flat form
  • Added geomap link
  • Added currency buttons
  • Accounted for nested templates

v1.1.0 Changes

  • Added [add listing] button

v1.0.0 Changes

  • Initial release