Routes WordPress Plugin

Author: Jennifer Hodgdon
Date Written: 24 March, 2010
Type: Download
Subject: WordPress

Introduction

The Routes WordPress plugin allows you to add geographical route information to articles and pages in a WordPress blog, map the routes using Google Maps, and create elevation charts. To see it in action, check out Jennifer and Zach's Adventures.

On this page, you can download the plugin, and learn about how to install and use it. A quick list of its features:

  • Each post or page can have either a route or a single geographical point associated with it. Points in routes can included elevations and tag markers.
  • Enter the routes or points via addresses, typing in latitude/longitude, clicking on a map, importing a GPX file, or a combination, on the post/page editing screen.
  • Separate from the route, each post/page can have one or more points of interest (POI) [new in version 2.3.0].
  • Blog viewers see a Google Map of the route/point and POI on the post/page screen, with tagged points marked, as well as overview maps on category/index pages.
  • Set up custom markers for different types of points, have custom line styles for the routes [new in version 2.3.0], and use different starting map types for different posts [new in version 2.3.1].
  • Optionally, create and display elevation charts of your routes, and allow users to download GPX files containing the route points [download is new in version 2.3.1].
  • Search by exact city, state, country, or for the closest routes to a geographical point.

Installation and Setup

Requirements for using Routes

  • WordPress version 2.2 or higher
  • A Google Maps-compatible browser (most are) with JavaScript enabled for yourself and your viewers to see the maps. (Note that some Internet Explorer users may need to change their security settings in order to see maps and map features, and they may need to upgrade to version 7.0 or higher.)
  • The PHP GD library installed on your web host, if you want to generate elevation profile images (most commercial hosts do have the GD library -- it is pretty standard).
  • The PHP XML Parser library installed on your web host, if you want to import GPX files (again, this is pretty standard).

Note that the Settings page (see below) will tell you if you have things set up correctly for elevation profiles and GPX imports or not.

How to install and set up Routes

  1. Download the plugin file (Routes.tgz, at bottom of this page).
  2. Extract and upload the files: routes.php (the main plugin file) goes into wp-content/plugins, in your WordPress installation. (In WordPress 2.6 and later, it's possible to choose a different location for wp-content; if so, put this file in your customized location for plugins.)
  3. Optionally, localize Routes: If you are using a localized version of WordPress and also want the Routes admin/editing panels (and one or two error messages blog viewers could see when using proximity search) to display in a language other than English, you will need to localize Routes. Routes uses the standard WordPress translation mechanism; the MO file(s) you create need to go into the WordPress plugins directory (wp-content/plugins) and be named "routes-LOCALE.mo", where LOCALE is the name of the locale you are using for WordPress (such as "es_ES" for Spanish). The POT file for translating into other languages is provided in the Routes zip file.
  4. Activate the plugin from your WordPress administration panel (log in, click on "Plugins" in the top menu bar, and activate the "Routes" plugin by clicking on the link that says "Activate" to the right of the plugin name). If you need more detailed information on how to manage WordPress plugins, please visit the Managing Plugins page on the WordPress site.
  5. Check status and set options: Click on "Options" or "Settings" (depending on which version of WordPress you are using) and then "Routes" to get to the Routes settings panel. (The Routes plugin may not be properly installed during plugin activation, but visiting this page will try to install the database tables again, and should fix most installation problems). Verify that the Status section says Routes is installed correctly. Then you can optionally change settings (some of the explanations may be confusing until you read the rest of this web page):
    • Language Code: You can enter a 2-letter language code, and if it is supported by Google Maps, the tool tips, map types, and other text on the map will show up in that language. Leave this blank to use English. You can also let Routes use the setting of your WordPress locale, by checking the appropriate box.
    • Map Choices: Google Maps has several different types of maps it can show, depending on what part of the world you are mapping. Check the boxes for which choices you want to offer your blog viewers, and choose a Default map type. As of version 2.3.1 of Routes, you can also choose a starting map type for each post, to override the default. The choice must be one of the map types you have enabled.
    • Map Features: Google Maps has several optional features that can be shown on your Google Maps, including a scale of miles/km. A map control that lets you zoom and pan the map is always shown as well, and Google Maps automatically chooses a control size appropriate to the size of the map you are displaying.
    • Full size control: As of Routes version 2.3.1, you can include a "Full Size" button. If a site visitor clicks the button, the map will zoom to fill up their browser window, and they'll have a "Normal size" button to zoom back. You can define the text to show in the button, or you can define an Icon (see below) and use the icon/shadow image as the button images.
    • Driving Directions: If you check the box, when a visitor double-clicks on a map, they will be given a choice of getting driving directions to this point or from this point. This will open up Google Maps in another window.
    • Icons and line styles [New in version 2.3.0]: Choose what type of icons and lines you want to use by default (you can override these settings on each post/page as well). There are separate icons for "index" maps (such as your blog's home page or tag archive page), the start point of each route when a post is displayed on its own page (this point gets an icon so that viewers can tell which direction the elevation profile goes), and tagged points within a route. You can also create custom icons on the Icons settings page. See sections below on icons and line types for more information.
    • Create elevation profile on save: Check this box if you want Routes to create elevation profile image files whenever you save a post with elevation information, and automatically look up elevations when you enter a route point by clicking on the map. Note that this setting does not affect any posts you have already created -- you will need to edit existing posts (making sure elevation is included) and save them to create or re-create elevation charts.
    • Use metric units for elevation: Check this box if you want Routes to use metric units (meters) for elevations when you look them up with the Lookup button and on elevation profiles. If it is not checked, Routes will use English units (feet). Exported GPX fiels will always use meters, however, since that is the GPX standard.
    • Height/Width of elevation profile: Enter the height and width of the elevation profile images to create. Recommended minimum values are 100 by 100 pixels. Note that this setting does not affect any elevation profile images you have already created -- you will need to edit existing posts and save them to create or re-create elevation charts.
    • Options for elevation profile: Enter red, green, and blue values (0 to 255) for the background color of the elevation profile images (defaults to white, 255/255/255), the line/text color for the axes (defaults to black, 0/0/0), the color used to fill the elevation profile chart (defaults to a blue color), and the color used for markers on the elevation chart (defaults to a red color, if you have the box checked that says to add markers). There are links at the top of the Routes Settings screen to a couple of web sites where you can look up RGB values for colors. Note that this setting does not affect any elevation profile images you have already created -- you will need to edit existing posts and save them to create or re-create elevation charts.
    After entering all the settings, click the "Update" button to save them.
  6. If you are planning to generate elevation profiles, make sure your WordPress uploads directory (usually wp-content/uploads under your WordPress site directory, although you can change this in WordPress 2.6 and later) exists and is writable. (The elevation profile images will be saved in a sub-directory "routes" underneath that directory, which Routes will create.)
  7. Add Routes to your theme (see section below).

That's it! You're now ready to add geographical information to your posts or pages (see section below), and have it displayed in your WordPress site.


Setting up Custom Icons

As of Routes 2.3.0, you can create custom icons for your web site. To create a custom icon, visit the Routes Icons settings page. For each icon, you will need to:

  • Enter an Administrative Name (which will show up in drop-down lists when you are doing something that needs an icon.
  • Optionally, enter a Legend Name. If you enter a Legend Name, then the icon will show up in your theme when you use the legend function (see section below on theming). If you leave it blank, that icon will not appear in legends.
  • Upload an image file and optionally a shadow image file. You can also enter the URL of these files instead of uploading them. If you are uploading, I recommend using PNG files (GIF files do not seem to work in some browsers in Google Maps).
  • Enter the size (height/width) of your image files and the "anchor point" (in pixels) relative to the upper left corner of the icon. The anchor is the point where the icon will be centered over the latitude/longitude on the map.
  • Click "Update icons" after editing an icon's information or adding information for a new icon.

Once you create a custom icon, there are several uses for them:

  • On an aggregate/index map (such as on your blog's home page or a tag, category, or date archive page), each post is shown with a line from the start to the finish of the route, and an icon in the center. You can choose the default icon to use for this on the Routes settings page (see above), and you can override the default on each post when you are editing the post.
  • On a single-post map, the first point of the route is marked with an icon. You can choose the default icon to use for this on the Routes settings page (see above), and you can override the default on each post when you are editing the post. If you don't want the first point of each route to be marked with an icon, you can create a transparent or blank icon on the custom icons page, and use that.
  • On a single-post map, each point of the route that you tag with extra information is marked with an icon (a visitor to your site can click the icon to see the extra information in a pop-up window). You can choose the default icon to use for this on the Routes settings page (see above), and you can override the default on each post when you are editing the post.
  • Besides route points, each post can have separate "Points of Interest" (POI) that are separate from the route. You can choose the icon for each POI when you create it on the post editing screen.

Setting up Custom Line Types

By default, Routes uses a semi-transparent blue line to mark routes on aggregate/index maps (such as on your blog's home page or a tag, category, or date archive page) and single-post maps. You can change the default line style for marking routes on the Routes settings page, and when you are editing a post, you can override the default values. The line style consists of three settings: color (given by web-color settings, such as #FF0000 for red), opacity (ranging from 0 for completely invisible to .5 for semi-transparent to 1 for not completely opaque), and width (the line width in pixels). A completely invisible line gives you the opportunity to tag points and make an elevation profile, without showing a route line on your map.


Frequently Asked Questions (and answers)

  1. I am having trouble with Routes in Internet Explorer. What could cause that?
    First off, make sure you are using Routes 1.02 or greater, WordPress 2.2 or higher, have upgraded IE to 7.0 or higher, and have followed the installation instructions above. If that doesn't fix the problem, check your browser's security settings, and make sure JavaScript can be executed (for some reason, Microsoft has lumped this in with "Active Content" in some versions, and with "Scripting" in other versions). Finally, it could be that your HTML pages are not valid... for some reason, Internet Explorer is very sensitive to invalid HTML and JavaScript (Google Maps uses JavaScript to display the maps, and Routes uses Google Maps). So if you are seeing maps fine using a browser such as Firefox or Opera, and getting page errors or missing maps in Internet Explorer, check the validity of your WordPress output page using the W3C HTML Validator. If your page is invalid, fix your theme, posts, and pages until they produce valid HTML, and the problem with Routes should go away.
  2. I have set the option to create elevation profiles, but they are not being created when I save my post. What could cause that?
    There are several possibilities that you can look into:
    • You have to have at least two points in your route with elevations entered in order to create an elevation profile.
    • Routes uses WordPress's file upload mechanism to save its elevation profile images, so if you are logged in as a user that does not have file upload permission, then Routes cannot create any elevation profile images. You can fix this by logging back in as the "admin" user, or any other user that has file upload permissions, going to the post edit screen, and saving the post again.
    • Routes tries to save the files it creates in directory wp-content/uploads/routes (in WordPress 2.6 or later you can override the default uploads location, and if you do, Routes will put its files there instead of under wp-content/uploads). Routes will try to create the "routes" sub-directory if it does not already exist, but if your uploads directory does not exist, or if the web server does not have write permission on it, Routes will not be able to create its directory or save files there. You can fix this by creating the "uploads" directory and making sure the web server has write permission in it.
    • Routes creates its elevation profile images using the PHP GD library, as well as a PHP XML library, so if your web host does not have the GD and XML libraries installed (most do!), Routes cannot create the images.
    You can test most of this by trying to upload an image in the "Uploads" or "Add Media" section of your post editing screen. If that works, then the uploads directory is set up correctly and you have permission to upload. Then type in at least two elevation values (along with latitudes, longitudes, and point order values) for a post and click "Save and Continue Editing" or "Save". If the elevation chart is created, you will see it in the "Uploads/Browse" section of the edit screen; if you are using WordPress 2.5 or later, it's in the Gallery tab of the media button screens. If it isn't created, but you can upload other images, go to the Options / Routes or Settings / Routes screen (depending on what version of WordPress you are using). There is a section near the top that says whether or not your web host has the software installed that will allow you to create elevation plots, and to allow you to import GPX files. There should be a message there explaining why it won't work. Contact your web host and see if they can fix it.
  3. Sometimes when I click on the map to add a point in the post editing screen, I get a route line to the new point, but no marker. Why?
    If you have more than about 50 points in your route (maybe because you imported them from a GPX file), Routes will not show markers at every point. This is to avoid having the browser take a very long time to load. You can still delete the new point by clicking the Delete checkbox in the list above.
  4. Maps don't seem to be working at all, or if they are, no markers or lines are shown on them. Why could that be?
    Probably you need to go back and read the section below on theme modification. You need to carefully follow all the instructions for "ALL maps", and also either the instructions for "Single Route Maps" or "Aggregate Route Maps", or both. There are several modifications that have to be made, and if they are not all done, Routes will not display maps correctly.

    For testing purposes, you can also try the Sandbox theme (see the theme modifications section below). If Sandbox is displaying maps and your theme is not, then you have not followed all of the instructions.

    Also, display of Google Maps (which Routes relies on) in a web page is VERY sensitive to the HTML in the page being valid. So you might want to check that your HTML is valid, and fix any validation errors you find. You can check the validity of HTML at validator.w3.org.
  5. I have uploaded a GPX file, but when I check the Import box and click "Save" or "Save and Continue Editing", the file stays in the Uploads section and is not imported. What could cause that?
    Go to the Options / Routes or Settings / Routes screen (depending on what version of WordPress you are using). There is a section near the top that says whether or not your web host has the software installed that will allow you to create elevation plots, and to allow you to import GPX files. There should be a message there explaining why it won't work. Contact your web host and see if they can fix it.
  6. After installing and activating the plugin, when I try to use it I am getting an error that says "Table 'wp_routes_waypoint' does not exist." (or something similar). Why?
    wp_routes_waypoint (possibly with a different prefix other than "wp") is the database table that Routes uses to store its point information. It is normally created when you first activate the plugin. However, if your WordPress installation does not have MySQL database permissions that allow it to create new tables, the table will not get created when you activate the plugin. If that is the case, you will need to update your MySQL database permissions. Contact your web host provider.
  7. I am using Routes in an area where Google Maps doesn't have mapping data, just satellite images. Is it possible to make Routes start in Satellite mode?
    As of Routes Version 2.2, there are options to define which type of maps to offer on your site, and which one to use by default. See the options section, above.
  8. What versions of WordPress is this plugin compatible with?
    Routes works with version 2.2 and above of WordPress. The latest version of WordPress that has been tested with this plugin is 4.6.
  9. How can I find out if there is a new version of the plugin?
    Check back on this page regularly to see if there is a new version. Note: The mechanism in WordPress 2.3 and above for automatic checking of version updates does NOT work with this plugin! It only works for plugins that are hosted on a particular WordPress plugin site, and this plugin is not hosted there. Sorry!
  10. What new features have been proposed or are under consideration?
    • Add the ability to have multiple routes in a single post/page, maybe with a "prefix" field or a way to insert a break in the route.
    • Add distances to the elevation charts.
    • When importing a GPX file, be smarter about which points to save (e.g. dropping points in the middle of a straight line) rather than only having the ability to skip N points. Note: In the meantime, you might check out the GPSBabel software, and use its "simplify" filter to reduce the points in your GPX file before uploading.
    • Make it possible to have multiple maps on the same page. For instance, on the blog's home page, you might want to have a map for each post, or an aggregate map and a map for each post. Currently this is not possible to do in Routes (you can only have one map per page).
    • Support the "rte" GPX file type (right now Routes only supports the "trk" format). See http://www.topografix.com/gpx.asp for GPX format information.

Theme Modifications Needed to run Routes

There are several modifications you will need to make to standard WordPress Themes, in order to use Routes.

Important: Display of Google Maps (which Routes relies on) in a web page is VERY sensitive to the HTML in the page being valid. So if you are having trouble getting route lines or maps to display, please make sure your theme is producing valid HTML on the page that is having trouble. You can check the validity of HTML at validator.w3.org.

Sample Theme

Because the theme modifications are complex for some Routes users, one thing you might want to do is to download a sample theme with the modifications installed in it. You can either use this theme for your web site (possibly modifying the style), or you can use it as a guide for modifying your preferred theme.

The sample theme is a modified version of the Sandbox theme, and is compatible with WordPress 2.2 or higher, and Routes 1.02 or higher. You can download it at the bottom of the page.

Once you have downloaded the Theme, install and activate just like you would any other WordPress Theme. Then visit the Widgets page in the Presentation section of the WordPress administrations screens, and customize your sidebars (this Theme does not have any of the special Routes sidebar sections in it, by default). Then you can skip to the section below on entering geographical information, if you plan to use Sandbox instead of another theme.

If you are using your own theme, the next sections will tell you how to modify it so it will work with Routes.

Modifications Needed for ALL Maps

There are several modifications you will need to do to your theme, in order to display any maps:

  1. In order for this plugin to work with blog visitors using Internet Explorer (IE), you will need to make sure that your theme's HTML header has a special "namespace" (xmlns) included. To do this, you will need to find the theme file that prints out the HTML header (probably head.php, header.php, or maybe simply index.php), and change the HTML line to look like this:
    <html xmlns="http://www.w3.org/1999/xhtml" xmlns:v="urn:schemas-microsoft-com:vml">
    Note: This may no longer be necessary in Google Maps version 3 (which is what the current versions of Routes use). You can try leaving it out and see what happens... Also, you may need to update more than one Theme file as well, depending on how your theme is organized.
  2. Routes adds JavaScript functions to your blog using the standard "wp_head" mechanism of WordPress. So, for Routes to function correctly, your theme needs to use this mechanism (most do). If your theme is non-standard, make sure it includes the following line somewhere between the HTML <head> tag and the </head> tag in every page that will display a map (usually, like the previous modification, this will just go in the header.php file):
    <?php wp_head(); ?>
  3. If you are using Routes 1.02 or a later version, you will need to add the following line to your Theme, at the very end of the HTML body, after all the DIV tags are closed, but before the </body> tag. These lines will need to go into each theme file that will be used to display a map, so it is probably easiest to put them in your footer.php file, if your theme has one:
    <?php if( function_exists('routes_do_map_js')) {
    routes_do_map_js();
    } ?>

Single Route Maps - Option 1

One main reason for using this plugin is to display a Google Map of a route (or a single location marker) with the posts or pages you have added geographical information to (see the section below on geographical information entry to learn about how to add geographical information to a post or page). Routes only supports having one map on a web page, so you don't want to display the map corresponding to a particular post when you are on an archive page or any page that displays a list of posts (such as the blog's home page). That is, you only want to display a single-route map when the user is viewing a single-post or single-page screen. Here's one way to make this happen, if you always want the maps to be either entirely before or entirely after the text of your posts or pages. (There is another option in the next section, which does not involve modifying your theme.)

  1. Make sure you have followed the "Modifications Needed for ALL Maps" instructions above.
  2. Find the Theme file used to display your post or page. Depending on your theme, for single posts, the file is either single.php (if it exists) or index.php (if it doesn't). If you are adding geographical information to WordPress Pages (i.e. static pages) too, you will need to repeat these steps for the Theme file used to display pages (which is either page.php, index.php, or a custom page template file).
  3. Find the section of the Theme file where the post's (or page's) content is displayed -- it should say:
    <?php the_content(); ?>
    Note that in some themes, you may have to navigate to a different PHP file to find the content. For instance, if there is a line in your index.php, single.php, or page.php file saying something like this:
    <?php require('post.php'); ?>
    (or it could be "include" or "include_once" or "require_once" rather than "require"), then you would look in the file post.php to find where the content is printed.
  4. Open the Theme file you found in a plain-text editor.
  5. Right below the content line, add the following lines to your theme:
    <?php
    if ((is_single() || is_page()) &&
    function_exists( 'routes_map' )) {
    routes_map( get_the_ID(), 500, 400,
    "Text to print above map" );
    } ?>

    You can replace the 500 and 400 with a different width and height (in pixels) if you want a different-sized map, and you can leave out the text to print above the map by just entering "" with no text inside. You can also put the lines above the content line, if you want your map to appear above the text content of the page.
  6. Save the Theme file and upload it to your web server.
  7. If you want maps on your Pages as well as Posts, repeat the steps above with your Theme's pages.php file, or custom page template file, if you have one in your Theme.

Single Route Maps - Option 2

If you are using Routes version 2.1.5 or a later version, you can also get route maps displayed on single-post or single-page web pages using an alternate method, which allows you to put the maps anywhere you would like in your posts and pages. To do this:

  1. Make sure you have followed the "Modifications Needed for ALL Maps" instructions above.
  2. In each post or page, if you want a map to appear, put the following special function line into the body of your post or page:
    [[routes_map( 500, 400, "Text to print above map" )]]
    You can replace the 500 and 400 with a different width and height (in pixels) if you want a different-sized map, and you can leave out the text to print above the map by just entering "" with no text inside.

If you use this method for putting maps in your post, there are a couple of things to remember:

  • Maps will be omitted when you are on an archive page, or any other page that displays more than one page or post.
  • No map will be displayed in any post or page where you forget to put the special function line into the body of the post, even if you have entered geographical information for that post.
  • You cannot mix Option 1 and Option 2 for single route maps. Either modify your theme, or use the special function line, but not both.

Aggregate Route Maps

You can also add an aggregate route map to your "archive" pages and your blog's home page. Basically, this makes it so that whenever WordPress is displaying a list of posts, if they have any routes associated with them, they will be shown on an index map. The map will allow them to pan and zoom (just like any Google map), and it has these additional special features:

  • Clicking on a marker or line in the map takes you to the corresponding post about that route or point.
  • Hovering your mouse over a marker shows you the name of the corresponding post.

Here is how to add aggregate route maps:

  1. Make sure you have followed the "Modifications Needed for ALL Maps" instructions above.
  2. Find the Theme file or files used to display the archives you want to add maps to. Although for some themes that can be a bit complex (you can read about it in this article about the WordPress hierarchy of Theme files), for most themes, the logic is fairly straightforward:
    • For category archive pages, WordPress will use category.php, archive.php, or index.php (in that order, the first one it finds that exists in your theme). You can also have custom category pages for particular categories, such as category4.php for the category whose index is 4.
    • For date-related archives (monthly, daily, yearly), WordPress uses date.php, archive.php, or index.php (in that order, the first one found).
    • For search results, WordPress uses search.php or index.php.
    • For your blog's home page, WordPress uses home.php or index.php (assuming you have your home page set to the default behavior of printing a list of posts).
    Repeat the steps below for each type of archive file you'd like to add a map to.
  3. Open your Theme file in a plain text editor.
  4. Decide where you would like the map to be. If you want it to be above the list of posts, then you need to find the beginning of the WordPress "Loop", and insert just above it. If you want the map to be below the list of posts, then you need to find the end of the WordPress Loop, and insert just after it. To find the beginning and end of the Loop, read this article about the WordPress Loop. Note when reading the article that even if you are running a later version of WordPress, your Theme may be based on an older version.
  5. Insert the following lines into your Theme, either before or after the Loop (but NOT inside the Loop):
    <?php
    if ((is_archive() || is_search() || is_home()) &&
    function_exists( 'routes_map_multiple' )) {
    routes_map_multiple( 500, 400,
    "Text to print above map" );
    } ?>

    You can replace the 500 and 400 with a different width and height (in pixels) if you want a different-sized map, and you can leave out the text to print above the map by just entering "" with no text inside. Also, if you want to have the map print for only some types of archive files, you might need to use other WordPress Conditional Tags. Note that "||" in the list above is PHP syntax for "OR", so for instance if you only want the map to be printed on search and category pages, you would use the line:
    if ((is_category() || is_search()) &&
  6. Save the Theme file and upload it to your web server.
  7. Repeat the steps above for the other Theme archive files that you want maps to appear on.

Note: This function only displays on the map the routes attached to the posts that are displayed below/above it on that particular page of results, so if you want more items displayed, you might want to change the option for "Show at most X posts per page" on the "Reading" screen under "Options" or "Settings" in your WordPress admin panel. You can set that option to the value -1 to make it display all posts no matter what.

Elevation Profiles

If you generate elevation profiles, you can add the following lines to your single-post theme file to show the generated elevation profile chart (see the section above on single-route maps for information on how to find the right theme file and where in the file to insert the chart):

<?php if(( is_single() || is_page() ) &&
function_exists( 'routes_elev_profile' )) {
routes_elev_profile( get_the_ID(), "Text for above chart" );
} ?>

You can replace "Text for above chart" with the text you would like to see above the elevation charts. If there is no chart for the post or page being displayed, neither the text nor any image will be shown.

 

If you want the elevation profiles on multiple-post pages (such as your monthly archive, blog home page, or tag archive pages), use the following in those theme files:
> <?php if( function_exists( 'routes_elev_profile' )) {
routes_elev_profile( get_the_ID(), "Text for above chart" );
} ?>

Or, if you prefer, you can also use the post editor to put the elevation plots directly into your posts, from the Uploads or Add Media area of the post editing screen, once they have been generated (they are generated every time you save your post or page, with the same file name every time, if you have the option set to do that -- see the section below on entering geographical information). If you decide to do that, it is best NOT to put the routes_elev_profile lines above into your theme, or you will end up with two elevation profiles on the screen. One note: In the Add Media dialogs, if you choose to make the image a link to the "attachment page", you will have problems, because each time you save the post, it makes a new image, and it is saved as a new attachment. So either don't make the image link anywhere, or link it to the image, and you will be fine.

Routes has the capability of searching by city and/or state/country (if you enter them in your routes -- see the section below on entering geographical information). If your Theme includes the default WordPress search form, and a user enters a search term, Routes will automatically search in the cities and states/countries you entered (as well as the post titles and content).

You can also offer your visitors a specific city and/or state/country search. There are three ways to do this:

  1. Build your own search form, similar to the default search form in your Theme. Add fields with name and ID equal to "routes_city" to search the City field of your routes, and "routes_state" to search the State/Country field of your routes.
  2. You can also just enter the following in your sidebar (or wherever in your Theme you would like the search form to appear):
    <?php
    if( function_exists( 'routes_search_form' )) {
    routes_search_form( "Keyword", "City", "State", "Search" );
    } ?>

    You can replace "Keyword", "City", "State", and "Search" with the text that you want to use as the labels for the keyword field, city field, state/country field, and search button respectively. And if you would like to leave out one of the fields entirely, just enter "" for that field and it will not be printed.
  3. If you are using WordPress 2.2 or higher with the built-in sidebar "Widgets" functionality, you can add the "Routes Search" widget to your sidebar, and configure it.

Proximity Search Form

Besides the exact searching described above, Routes also has the capability of searching for the closest routes to a point. To add a proximity search to your site, there are two methods:

  1. Put the following lines in your sidebar (or wherever in your Theme you would like the proximity search form to appear):
    <?php
    if( function_exists( 'routes_prox_search_form' )) {
    routes_prox_search_form( "Enter Address", "", "Latitude", "Longitude", "Search" );
    } ?>

    You can replace "Enter Address", "Latitude", "Longitude", and "Search" with the text that you want to use as the labels for the address lookup field, lookup button, latitude field, longitude field, and search button respectively. The way it works is that the blog viewer can enter an address, city, state, country, and/or postal code in the Address field, and then when they tab or click to another field or area of your site, it will look up the latitude and longitude of that point. If Google Maps cannot recognize what they enter, the user will get an error message. Alternatively, they can enter latitude/longitude directly. Then if they click Search, they will see a search results page with the closest trails to that point, in order by distance.
  2. If you are using WordPress 2.2 or higher with the built-in sidebar "Widgets" functionality, you can add the "Routes Proximity Search" widget to your sidebar, and configure it.

State/Country List

Routes also has a function to list the states/countries you have entered into your route points, with each state/country being a link. When a blog viewer clicks the link, they will be shown a list of all the routes that are in that state/country (up to your page limit) -- just as if they used the search by state/country function described above. This list can be added to the sidebar (to show all states/countries you have entered) or to a post/page (to show the states/countries for that particular post/page).

To add the full state/country list to your sidebar (or wherever you want it in your Theme), there are two methods:

  1. Insert the following lines where you want the state list to appear in your theme:
    <?php
    if( function_exists( 'routes_list_states' )) {
    routes_list_states( " | " );
    } ?>

    As shown, a vertical bar "|" will be put between each state in the list. If you would like to have them on separate lines, use "<br />". If you would like to have them separated by commas, use ", ".
  2. If you are using WordPress 2.2 or higher with the built-in sidebar "Widgets" functionality, you can add the "Routes State List" widget to your sidebar, and configure it.

To add the state/country list to a post/page, find the "single.php", "index.php", or other theme file that you want to add the states list to. Then insert the following lines:


<?php
if( function_exists( 'routes_list_states' )) {
echo "States: ";
routes_list_states( ', ', get_the_ID());
} ?>

Note that the per-post list of states is only available in Routes version 2.2.4 or later.

 

Icon Legend

If you are using custom icons and Points of Interest, you may want to display a "legend" that shows what each of your icons means. To do that, figure out where you want the legend in your "single.php", "index.php", or other theme file, and insert the following:


<?php routes_icon_legend(); ?>

Note that only icons that have a legend name entered will be shown in the legend.

 

GPX Download Link

Routes can automatically add a link to each post/page that contains a route, so that visitors to your site can download a GPX file containing the route. To do this, insert the following in your "Loop":


<?php routes_gpx_link(); ?>

You can also change the text shown in the link (which can contain HTML, etc.):

<?php routes_gpx_link('HTML or plain text to go into the link'); ?>

Advanced: Conditional Tags

If you are an advanced theme programmer, you might want to know about two "Conditional Tags" that Routes defines:

  • routes_is_search() : This is like the standard is_search() conditional tag, but it also detects when the user has searched for a specific city, state, and/or country (or clicked on a state/country from the state list).
  • routes_is_prox_search() : This is like the standard is_search() conditional tag, but it detects when the user is using a proximity search.

Entering Geographical Information

Once you have the Routes plugin installed and set up, as described above, you are ready to enter route information for your blog. Route information can be added to both posts and static pages; it works the same for both, so if you want to add information to a page, just follow the directions below and wherever it says "post", substitute "page".

So, first you need to find the Routes data entry section on the post editing screen:

  1. Find a post that you would like to add route information to, or create a new post and enter a title and body.
  2. Scroll down and find where it says "Route Waypoints" near the bottom.
  3. Expand the Route Waypoints section by clicking on the "+" sign on the right of the bar, or arrow on the left side of the bar, if necessary.
  4. At the top of this section, you can define which icons and line type you want to use for this particular post (to override the defaults).
  5. Expand or hide groups of data entry lines, as necessary, by clicking on the "Show/hide rows 1 to ..." links.

There are two types of points you can enter: "route points" and "points of interest" (POI). If you want to have a map, you need to enter at least one route point.

Route Points

Each route point has several fields of information you can enter:

  • Order (Required): An ordering number for the point -- for instance, number the first point 10, the second 20, and so on. That way if you need to insert another point, you can number it 15 to insert it in between. (You can also use decimal numbers in the Order field, if necessary.)
  • Address: Street address of your point -- if you enter the address, city, and state, you can click on the "Lookup" button to use Google Maps to look up the latitude and longitude. Otherwise, Address is not used except for your reference when entering points.
  • City: City where your point is located. This can be used both for the lookup function just described, and for searching by city (see theme page).
  • State/Country: State and/or Country where your point is located. This can be used both for the lookup function just described, and for searching by state/country (see theme page).
  • Latitude and Longitude (Required): Routes are displayed on maps using Latitude and Longitude fields only, so these fields are required. You can use the Lookup button to look up latitude and longitude by address (as described above), enter them directly, or click on the map (see below).

If you click on the "Show/Hide Extended Info" button above the list of route points, you will see an additional line of fields for each route point:

  • Tag: Extra information associated with this point. If you enter something here, blog viewers will see a marker in a single-route map at that point, and if they click on the marker, they will see the information you entered displayed in a Google Maps information window. This information can be plain text or HTML (which you can use for images, links, formatting, etc.). Also, if you have checked the box on the Routes settings screen to create elevation profiles, and the box that says to put markers on the elevation profiles, you will also get a marker on the elevation profile corresponding to the marker on the map.
  • Elevation: You can look up the elevation of the entered latitude and longitude by clicking on the Lookup button; elevation lookup comes from Google Maps. You can also enter elevation values directly. Once you have looked up or entered at least two elevation values for a route and save the post containing the route, an elevation profile graph will be generated (if you have set the option telling Routes to generate elevation profiles -- see the options section). If you forgot to enter elevations, or you imported a GPX file (see below) whose elevations are faulty or missing, you can look up elevations in bulk by using the "Look up 100 elevations" button. It looks up elevations in batches of 100 rows of information, so if you have more than 100 points in your route, you will need to click the button multiple times to update all the elevations.

There are several ways to get information into these fields:

  1. Type information into the fields
    Here are some data entry tips:
    • It's possible to enter just one point for a post or page. In that case, maps will display a marker at that point, rather than a route. If you enter at least two points, single-post maps will show a line connecting all the points in order, and aggregate maps will show a line from the first point directly to the last point, and a clickable marker with the post title.
    • After entering some points, if you find you want to insert another point, just enter it in the bottom line and set its Order to an appropriate value. You can use zero, negative numbers, and decimals. Next time you save, the points will be put in order.
    • After entering some points, if you find you want to delete a point, just click on the checkbox in the "Delete" column, and next time you save, the point will be deleted.
    • If you need more space, click on "Add More Input Lines".
  2. Use the map to enter points.
    To do this:
    1. Click the "Refresh Map" button to show all the points you have already entered. (If the points are not in order, click "Save and Continue Editing" or "Save" instead to put them in order.)
    2. Pan and zoom the map until the desired region is shown.
    3. Click on the map where you want the next point to be. It will be entered in the list and shown on the map. If you have the option set to create elevation maps automatically, and you are using Routes 2.1.5 or later, the elevation of the point where you clicked will also be looked up automatically (just as if you had clicked the elevation lookup button, see above).
    4. At this point, it is a good idea to go up and edit the Order, City, State/Country, and Tag fields (see above for descriptions). When you enter a new point, it is automatically given the previous line's City and State/Country (if entered), and an Order 10 beyond the previous Order, but you can edit those values. If you want to use City or State/Country searching, you will save yourself some time by entering the values after clicking on the first point, or whenever the City changes, so the rest of the City and State/Country values will be entered for you.
    5. To remove a point, click on its marker in the map. It will be removed from the map and marked as Deleted in the list above. To undo, uncheck the Delete check box in the list and click "Refresh Map". Note that if you have entered (or imported) a lot of points, some will be skipped rather than shown on the map, because Google Maps with more than about 50 markers do not display well. If you want to delete points that are not shown, use the checkbox as described above.
    6. Tip: If you enter at least one point using Address lookup (as described above), and then click "Save and Continue Editing", or "Save", the map will be shown pointing to your location rather than the entire world.
    7. Tip: you will see a marker at each point in the map on the edit screen. If you have more than about 50 points, you will only see markers for some of your points, because Google Maps gets really slow with a lot of markers displayed. If you hover over the marker, you will see the point's order value, followed by its latitude and longitude, as an aid to finding it in the list above.
  3. Import a GPS track (latitude, longitude, and elevation information) into a post, if the GPS track is saved as a GPX file. (Note that only GPS tracks in GPX format are supported. GPX "routes" and "waypoints" are not supported, only "tracks", which is what most GPS devices create.)
    To do that:
    1. Enter at least a post title on the post editing screen, and click "Save and Continue Editing" or "Save".
    2. Upload a single GPX file in the Uploads section of the post editing screen (if you need to import several tracks, you can repeat these steps). If you are using WordPress 2.5 or later, uploads are done via the media buttons (use the one that looks like a * and says Add Media when you hover over it, for GPX files), which are located to the right of the post body editor toolbar.
    3. Check the "import GPX" box in the Routes Waypoints section of the post editing screen, and if necessary, check the box saying that the GPX file has elevations in feet.
    4. If the GPX file has a lot of points in it, you might want to enter a number to import just every 3 points, every 10 points, etc. in the box below. You might also check out the GPSBabel software, and use its "simplify" filter to reduce the points in your GPX file before uploading.
    5. Click the "Save and Continue Editing", "Save", or "Save Draft" button on the post editing screen (depending on your WordPress version). Your GPX file will be imported and removed; the new points will come after any other points you had already entered on the map or by address lookup.

However you have chosen to enter your points, when you are done entering your points, click "Save" or "Publish", and your points will be saved, along with the other post/page information. If you are generating elevation profiles, they are also regenerated every time you click "Save", "Save and Continue Editing", or "Publish". Important: The WordPress "auto-save" function, which saves your post's title and body periodically, does NOT save your Routes points! You need to click the "Save" or "Save and Continue Editing" button to make sure your points are saved.

Points of Interest

As of Routes 2.3.0, you can also have Points of Interest (POI) displayed on your per-post maps. These are points that are separate from the main route, and are displayed with custom icons (which you can set up on the Routes Icons settings page).

POI have several fields of information you can enter:

  • Address: Street address and/or city, state, and country of your point -- if you enter this, you can click on the "Lookup" button to use Google Maps to look up the latitude and longitude. Otherwise, Address is not used except for your reference when entering points.
  • Latitude and Longitude (Required): POI are displayed on maps using Latitude and Longitude fields only, so these fields are required. You can use the Lookup button to look up latitude and longitude by address (as described above), enter them directly, or click on the map. This works the same as when entering Route points (see above) -- just make sure the option button is set so that when you click on the map, you get a POI instead of a Route point.
  • Text: If you enter something here, blog viewers can click on the marker, and they will see the information you entered displayed in a Google Maps information window. This information can be plain text or HTML (which you can use for images, links, formatting, etc.).
  • Icon: Choose the icon you want to display this POI with, from the drop-down list. You can create custom icons for your site on the Routes Icons settings page.

Update History for Routes Plugin and Theme

Routes plugin

Version 2.3.3 - Add Google Maps API key, because Google now requires it for new installations using maps.
Version 2.3.2 - Bug fixes regarding metric/English elevation units. Work-around for bug regarding activation not creating tables.
Version 2.3.1 - New features: GPX download, full screen button for maps, set map type default on a per-post basis
Version 2.3.0 - New features: custom icons and line styles, on a per-post basis; Points of Interest separate from route line
Version 2.2.11 - New features: button to look up elevations in bulk, street view control option, and ability to add markers to elevation profiles
Version 2.2.10 - Bug fix - GPX import can fail if you have inline images in your post. Also added messages to appear when you save a post.
Version 2.2.9 - Bug fix - when importing GPX files, the points were not appending to existing route points.
Version 2.2.8 - Bug fix - maps were not displaying in Internet Explorer 6 due to a JavaScript syntax error (not sure about other versions of Internet Explorer)
Version 2.2.7 - Bug fix - proximity search was not working in WordPress 3.0.
Version 2.2.6 - Updated to Google Maps API version 3 (no more API key needed, better printing, but no local search or overview map available). Better editing interface for faster loading when editing a post/page with a route. Elevation lookup is now done through Google maps (faster, more reliable, better coverage). Proximity search form looks up latitude/longitude automatically (no more lookup button).
Version 2.2.5 - Bug fix: when you do a generic keyword search in WordPress, Routes is also supposed to make it search in the city and state/country fields of any routes you have defined. This wasn't working for recent versions of WordPress in Routes 2.2.4 and earlier versions; it now should work in all versions of WordPress.
Version 2.2.4 - Minor bug fix in states list, and add per-post functionality to states list. More status checks on settings page. Add option to use smaller map control.
Version 2.2.3 - Bug fix: list of states was including post/page revisions and unpublished posts/paged, fixed so it only includes states listed in published versions of posts and pages
Version 2.2.2 - Minor bug fixes and editing interface improvements. Add a class to legends on maps and elevation profiles.
Version 2.2.1 - Compatibility with WordPress 2.6's ability to move the wp-content and upload directories (still compatible with older versions of WordPress).
Version 2.2 - New options for Local Search, map scale, overview map, map types, language, and driving directions. Make lines clickable on index maps. Bug fix: sometimes the post edit screen was showing too many markers and loading slowly.
Version 2.1.7 (limited release) - Fix minor internationalization bug. Fix for comma vs. period decimal points in numbers.
Version 2.1.6 - Updates for WordPress 2.5 (still works with earlier versions of WordPress)
Version 2.1.5 - Avoid loading Routes functions on most admin pages, for faster loading when Routes is not needed. Fix HTML error in Routes search forms. Add ability to automatically look up elevations when using map to input points. Add ability to place route maps in middle of body of post/page.
Version 2.1.4 - Added support for PHP 5 DOM library, which will allow PHP 5 users to import GPX files. PHP 4 is also still supported (if the XML DOM extension is installed, as before).
Version 2.1.3 - New feature: GPX import with reduced points. Bug fix: Routes searches now compatible with version 4.2 and above of MySQL (as is the rest of WordPress; previously Routes was using a MySQL 5.x feature in searches).
Version 2.1.2 - limited/internal release
Version 2.1.1 - Bug fixes: GPX import was always converting elevations to feet, state/country list was listing blank states. Also changed Post editing screen so that only about 50 markers are shown on the map -- when showing more the screen took forever to load, or failed to load. And a few terms were missing from the internationalization files.
Version 2.1 - Add ability to import GPX files, "Delete All" button for points, and sidebar Widgets for WordPress 2.2 and above.
Version 2.0 - Add elevation profile charts, proximity search, and point tagging. Add ability to display aggregate maps with smaller markers. Markers on edit screen now show information to help locate them in the table above.
Version 1.02 - Fix Internet Explorer bugs. Note that if you are upgrading, some theme and core WordPress modifications are required, see instructions above.
Version 1.01 - Fix bug: strange characters appearing in marker hover text on aggregate maps. Minor improvements to admin editing interface. Remove markers at ends of single-route maps (now only prints a marker if it's a single-point "route", and prints a route line otherwise).
Version 1.0 - Initial Release.

Routes Sandbox theme

Routes 2.3.1: Added information about gpx download, and uploaded new RoutesSandbox sample theme
Routes 2.3.0: Added information about icon legends
Added information about elevation profiles for multiple-post pages
Routes 2.2.6: Updated instructions for proximity search form

Questions, Comments, and Bugs

The Routes plugin is provided free, with no warranty and no guarantee of service or support. However, Poplar ProductivityWare welcomes your comments. So if you have questions about how to install or use the plugin, suggestions for how to make it better, or wish to report a bug in the plugin, please contact Poplar ProductivityWare.

Please read and follow the instructions on these pages carefully before contacting Poplar ProductivityWare with questions. Especially with Internet Explorer, all of the theme modifications need to be done exactly as specified for Routes to work. Thanks!