Wikivoyage:Listing editor

From Wikivoyage
Jump to: navigation, search

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

How to use[edit]

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 overwrite any existing values in the website, latitude, longitude, Wikipedia and image fields 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.

Features[edit]

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[edit]

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

  • Add mouse cursor back to price after clicking currency sign
  • 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)
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)
  • Template:Go breaks the listing editor. See Cleveland#By plane for an example - the listing type is unrecognized and the editor does not open. -- Ryan • (talk) • 02:34, 26 January 2017 (UTC)
  • When clicking any following section other than listings under the first section, information for another listing that is further up will be displayed, rather than the one being selected. Results in "Error: An unknown error has been encountered while attempting to save the listing, please try again: invalidsection" when saving. – Craig Davison (talk) 08:27, 18 April 2018 (UTC)

Feature requests[edit]

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.
  • Currency. More currency options - a question of layout rather than functionality.
  • Country-specific info. Pre-populate some country-specific data such as currency symbol or country calling code. Per User:WOSlinker it may be possible to determine country from the breadcrumbs:
var level1 = $("#contentSub a:nth-child(1)").html();
var level3 = $("#contentSub a:nth-child(3)").html();
var country;
if (level1 == 'Asia') country=level3;
  • 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%).
  • Preview. See Wikivoyage talk:Listing editor#Feature request: Preview button.

How to install[edit]

  • 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

Versions[edit]

Configuration[edit]

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

TRANSLATIONS
Strings that must be translated into the local language.
MAX_DIALOG_WIDTH
Maximum allowed width of the listing editor (specified in pixels)
ALLOW_UNRECOGNIZED_PARAMETERS
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.
SECTION_TO_TEMPLATE_TYPE
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.
DISALLOW_ADD_LISTING_IF_PRESENT
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.
DEFAULT_LISTING_TEMPLATE
The name of the default listing template. On English Wikivoyage the default listing template is Template:Listing.
LISTING_TYPE_PARAMETER
Listing template parameter indicating the template type. On English Wikivoyage this is the "type" parameter.
LISTING_CONTENT_PARAMETER
Listing template parameter indicating the template content. On English Wikivoyage this is the "content" parameter.
EDIT_LINK_CONTAINER
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.
LISTING_TEMPLATE_PARAMETERS
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.
LISTING_TEMPLATES
This array links each supported template type to its configuration object. For example, template "listing" uses LISTING_TEMPLATE_PARAMETERS.
EDITOR_FORM_SELECTOR
A JQuery selector that will match the listing editor UI specified in EDITOR_FORM.
EDITOR_CLOSED_SELECTOR
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.
EDITOR_SUMMARY
A JQuery selector that will match the listing editor UI specified in EDITOR_FORM corresponding to the edit summary input field.
EDITOR_MINOR_EDIT
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.
EDITOR_FORM
The HTML to use for the listing editor UI.

Callbacks[edit]

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:

CREATE_FORM_CALLBACKS
Called when the listing editor UI is created. The default configuration includes callbacks that initialize the geomap and currency symbol functionality.
SUBMIT_FORM_CALLBACKS
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.
VALIDATE_FORM_CALLBACKS
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.

Changelog[edit]

2.1.x
  • 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, preventing editing of templates using types such as "Do".
2.0.x
  • 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}})
2.0
  • 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.
1.4.0
  • CAPTCHA dialog on addition of new external links for anon IPs
  • Shows edit buttons depending on protection level
1.3.5
  • 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
1.3.3
  • Slight adjustment for headings with special characters
1.3.2
  • Adjusted for other language headings and types
1.3.1
  • Corrected for single-line listings
  • Fixed single parameter bug
1.3.0
  • Added link to help page
  • Added geomap link for address/name
  • Fixed whitespace bug
1.2.8
  • Get uncached version
1.2.6
  • Converted to flat form
  • Added geomap link
  • Added currency buttons
  • Accounted for nested templates
1.1.0
  • Added [add listing] button
1.0.0
  • Initial release