Routes WordPress Plugin

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's List of Bike Trails.

On these pages, you can learn about how to install and use the Routes plugin. 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.
• Blog viewers see a Google Map of the route or point on the post/page screen, with tagged points marked, as well as overview maps on category/index pages.
• Optionally, create and display elevation charts of your routes.
• 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 (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). A Spanish translation (both PO and MO files) and the POT file for translating into other languages are 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 are upgrading from a previous version of Routes, deactivate Routes temporarily before uploading the new file, and then activate it again after uploading. If you need more detailed information on how to manage WordPress plugins, please visit the Managing Plugins page on the WordPress site.
5. 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, and optionally change some 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.
   • Map Features: Google Maps has several optional features that can be shown on your Google Maps, including a scale of miles/km. For best results, choose no more than 2 of these 3 features. A map control that lets you zoom and pan the map is always shown as well; if you check the box, you can display a smaller version (useful if your map display is small).
   • 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.
   • Use small icons on index maps: Check this box to show small markers on multiple-route maps, such as your blog's home page. If it is not checked, the larger standard Google Maps markers will be used.
   • Use special green icon at start of route: Check this box if you want to put a green arrow marker at the start of the route on a single-route map. This is useful if you are displaying elevation profiles, so viewers will know which end of the route is the start. Another option would be to tag the start and end of the route with text tags, but this requires the user to click the tag to see tag 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 (see below for more information). 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 (see below for more information on that) and on elevation profiles. If it is not checked, Routes will use English units (feet).
   • 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.
   • Background color, line/text color, and fill color of 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), and the color used to fill the elevation profile chart (defaults to a blue color). 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 (separate page).

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

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 instructions for 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 page). 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 3.0.
9. How can I find out if there is a new version of the plugin?
   Subscribe to the RSS feed on the sidebar of this page, or 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 download the point information as a GPX file, from the post editing screen, and/or from the blog. Note: GPX format information.
    • 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 the ablity to change the color of route lines on the map, and use different markers. It's also been suggested to have category-based markers on aggregate maps, so posts in certain categories would get certain markers on the map. Or each post could have its own marker choice when editing, and use that marker on the aggregate map.
    • Add distances to the elevation charts.

Questions, Comments, and Bugs

The Routes plugin is provided free, with no warrantee 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 or leave a comment below.

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

File Downloads: 

Routes.zip - Routes plugin, version 2.2.8 - 42.8 KB (43,831 bytes)