Subway Map
Some of the maps on both Trainwatch and Setra.in are generated with the brilliant subwayMap[1] JQuery plugin.
Contents |
Use in normal web pages
Referencing the Plugin
First you need to include the following two scripts in your pages header:
<script src="http://trainwatch.co.uk/js/jquery-1.4.2.min.js" type="text/javascript"></script> <script src="http://trainwatch.co.uk/js/jquery.subwayMap-0.5.0.js" type="text/javascript"></script>
Using the Plugin
The subwayMap plugin is called using a jQuery selector as follows:
<script type="text/javascript">$(".subway-map").subwayMap({ debug: true });</script>
Here it invokes the plugin against the html element .subway-map
The only supported option (at present) is “debug” which has a default value of “false”. Setting it to true will display some debug statements in the JS console.
HTML Markup for Plugin
Like most navigation plugins, subwayMap uses an unordered list. The basic markup consists of the following:
- An outer DIV element to control general placement, background etc.
- One UL element for each “line” desired in the map.
- For each UL element, one or more LI elements with either plain text or an A element with plain text. An LI element provides coordinates for drawing lines and/or markers on the map.
Each of the DIV, UL and LI elements make use of custom attributes to convey how the map should be rendered. These are explained in the Step-by-Step section below.
Map Rendering
The subwayMap plugin renders the map on a grid with the origin at top left (i.e. X coordinates extend from left to right and Y coordinates extend from top to bottom). The size of this grid depends on a value you define called “cellSize.” For example, if you define a cellSize of 50 and specify a grid of 20 columns by 10 rows, then you will have a map that is 1000 pixels wide and 500 pixels high. For each UL element, a <canvas> element that is the size of the grid is created and positioned at (0,0). Subsequent <canvas> elements are stacked on top of the prior <canvas> elements. Station and interchange markers for each line are also created in separate, stacked <canvas> elements, however their z-Index is always higher than that of the <canvas> elements containing the lines. Finally, all labels are added as elements with the highest z-Index of all the elements in the map.
Markup of a SubwayMap
Now the 'hard' part. We now need to generate some markup to represent the map. Here we'll generate a 10x10 grid with three stations on it.
<div class="subway-map"
data-columns="10" data-rows="10" data-cellSize="40"
data-legendId="legend" data-textClass="text"
data-gridNumbers="true" data-grid="true"
data-lineWidth="8">
<ul data-color="#ff4db2" data-label="Maidstone East Line">
<li data-coords="0,2"></li>
<li data-coords="2,2"><a href="http://setra.in/wiki/Barming_Rail_Station">Barming</a></li>
<li data-coords="4,2"><a href="http://setra.in/wiki/Maidstone_East_Rail_Station/">Maidstone East</a></li>
<li data-coords="6,2"><a href="http://setra.in/wiki/Bearsted_Rail_Station">Bearsted</a></li>
<li data-coords="8,2"></li>
</ul>
<ul data-color="#4dffb2" data-label="Medway Valley Line">
<li data-coords="1,0"></li>
<li data-coords="2,1" data-dir="S"><a href="http://setra.in/wiki/Barming_Rail_Station">Aylesford</a></li>
<li data-coords="3,1.5" data-dir="E"></li>
<li data-coords="3,3"><a href="http://setra.in/wiki/Maidstone_Barracks_Rail_Station/">Maidstone Barracks</a></li>
<li data-coords="3,5"><a href="http://setra.in/wiki/Maidstone_West_Rail_Station">Maidstone West</a></li>
<li data-coords="3,7"></li>
</ul>
</div>
<div id="legend"></div>
<script type="text/javascript">$(".subway-map").subwayMap({ debug: true });</script>
Markup attributes
Heres are the attributes being used in the code above:
| element | attribute | description | value in example |
|---|---|---|---|
| DIV | data-columns | The number of columns the map will display | 12 |
| DIV | data-rows | The number of rows the map will display | 10 |
| DIV | data-cellSize | The width and height of each cell in pixels | 40 resulting in a 480x400 pixel grid |
| DIV | data-legendId | The ID of an HTML element into which the map legend will be appended | legend |
| DIV | data-textClass | The CSS class to use for text labels in the map | text |
| DIV | data-grid | True or false, to show or hide a grid that is useful during map construction. The default is false | true |
| DIV | data-gridNumbers | True or false, to show or hide numbers on the grid. Only applies if data-grid=”true” | true |
| DIV | data-lineWidth | The width in pixels for each line. The default is 10 pixels. | 8 |
| UL | data-color | The color of the line in standard CSS RGB notation | #ff4db2 |
| UL | data-label | The label for the line that will be displayed in the legend | Maidstone East Line |
| UL | data-reverseMarkers | true to render while on black, false black on white. default is false. | |
| UL | data-shiftCoords | Optional, if provided move the line by x,y amounts, i.e. "-1,0" means move line to left by 1 width | |
| LI | data-coords | The X,Y coordinate pair where the line should be drawn to from its last location (or the starting location if it’s the first LI element) | |
| LI | data-dir | Direction of the curve. If not present then no curve is used. Can be one of E, W, N or S | |
| LI | data-labelPos | Specifies where the label should be displayed using a directional abbreviation. Supported values are N, E, S, W, NE, NW, SE, SW. (Default is “S”). Sometimes your label may be too long and text-wrap may be needed. To do this, you can use “\n” within the text of the label | |
| LI | data-marker | Can be either “station” or “interchange.”
Will produce a different marker for each. Value may be prefixed by “@” to indicate that the LI element is solely for indicating the position of the marker and should not be used as a coordinate defining the path of the line. (Examples: data-marker=”station” or data-marker=”@interchange”) IMPORTANT: Markers are displayed only if the LI element contains content. Interchange markers ignore any coordinate shift values specified for the line. || | |
| LI | data-markerInfo | For “interchange” or “@interchange” markers, this attribute is used to define scenarios in which the interchange marker has to “stretch” across multiple lines or connect lines that are not next to each other. The attribute value consists of a letter “v” for vertical or “h” for horizontal, followed by a number representing the number of line widths to stretch (example: v3 or h4). The marker is rendered at the coordinate position specified and extends either vertically upwards or horizontally to the right.
While it is easy and convenient to use the LI elements that define line coordinates to also define markers, sometimes this does not yield the best result. The marker may appear off by a few pixels. In these cases, it is best to add an LI element for the marker, use the “@” prefix and provide precise coordinates with decimal places (Example: 1.5,2.25). |
References
- ↑ Subway Map Visualization JQuery Plugin Sept 17, 2011
