Skip to content

Routes

A route is a line drawn on a map through a set of waypoints in a connect-the-dots fashion. You can set the line’s width, color, opacity, and effects. You can also create gaps in the routes to show that the route travels through something opaque like a tunnel.

To use the Route feature, you must have a Plus Plan or Pro Plan.

Specifying a Route

A route consists of a set of waypoints that can be connected to draw a path from a start point to an endpoint through a set of intermediate waypoints. The route itself is a special hotspot that is used as a container in which the route’s path is drawn. You draw a route using the API. Each of these elements of a route will be discussed in the following sections.

Route waypoints

A waypoint is a marker on the map that a route will be drawn through. Any hotspot marker can serve as a waypoint except for a special hotspot that is used to draw the route itself.

You indicate the location of a waypoint by placing a hotspot's marker on your map. MapsAlive uses the center of each waypoint marker as the dot through which a route is drawn. If you want the waypoints that a route is drawn through to show, use visible markers. If you don’t want the waypoints to show, use markers that are hidden.

Route hotspot

To enable the drawing of a route through a set of waypoints, you add a route hotspot to your map. A route hotspot serves as a container within which the route will be drawn. When you draw a route, you specify the Id of the route hotspot and that hotspot takes on the appearance of the route. You can erase a route by drawing another route using the same route hotspot, or you can use multiple route hotspots so that you can show more than one route at a time.

How to create a route hotspot
  • Select the hotspot to be used for the route from the Tour Navigator
  • Choose Hotspot > Advanced Hotspot Options from the Tour Builder menu
  • On the Advanced Hotspot Options screen:
    • Check the Is Route option

To draw a route, at least one hotspot on your map must have its Is Route attribute set.

A route hotspot has all of the attributes of a regular hotspot except that it has no marker and you can’t use it as a waypoint in a route. It can, however, have content (like a photo or text) and respond to mouse actions. For example, you can set things up so that when you mouse over a route, a photo appears. Or you can specify that when you click on a route, a JavaScript function gets called. You can also make a route hotspot static so that nothing happens when you mouse over it or click it.

Drawing a route

To show a route on your map you tell MapsAlive to draw it using the drawRoute method of the API. You can call this method any time you like, for example, when your map first loads, when a marker is moused over or clicked, or in response to a user action on your web page.

The drawRoute method is intended for use by JavaScript programmers, but non-programmers can use the examples in this document to successfully draw routes. Here is an example of what the method looks like when called to draw a route through three hotspots that have Ids of H1, H2, and H3. In the example, the hotspot Id for the route hotspot is R1.

api.drawRoute("R1", "H1,H2,H3");

The drawRoute method can take additional optional parameters that allow you to specify the appearance of the route. You can set the line width, color, opacity, and effects such as shadow or glow.

You can call the drawRoute method from your own JavaScript or when a marker action occurs. The marker mouse events are mouseover, mouseout, and click. You specify JavaScript for a hotspot marker’s mouse events on the Marker Actions screen.


The example below draws short routes having only a few waypoints, and one route (from marker "9") with six waypoints.

Mouse-over or touch a number to see a route drawn from the number to a part of the lightbulb

The route drawing code for the example above is shown below.

const routes = {
   GlassBulb: "W1",
   InertGas: "W2",
   Filament: "W3",
   ContactWires: "W4;W5",
   SupportWires: "W6;W7",
   Stem: "W8",
   Cap: "W9",
   Insulation: "W10",
   ElectricalContact: "W11a,W11b,W11c,W11d,W11e"
};

function onEventHotspotChanged(event) {
   let route = createRoute(event.hotspot.id);
   const show = route.length > 0;
   if (show)
      event.api.drawRoute("R1", route, 3, 0xff0000, 100, "linedash,25,10");
   event.api.setMarkerHidden("R1", !show);
}

function createRoute(hotspotId) {
   let route = "";
   if (hotspotId.length > 0 && routes[hotspotId]) {
      let waypoints = routes[hotspotId].split(';');
      for (const waypoint of waypoints)
         route += `${route.length ? ';' : ''}${hotspotId},${waypoint}`;
   }
   return route;
}

Importing Routes

If your map has dozens or hundreds of waypoints, like in the example below, you’ll want to consider importing your routes. The Import Routes feature allows you to define and manage large numbers of complex routes in an Excel spreadsheet or CSV file.


Mouse-over or touch a location on the left to see the route from the You Are Here marker to that location

Routes spreadsheet

You define routes in a spreadsheet and then import the spreadsheet into MapsAlive. The routes spreadsheet contains one row for each route you want to draw. To draw an imported route you refer to it by its route Id like this:

api.drawRoute("R1", "LobbyToWaitingRoom");

The spreadsheet specifies which markers belong to which routes. You identify markers using their hotspot Id which appears on the Advanced Hotspot Options screen. Each row in the spreadsheet contains a route Id and a set of hotspot Ids that make up the route. A row in the spreadsheet can define a complete start-to-end route defined by individual hotspot Ids, or it can combine hotspot Ids with the Ids for route segments as defined in the next section.

The columns in the spreadsheet are shown in the table below.

Id
A unique Id for the route. Choose a name that will make it easy to understand what the route is or what its start and endpoints are.
Route
A list of two or more hotspot Ids and/or route Ids that describe the route.
Normally you use commas to separate the Ids, but you can use a semicolon where there are breaks in the route as explained below in the section on non-contiguous routes.
If the waypoints within a segment of the route need to be drawn in reverse order, enclose the segment Id in parenthesis as explained below in the section on reversing segment direction. For example: Wait,P8,(Hall1),Lobb.
Import
Specify True (or TRUE) if the row is for a route that will be drawn on your map. Specify False or leave this column blank to indicate that the row defines a segment used as part of another row’s route. Note that a row can be used for both a route that will be drawn and as a segment used by another route. In that case, specify True.

MapsAlive will ignore any other columns in the spreadsheet so feel free to use those for notes. MapsAlive also ignores formatting such as colors and bold text. When you have a lot of routes, it can help to use colors or other formatting to make your spreadsheet easier to read.

If you import routes and then later delete a hotspot from your map that was used in a route, the route will still be drawn but will skip the missing hotspot.

Anytime you want to modify your routes, simply edit the spreadsheet and import it into MapsAlive again. Whenever you import a routes file, its contents replace any and all existing routes that were previously imported. This differs from importing hotspot content where you can add new hotspots or update a subset of your existing hotspots from imported data.

How to import routes from a CSV file or Excel spreadsheet
  • Choose Tour > Import Routes from the Tour Builder menu
  • On the Import Routes screen:
    • Browse for the spreadsheet file containing the routes
    • Click the Import button

During the import process, MapsAlive resolves each Id it encounters by comparing it to the Hotspot Ids present in the tour. If a route references a Hotspot Id that does not exist, MapsAlive will report an error and reject any routes that use that Hotspot Id.

Segments

Routes that travel over part of the same path as other routes can make use of segments to avoid duplication of data and make maintenance easier. You can define a segment and then include its Id as part of another route. In a large building, there are often primary and secondary corridors that almost everyone walks through to get from point A to point B. These corridors can be defined as segments so that each unique route does not have to define waypoints for corridors over and over again.

Non-contiguous routes

You can draw a route that has non-contiguous segments by separating the points or segments with semi-colons. The semi-colon tells MapsAlive to pick up the “pen” and move it to the next coordinate before continuing to draw. For example, if you want to draw a route that stops at the edge of a river and then starts again on the other side you can define the points for each part of the route and separate the two groups by a semi-colon like this:

Id Route Import
EastSection H1,H2,H3
WestSection H4,H5,H6
EntireRoute EastSection;WestSection TRUE

When MapsAlive draws the route defined by EntireRoute, it will first draw the East section, then pick up the “pen”, move to H4, put down the “pen” and continue drawing the West section. You use a semi-colon instead of a comma anywhere you want to break the route into non-contiguous lines.

Reversing segment direction

If the waypoints within a segment of a route need to be drawn in reverse order, enclose the segment Id in parenthesis. You do this when a segment is used for multiple routes that traverse the segment from either direction. This is useful when multiple routes traverse the same segment but from different directions.

In the imported route example below, the WaitToLobb route on line 15 of the import spreadsheet encloses the Hall1 segment in parentheses to indicate that the segment should be drawn in reverse order, i.e. P3, P2, P1.

Testing imported routes

When a tour has imported routes, the Map Editor displays a dropdown list showing the Id of each imported route. When you select a route from the list the route appears on the map.

Show the documentation for the Show Routes List option once it works in V4

You can also test your routes while in Tour Preview using the Show Routes List option. You do this by choosing Map > Advanced Map Options from the Tour Builder menu and then checking the box labeled Show Routes List (it’s at the very bottom of the screen). Checking the box will cause a dropdown list to appear in the upper left corner of your map. When you select a route Id from the list, the route will be drawn using a dark blue line. The dropdown list will not appear when you run your tour outside of Tour Preview.

Imported Routes Example

The example tour below lets you choose a route starting from either the lobby or the waiting room to the other six rooms on a hospital floor. If a room has two public entrances, the route takes you to the closest entrance from the start of the route. Where the route travels through closed doors (such as into the Emergency Room), a gap appears on either side of the doors.


Move your mouse over or touch the gray boxes below to show a route.

The import spreadsheet

The routes for the hospital example are defined in the spreadsheet shown below.

Rows 2 and 3 define two segments, called Hall1 and Hall2. Hall1 runs North/South between the cafeteria and pathology. Hall2 runs East/West above pathology and emergency. In this simple example, these segments have only a few waypoints, but in a real hospital, a main hall or corridor could have many waypoints. Using a segment not only keeps you from having to specify the same waypoints over and over again in each route that uses the segment, but it also means that you can edit a segment and automatically alter all routes that use it. For example, suppose a detour was required in a corridor as a result of a long-term construction project. You could add the detour to the segment (and remove it when the construction was finished) without having to change any of the routes that use that segment.

Rows 4 through 15 in the spreadsheet define six routes that start in the lobby and six routes that start in the waiting room. The Hall1 segment is shared by the LobbToEmrg, LobbToAdmn, and LobbToWait routes. The Hall2 segment is shared by WaitToPath and WaitToCafe. Note that some of the waypoints are separated by semicolons instead of commas. The semicolons are used to create gaps where a route goes through closed doors.

The Import column of all rows specifies TRUE except for rows 2 and 3 which define segments. This tour never draws routes just for Hall1 or Hall2 and therefore does not import them into the tour.

Working with maps in the Map Editor

The screenshot below shows the Map Editor screen in the Tour Builder. This is what you would see when you are placing waypoint and other markers on your map. In this tour, all of the markers are set to Hidden (the waypoint markers and the You Are Here markers), but on the Map Editor screen they appear semi-transparent so that you know where they are and can move them around while working with your tour.

The dropdown list on the Map Editor screen lets you choose an imported route so that you can see it while working on your map. In this example, the route shown is LobbToEmrg.

To help you better understand the spreadsheet, the screenshot above is annotated to label the waypoints that make up the LobbToEmrg route (these labels do not appear in the Tour Builder).

The LobbToEmrg route is defined in the spreadsheet on line 4 as:

Lobb,Hall1,P6,P12;P19,EmrgW

Follow the green line to see how this route is drawn. It starts at the Lobb marker, then travels to P1 which is the start of the Hall1 segment. It leaves the Hall1 segment at P3 and travels to P6 where it makes a right turn to P12. The semicolon following P12 tells MapsAlive to lift the pen and then move to P19 to create a gap in the route at the doorway. The route then continues from P19 to EmrgW.

HTML and JavaScript

The hospital example tour uses the MapsAlive Custom HTML feature to display the boxes at the top of the tour that let you select a route. You could accomplish the same thing by coding the HTML in a containing web page.

HTML from the Top section of the Custom HTML screen

<table class="chart">
    <tr>
        <td style="text-align:right;">Draw route from <b>Lobby</b> to:</td>
        <td class="box" onmouseover="showRoute('LobbToEmrg');">Emergency</td>
        <td class="box" onmouseover="showRoute('LobbToPath');">Pathology</td>
        <td class="box" onmouseover="showRoute('LobbToAdmn');">Administration</td>
        <td class="box" onmouseover="showRoute('LobbToRadi');">Radiology</td>
        <td class="box" onmouseover="showRoute('LobbToCafe');">Cafeteria</td>
        <td class="box" onmouseover="showRoute('LobbToWait');">Waiting</td>
    </tr>
    <tr>
        <td style="text-align:right;">Draw route from <b>Waiting</b> to:</td>
        <td class="box" onmouseover="showRoute('WaitToEmrg');">Emergency</td>
        <td class="box" onmouseover="showRoute('WaitToPath');">Pathology</td>
        <td class="box" onmouseover="showRoute('WaitToAdmn');">Administration</td>
        <td class="box" onmouseover="showRoute('WaitToRadi');">Radiology</td>
        <td class="box" onmouseover="showRoute('WaitToCafe');">Cafeteria</td>
        <td class="box" onmouseover="showRoute('WaitToLobb');">Lobby</td>
    </tr>
</table>
Each cell in the table at the top of the tour has an onmouseover handler that calls a JavaScript function named showRoute. Each handler passes the Id of the route to be displayed when you mouse over or touch that cell. For example, the onmouseover handler for the Emergency cell in the first row looks like this:

onmouseover="showRoute('LobbToEmrg');"

Showing a route

In this example, the showRoute function uses the first four letters of the route Id to determine whether the route originates from the lobby or the waiting room so that it can show the appropriate You Are Here marker. The showRoute function also calls the MapsAlive API function drawRoute passing the route Id along with parameters that specify the appearance of the route’s line. The call looks like this:

mapsalive.drawRoute("Route", routeId, 3, 0x007700, 100, "shadow");

Note that in the call above, the first parameter “Route” is the Id of the route hotspot as explained above. The second parameter is an Id from the spreadsheet e.g. LobbToEmrg.”

JavaScript from the JavaScript section of the Custom HTML screen

function showRoute(routeId)
{
    let api = MapsAlive.getApi();   

    // Determine which "You Are Here" marker to show and which to hide.
    let show = routeId.substr(0, 4) == "Wait";
    api.setMarkerHidden("YouAreHereLobby", show);
    api.setMarkerHidden("YouAreHereWaiting", !show);

    // Draw a route that is a 3px green line at 100% opacity with a shadow.
    api.drawRoute("Route", routeId, 3, 0x007700, 100, "shadow");
}