User:Eleazaros/coords.js/doc

Overview of the map tooltip system

Map tooltips are ubiquitous on LOTRO-Wiki. Using a simple template, users can easily add a tooltip showing a particular location on a map. For example, {{Tooltip Coords|Bree-town|29.8S|51.3W}} results in the following: ^{[29.8S, 51.3W]}

The main components of the system are

• the map images themselves, e.g. File:Bree-land map.jpg
• the Tooltip Coords template
• the javascript file User:Eleazaros/coords.js

Additional components are

• the GetMapInfo lua module, for identifying invalid coordinates
• the LocationList template and LocationList lua module, for generating tables of coordinates

Template:Tooltip Coords

This template is the main user interface to the system. Full documentation for how to use it is available on its /doc page.

The function of this template is to create a <span> tag with a certain class attribute, for later processing by User:Eleazaros/coords.js. The tag uses the following format:

<span class="coordslink map--northsouth--eastwest"> [northsouth, eastwest] </span>

where

• map is the name of the map, e.g. Bree-town
• northsouth is the north/south coordinate, e.g. 29.8S
• eastwest is the east/west coordinate, e.g. 51.3W

So, for example, {{Tooltip Coords|Bree-town|29.8S|51.3W}} would create the following HTML:

<span class="coordslink Bree-town--29.8S--51.3W">[29.8S, 51.3W]</span>

This <span> tag is later discovered by User:Eleazaros/coords.js by searching for the class="coordslink ..." attribute.

User:Eleazaros/coords.js

This javascript file, which is invoked in MediaWiki:Common.js, runs after each page is loaded. Its main purpose is to find the <span> tags created above and add mouse behaviors to them, so that when the mouse hovers over them, the appropriate map image is displayed, with a "swirly" icon in the correct location.

Besides the functions necessary to do this, it also contains a complete list of the maps in the game. For each map, it has the boundary coordinates (top, left, right, bottom). This is the central place on LOTRO-Wiki where the map information is stored; it is not duplicated elsewhere.

Module:GetMapInfo

This lua module, which is invoked in Template:Tooltip Coords, is responsible for checking the arguments of that template. In particular, it makes sure that the specified map exists, and if so, that the specified coordinates are within the boundaries of the map. If not, then it adds the page to Category:Invalid Coordinates.

To do its work, this module reads in and parses the entire source code of User:Eleazaros/coords.js to extract the list of maps and their boundaries.

A secondary function of this module is to generate the list of maps at Template:Tooltip_Coords#Maps_with_coordinates.

Template:LocationList and Module:LocationList

This template (and the module which implements the functionality) are for creating tables of coordinates to be shown on the same map toolip. For example:

{{LocationList
| The Shire | 31.4S | 71.1W | Hobbiton
| The Shire | 28.0S | 76.0W | Needlehole
| The Shire | 33.3S | 65.7W | Woodhall
}}

Coordinates	Directions / Description
[31.4S, 71.1W]	Hobbiton
[28.0S, 76.0W]	Needlehole
[33.3S, 65.7W]	Woodhall

The template creates a table with class="locationList", with a Tooltip Coords template in each row.

When User:Eleazaros/coords.js finds a table with class="locationList", it groups all of the coordinates in the table together, so that when the mouse hovers over any of them, the map is displayed with all of the dots shown.

How to add new maps to LOTRO-Wiki

This is the procedure for adding a new map to LOTRO-Wiki when it is added to the game.

1. Get the map file from the game client:
   • Don't attempt to do a screen capture. This will show menus and icons superimposed over the map. We want the raw map itself, with nothing overlaid.
   • Extract the .JPG directly from the game files (client_local_English.dat) using DAT_UNPACKER and XnView.
   • Ask in discord for help.
2. Upload the file to lotro-wiki as "Region_map.jpg"
   • The word "map" must be in lowercase in the filename and be preceded by a space or underscore (spaces and underscores are interchangeable in LOTRO-Wiki filenames).
   • If the region name starts with "The" (e.g. "The Shire"), don't put "The" in the filename (e.g. "Shire_map.jpg", not "The_Shire_map.jpg").
3. Find the map's boundary coordinates:
   • Open the game client and view the map.
   • Move the cursor to each edge of the map, noting the coordinates of the top, bottom, left and right sides.
4. Add the boundary coordinates to User:Eleazaros/coords.js (see Adding map data below).
5. Alternate names for the region can be given in User:Eleazaros/coords.js (see Aliases below).
6. Add the new map to an appropriate subcategory of Category:Regional Maps.
7. Add the new map to the Maps page.

Adding map data

Before tooltips can be made with the new map file, its filename and boundary coordinates must be added to User:Eleazaros/coords.js. Note that admin privileges are required for modifying this file.

To add a new map, create a new element in the MapData array. Before doing so, you must assign the correct sign (+/-) to the coordinates:

• We use negative numbers for South and West.
• We use positive numbers for North and East.

If the name of the region begins with "The", remove it. It will be added by the script if necessary.

Example. For the Vales of Anduin, we note the following boundaries in the game client:

• top edge of the screen = 18.3N (North is positive, so we use 18.3)
• left edge of the screen = 81.4W (West is negative, so we use -81.4)
• bottom edge of the screen = 12.4S (South is negative, so we use -12.4)
• right edge of the screen = 40.4W (West is negative, so we use -40.4)

Therefore, the MapData entry should be

MapData["Vales of Anduin"] = { top:18.3, left:-81.4, bottom:-12.4, right:-40.4 };

Aliases

If a region has more than one name, and you wish to support both names in the Template:Tooltip Coords template, you can create an alias instead of a duplicate MapData entry.

Example. For Annúminas, we have the MapData entry:

MapData["Annúminas"] = { top:-15.5, left:-73.5, bottom:-21.2, right:-65.9 };

But since the ú is difficult to type, we want people to be able to type Annuminas instead, i.e. {{Tooltip Coords|Annuminas|...}}. To enable this, we create an alias:

MapData["Annuminas"] = "Annúminas";

Instance maps with their own coordinate systems

Sometimes an instance occurs in the same location as landscape content, but has a different coordinate system. For example, the instance At the Stone of Erech occurs in the Blackroot Vale. If you stand near the Stone of Erech while in the instance, your coordinates will be 99.6S, 88.6W. If you stand in the same position on the landscape, your coordinates are 58.0S, 65.0W.

When documenting landscape content, people can use {{Tooltip Coords|Blackroot Vale|58.0S|65.0W}}. When documenting the instance, we would like to allow people to use {{Tooltip Coords|At the Stone of Erech|99.6S|88.6W}} to display the same point on the same map.

The procedure:

1. First you need to figure out the distance between the two coordinate systems:

   Find a point in the instance, and the same point on the landscape:

   Instance location = 99.6S, 88.6W

   Landscape location = 58.0S, 65.0W

   Convert the coordinates to signed numbers, using positive (+) for North and East, negative (-) for South and West:

   Instance location = -99.6, -88.6

   Landscape location = -58.0, -65.0

   Subtract the landscape coordinates from the instance coordinates:

   North/South offset = (-99.6) - (-58.0) = -41.6

   East/West offset = (-88.6) - (-65.0) = -23.6

2. Next, find the existing MapData entry:

   MapData["Blackroot Vale"] = { top:-51.0, left:-83.3, bottom:-71.4, right:-56.0 };

3. Then, shift the coordinate system by adding the calculated offsets:

   Add -41.6 to the top and bottom values:

   top: -51.0 + (-41.6) = -92.6

   bottom: -71.4 + (-41.6) = -113

   Add -23.6 to the left and right values:

   left: -83.3 + (-23.6) = -106.9

   right: -56.0 + (-23.6) = -79.6

   So, the new MapData entry will be

   MapData["At the Stone of Erech"] = { top:-92.6, left:-106.9, bottom:-113, right:-79.6 };

4. Add this to User:Eleazaros/coords.js (under "Instances or areas which use the same .jpg as an open-world map, but with different coordinates").
5. Finally, create a redirect from File:At the Stone of Erech map.jpg to the existing map File:Blackroot Vale map.jpg.

Result:

{{Tooltip Coords|Blackroot Vale|58.0S|65.0W}} is the same as {{Tooltip Coords|At the Stone of Erech|99.6S|88.6W}}

^{[58.0S, 65.0W]} is the same as ^{[99.6S, 88.6W]}