Template:Map/doc - Revision history

Alex: Created page with "{{documentation}} The Map template is used to easily create interactive maps or inline links to interactive maps. To find coordinates of a specific map square, use a tool such as https://mejrs.github.io/osrs. For a guide on how to manually define maps, see RuneScape:Create Map. ==Usage== ===Basic map=== A map with no arguments will default to Lumbridge. Provide an X/Y coordinate to define where the map is centered. {| class="center" |- | {{Map}} 2024-10-15T14:48:47Z Created page with "{{documentation}} The Map template is used to easily create interactive maps or inline links to interactive maps. To find coordinates of a specific map square, use a tool such as https://mejrs.github.io/osrs. For a guide on how to manually define maps, see RuneScape:Create Map. ==Usage== ===Basic map=== A map with no arguments will default to Lumbridge. Provide an X/Y coordinate to define where the map is centered. {| class="center" |- | <code><nowiki>{{Map}}</no..." New page {{documentation}} The Map template is used to easily create interactive maps or inline links to interactive maps. To find coordinates of a specific map square, use a tool such as https://mejrs.github.io/osrs. For a guide on how to manually define maps, see [[RuneScape:Create Map]]. ==Usage== ===Basic map=== A map with no arguments will default to Lumbridge. Provide an X/Y coordinate to define where the map is centered. {| class="center" |- | <code><nowiki>{{Map}}</nowiki></code> | <code><nowiki>{{Map|3165,3494}}</nowiki></code> |- | {{Map}} | {{Map|3165,3494}} |} ===Pins=== In the following sections are various map features, such as pins, that are defined with an <code>mtype</code>. Multiple coordinates can produce multiple [[#Single-point feature|single-point features]]. Pins are mostly used to mark things that take up a 1x1 space or otherwise have an exact X/Y location. {| class="center" ! One pin !! Multiple pins |- | <code><nowiki>{{Map|mtype=pin|2965,3381}}</nowiki></code> | <code><nowiki>{{Map|mtype=pin|2638,3300|2661,3308}}</nowiki></code> |- | {{Map|mtype=pin|2965,3381|group=pins1}} | {{Map|mtype=pin|2638,3300|2661,3308|group=pins2}} |} ===Dots=== Like pins, dots are also used to mark precise locations. However, dots are better suited for marking many tightly packed coordinates. {| class="center" ! Tightly packed dots !! Cluttered pins |- | <code><nowiki>{{Map|mtype=dot ... }}</nowiki></code> | <code><nowiki>{{Map|mtype=pin ... }}</nowiki></code> |- | {{Map|mtype=dot|1843,3728|1847,3728|1851,3728|1851,3724|1851,3720|1847,3720|1843,3720}} | {{Map|mtype=pin|1843,3728|1847,3728|1851,3728|1851,3724|1851,3720|1847,3720|1843,3720|group=dots}} |} ===Text=== A text feature is another way to mark a precise location but with a label describing the subject. Though there are [[#Popups|configurable popups]], a text feature provides a more immediate and obvious label for something. {| class="center" |- | <code><nowiki>{{Map|mtype=text|2512,3466|label=Dead tree}}</nowiki></code> |- | {{Map|mtype=text|2512,3466|label=Dead tree}} |} ===Circles and squares=== Circles and squares are defined by a single point and a radius <code>r</code>. The point defines the centre of the shape and, for squares, <code>r</code> defines half the length of the square's edges—i.e., the shortest distance from its centre to one of its edges. {| class="center" ! Circle !! Square |- | <code><nowiki>{{Map|mtype=circle|r=18|3165,3490}}</nowiki></code> | <code><nowiki>{{Map|mtype=square|r=3|3316,3163}}</nowiki></code> |- | {{Map|mtype=circle|r=18|3165,3490}} | {{Map|mtype=square|r=3|3316,3163}} |} ===Rectangles=== Like circles and squares, rectangles are also defined by a single point. Its side lengths, though, are defined with <code>rectX</code> and <code>rectY</code>. {| class="center" |- | <code><nowiki>{{Map|mtype=rectangle|rectX=11|rectY=15|3185,3440}}</nowiki></code> |- | {{Map|mtype=rectangle|rectX=11|rectY=15|3185,3440}} |} ===Lines and polygons=== Lines and polygons are defined with a series of coordinates. Unlike lines, polygons are automatically closed—i.e., the start and end points are attached. Lines are used to draw a walkable path or general route, while polygons are used to outline a map location (e.g., building) or mark a complex area. {| class="center" ! Line |- | <code><nowiki>{{Map|mtype=line|3243,3735|3226,3737|3222,3754|3238,3764|3252,3752}}</nowiki></code><br>{{Map|mtype=line|3243,3735|3226,3737|3222,3754|3238,3764|3252,3752}} |- ! Polygon |- | <code><nowiki>{{Map|mtype=polygon|3243,3735|3226,3737|3222,3754|3238,3764|3252,3752}}</nowiki></code><br>{{Map|mtype=polygon|3243,3735|3226,3737|3222,3754|3238,3764|3252,3752}} |} Each point of a line is '''centered''' on its respective tile. This is because lines should represent points that a player can stand on. Polygons, on the other hand, have points aligned to the '''south-west corner''' of their respective tile. This allows map locations to be outlined exactly. ===Combos=== Combo features are a combination of a [[#Single-point feature|single-point feature]] and a [[#Multi-point feature|multi-point feature]]. One example is <code>pin-line</code>, where <code>pin</code> is the single-point feature and <code>line</code> is the multi-point feature. Combos will generate a single-point feature per coordinate and a multi-point feature using all coordinates together. {| class="center" ! Pins and polygon !! Dots and line |- | <code><nowiki>{{Map|mtype=pin-polygon ... }}</nowiki></code> | <code><nowiki>{{Map|mtype=dot-line ... }}</nowiki></code> |- | {{Map|mtype=pin-polygon|2774,3469|2784,3459|2794,3469|2784,3479}} | {{Map|mtype=dot-line|2764,3468|2764,3461|2771,3458|2773,3452|2781,3444}} |} Combos should be used sparingly and only when multiple coordinates have some kind of relationship. A good example is the map of tasks throughout [[One Small Favour#Walkthrough|One Small Favour]], where the tasks must be completed in a specific order. Another example is the map of [[Canoe Station|canoe stations]], where each station represents a point along the River Lum. ===Maplinks=== Any map can be rendered as a maplink instead of a mapframe by using <code>|type=maplink</code>. With this, the <code>|text=</code> argument can be used to change the text of the link. {| class="center" |- | <code><nowiki>{{Map|type=maplink}}</nowiki></code><br> {{Map|type=maplink}} | <code><nowiki>{{Map|type=maplink|text=Maplink Text}}</nowiki></code><br> {{Map|type=maplink|text=Maplink Text}} |- | <code><nowiki>{{Map|type=maplink|text=}}</nowiki></code><br> {{Map|type=maplink|text=}} | <code><nowiki>{{Map|type=maplink|mtype=pin|2613,3294}}</nowiki></code><br> {{Map|type=maplink|mtype=pin|2613,3294|group=maplinks}} |} ===Plane, map ID, and zoom=== Plane, map ID, and zoom are three essential options used to control the map view in many cases. * Plane—set with <code>plane</code>—controls the Z value of a feature and corresponds to the floor something is on. For example, if a feature is on the {{Floor|uk=1}} of a building, set <code>plane</code> to <code>1</code>. * Map ID—set with <code>mapID</code>—controls which area of the game map to render. Setting this value is similar to changing the [[World_map#Map_selection|world map's map selection]]. * Zoom—set with <code>zoom</code>—overrides the automatically calculated zoom amount for a map. If the area you want to mark appears too large or small at the default zoom level, set it to a value that will better represent that area. ==Advanced usage== ===Anonymous features=== Multiple map features can be defined through [[#Anonymous feature|anonymous features]], which have the general form: <pre>|option1:value1,optionN:valueN,x1:y1,xN:yN</pre> You can provide as many options and coordinates as you want for a single anonymous feature. Each option/value and x/y must be separated by a colon (<code>:</code>), and each of these pairings must be separated by a comma (<code>,</code>). The options available to use in anonymous features are exactly the same as regular [[#Named argument|named arguments]], meaning the two are entirely interchangeable. If a named argument is also provided as an anonymous argument, the anonymous value will override the named value. One small difference with anonymous features—because they are comma- and colon-separated—is the need to escape ''extra'' commas and colons with <code>\</code> backslashes in certain options. These are mentioned in the table of [[#Feature options|feature options]] below. {| class="center" |- | <code><nowiki>{{Map|mtype:pin,3211:3247,desc:A comma \, and a colon \:|mtype:rectangle,rectX:6,rectY:5,3246,3246}}</nowiki></code> |- | {{Map|mtype:pin,3211:3247,desc:A comma \, and a colon \:|mtype:rectangle,rectX:6,rectY:5,3246,3246|group=anonfeats}} |} Because the anonymous feature syntax is used solely to create features, [[#Map options|map-only options]] cannot be used as feature options. ===Offsetting the view=== With at least one feature on a map, the view will be centered on the average X and Y coordinates of all points provided. To override this behaviour and offset the view, provide [[#Named argument|named]] <code>x</code> and <code>y</code> arguments. {| class="center" ! Offset !! No offset |- | <code><nowiki>{{Map|2990,9935|y=9955|x=2975 ... }}</nowiki></code> | <code><nowiki>{{Map|2990,9935 ... }}</nowiki></code> |- | {{Map|mapID=-1|mtype=rectangle|rectX=8|rectY=6|y=9955|x=2975|2990,9935}} | {{Map|mapID=-1|mtype=rectangle|rectX=8|rectY=6|2990,9935}} |} ===Popups=== By default, all features are clickable to show their X/Y coordinates. For [[#Multi-point feature|multi-point features]], this coordinate is the first coordinate provided. However, more details can be added. * Add a '''title''' with <code>title</code>. * Add a '''description''' with <code>desc</code>. * Add '''detailed info''' with <code>ptype</code> if the feature represents an item, object, monster, or NPC. For any <code>ptype</code>, the subject's name will default to the current page's title. Set <code>name</code> to change this. Specify the subject's internal ID with <code>id</code> if needed. For items, set <code>qty</code> and <code>respawn</code> if needed. ** For monsters and NPCs, set <code>levels</code> and <code>respawn</code> if needed. Keep in mind that the page a map is placed on may already provide these details, in which case it may not be necessary to repeat them in the popup. ===SMW=== The Map module provides functionality that allows other pages, templates, and modules to interact with its data. More specifically, by setting <code>smw=yes</code> on a map, the final map options and GeoJSON for each feature will be stored in SMW for other resources to consume. See [[Property:Location JSON]] for example data. In some cases, a page will have multiple maps that relate to specific instances of the page's subject. For example, [[Forestry Shop]] has three maps that each relate to one of its locations. To handle this, you can set <code>smwName</code> ''along with'' <code>smw</code> to tell the Map module to store each map's data in a "subobject" on the page; Otherwise, each of the maps would overwrite each other. The value of <code>smwName</code> should match the subject's instance name if possible ("Draynor Village", "Seers' Village", or "Prifddinas" in the Forestry Shop example). Note that you should only provide these arguments if you know exactly what you're doing. =Arguments= ==Map options== Map options are [[#Named argument|named arguments]] that define how the map itself behaves and how it is rendered on the page. These options cannot be used as feature options. {{ArgDocHeader}} {{ArgDocLine |name = type |description = Sets the map type on the page. |optional = Yes |values = <code>mapframe</code> <code>maplink</code> |default = <code>mapframe</code> }} {{ArgDocLine |name = width |description = Sets the map width on the page. |optional = Yes |values = Any number >=<code>1</code> |default = <code>300</code> }} {{ArgDocLine |name = height |description = Sets the map height on the page. |optional = Yes |values = Any number >=<code>1</code> |default = <code>300</code> }} {{ArgDocLine |name = align |description = Sets the map's alignment on the page. |optional = Yes |values = <code>left</code> <code>center</code> <code>right</code> |default = <code>center</code> }} {{ArgDocLine |name = x |description = Sets the X coordinate of the map view if at least one feature is defined. |optional = Yes |values = Any number >=<code>0</code> |default = <code>3233</code> }} {{ArgDocLine |name = y |description = Sets the Y coordinate of the map view if at least one feature is defined. |optional = Yes |values = Any number >=<code>0</code> |default = <code>3222</code> }} {{ArgDocLine |name = zoom |description = Sets the zoom amount. A higher number means a closer zoom. |optional = Yes |values = Any integer <code>-3</code>–<code>3</code> |default = <code>2</code> }} {{ArgDocLine |name = mapID |description = Sets the map ID. |optional = Yes |values = Any [[RuneScape:Map/mapIDs|map ID]] |default = <code>0</code> }} {{ArgDocLine |name = caption |description = Adds a caption to the map if <code>type</code> is unset or set to <code>mapframe</code>. |optional = Yes |values = Any text }} {{ArgDocLine |name = text |description = If <code>type</code> is set to <code>maplink</code>, changes the text of the link. |optional = Yes |values = Any text }} {{ArgDocLine |name = smw |description = Enables [[Property:Location JSON|Location JSON]] or [[Property:Historic Location JSON|Historic Location JSON]] data for the current page. This should only be used if the map directly describes the page subject. |optional = Yes |values = <code>yes</code> <code>hist</code> }} {{ArgDocLine |name = smwName |description = Changes the SMW data to a subobject on the current page with the provided value as the subobject name. This should only be used if the map does ''not'' directly describe the page subject. |optional = Yes |values = Any Text }} {{ArgDocLine |name = nopreprocess |description = Outputs the final map element with GeoJSON as raw text instead of a rendered map. |optional = Yes |values = <code>True</code> }} {{ArgDocFooter}} ==Feature options== Feature options are [[#Named argument|named]] or [[#Anonymous argument|anonymous]] arguments that define features on the map. {{ArgDocHeader}} {{ArgDocLine |name = mtype |description = Sets the type of a feature. |optional = Yes |values = <code>pin</code> <code>rectangle</code> <code>square</code> <code>circle</code> <code>dot</code> <code>text</code> <code>line</code> <code>polygon</code> or a [[#Combo type|combo type]] |default = <code>pin</code> }} {{ArgDocLine |name = x |description = Sets the X coordinate of a feature. Can also be set with [[#Coordinate shorthand|coordinate shorthand]]. |optional = Yes |values = Any number >=<code>0</code> |default = <code>3233</code> }} {{ArgDocLine |name = y |description = Sets the Y coordinate of a feature. Can also be set with [[#Coordinate shorthand|coordinate shorthand]]. |optional = Yes |values = Any number >=<code>0</code> |default = <code>3222</code> }} {{ArgDocLine |name = plane |description = Sets the plane (Z value) a feature is on. |optional = Yes |values = Any integer >=<code>0</code> |default = <code>0</code> }} {{ArgDocLine |name = r |description = Sets the radius of a circle or square. |optional = Yes |values = Any number >=<code>1</code> |default = <code>10</code> }} {{ArgDocLine |name = rectX |description = Sets the X length for a rectangle. |optional = Yes |values = Any number >=<code>1</code> |default = <code>20</code> }} {{ArgDocLine |name = rectY |description = Sets the Y length for a rectangle. |optional = Yes |values = Any number >=<code>1</code> |default = <code>20</code> }} {{ArgDocLine |name = icon |description = Sets the icon for a pin feature using a built-in value. |optional = Yes |values = <code>greenPin</code> <code>redPin</code> <code>bluePin</code> <code>cyanPin</code> <code>magentaPin</code> <code>yellowPin</code> <code>greyPin</code> |default = <code>greenPin</code> }} {{ArgDocLine |name = iconWikiLink |description = Sets the icon for a pin feature using an image from the wiki. File extension must be included. |optional = Yes |values = Any file name }} {{ArgDocLine |name = iconSize<br>''iconSizeX''<br>''iconSizeY'' |description = Sets the icon size for a pin feature. If one number is provided (e.g., <code>5</code>), that number is used as the X ''and'' Y sizes. If two numbers are provided (e.g., <code>2,3</code>), the X and Y sizes are set separately. Separate values can also be provided with <code>iconSizeX</code> and <code>iconSizeY</code>. |optional = Yes |values = Any number >=<code>1</code> }} {{ArgDocLine |name = iconAnchor<br>''iconAnchorX''<br>''iconAnchorY'' |description = Sets the icon position for a pin feature relative to the map point. [0,0] is at the top-left corner of the image. If one number is provided (e.g., <code>5</code>), that number is used as the X ''and'' Y. If two numbers are provided (e.g., <code>2,3</code>), the X and Y are set separately. Separate values can also be provided with <code>iconAnchorX</code> and <code>iconAnchorY</code>. |optional = Yes |values = Any number }} {{ArgDocLine |name = popupAnchor<br>''popupAnchorX''<br>''popupAnchorY'' |description = Sets the popup position for a pin feature relative to the icon. [0,0] is at the top-left corner of the image. If one number is provided (e.g., <code>5</code>), that number is used as the X ''and'' Y. If two numbers are provided (e.g., <code>2,3</code>), the X and Y are set separately. Separate values can also be provided with <code>popupAnchorX</code> and <code>popupAnchorY</code>. |optional = Yes |values = Any number }} {{ArgDocLine |name = group |description = Sets the group for a pin feature. |optional = Yes |values = Any text |default = <code>pins</code> }} {{ArgDocLine |name = label |description = Sets the label text of a text feature. '''Only required on text features.''' In an [[#Advanced usage|anonymous feature]], all commas and colons within must be escaped with <code>\</code> backslashes. |values = Any text }} {{ArgDocLine |name = position |description = Sets the position of a text feature's label. |optional = Yes |values = <code>left</code> <code>right</code> <code>top</code> <code>bottom</code> <code>center</code> |default = <code>top</code> }} {{ArgDocLine |name = title |description = Sets the popup title of a feature. In an [[#Advanced usage|anonymous feature]], all commas and colons within must be escaped with <code>\</code> backslashes. |optional = Yes |values = Any text }} {{ArgDocLine |name = desc |description = Sets the popup description of a feature. In an [[#Advanced usage|anonymous feature]], all commas and colons within must be escaped with <code>\</code> backslashes. |optional = Yes |values = Any text }} {{ArgDocLine |name = ptype |description = Sets the feature's subject's type for providing extra popup details. |optional = Yes |values = <code>item</code> <code>monster</code> <code>npc</code> <code>object</code> }} {{ArgDocLine |name = name |description = Sets the feature's subject's name if <code>ptype</code> is set. |optional = Yes |values = Any text |default = The page's title }} {{ArgDocLine |name = id |description = Adds the feature's subject's internal ID to the popup if <code>ptype</code> is set. |optional = Yes |values = Any integer }} {{ArgDocLine |name = qty |description = Adds the feature's subject's quantity to the popup if <code>ptype</code> is set to <code>item</code>. |optional = Yes |values = Any integer }} {{ArgDocLine |name = respawn |description = Adds the feature's subject's respawn time to the popup if <code>ptype</code> is set to <code>item</code>, <code>npc</code>, or <code>monster</code>. |optional = Yes |values = Any text }} {{ArgDocLine |name = levels |description = Adds the feature's subject's list of levels to the popup if <code>ptype</code> is set to <code>monster</code> or <code>npc</code>. |optional = Yes |values = Any text }} {{ArgDocLine |name = stroke |description = Sets the stroke color of a feature with a stroke. |optional = Yes |values = Any hexadecimal color code |default = <code>#3388ff</code> }} {{ArgDocLine |name = stroke-opacity |description = Sets the stroke opacity of a feature with a stroke. |optional = Yes |values = Any number <code>0</code>–<code>1</code> |default = <code>1</code> }} {{ArgDocLine |name = stroke-width |description = Sets the stroke width of a feature with a stroke. |optional = Yes |values = Any number >=<code>0</code> |default = <code>3</code> }} {{ArgDocLine |name = fill |description = Sets the fill color of a feature with a fill. |optional = Yes |values = Any hexadecimal color code |default = <code>#3388ff</code> }} {{ArgDocLine |name = fill-opacity |description = Sets the fill opacity of a feature with a fill. |optional = Yes |values = Any number <code>0</code>–<code>1</code> |default = <code>0.2</code> }} {{ArgDocLine |description = Any number of anonymous features. |optional = Yes |values = See [[#Anonymous features|Anonymous features]] }} {{ArgDocFooter}} =Definitions= * <div id="Named argument" /> '''Named argument''' - An argument with the form <code>|arg=value</code>. ** <div id="Named feature" /> '''Named feature''' - A feature defined entirely with named arguments. * <div id="Anonymous argument" /> '''Anonymous argument''' - An argument with the form <code>|value</code>. ** <div id="Anonymous feature" /> '''Anonymous feature''' - A feature defined entirely or partially with anonymous arguments. Uses the format <code>|option1:value1,optionN:valueN,x1:y1,xN:yN</code>. * <div id="Single-point feature" /> '''Single-point feature''' - A feature defined by a single point. Pins Rectangles Squares Circles Dots Text * <div id="Multi-point feature" /> '''Multi-point feature''' - A feature defined by multiple points. Lines Polygons * <div id="Combo type" /> '''Combo type''' - An <code>mtype</code> that combines a ''single-point'' <code>mtype</code> with a ''multi-point'' <code>mtype</code>. Examples: <code>pin-line</code>, <code>dot-line</code>, and <code>pin-polygon</code>. * <div id="Coordinate shorthand" /> '''Coordinate shorthand''' - A more compact way to provide X/Y coordinates for a feature. Allows multiple coordinates to be provided. For ''named features'', this could look like <code>|1000,1000|2000,2000</code>. For ''anonymous features'', this could look like <code>|1000:1000,2000:2000</code>. =See also= * [[Module:Map/doc|Map module API]]