Routes WordPress Plugin
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.
- 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
- 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
- Download the plugin file (bottom of this page). You will probably need to change the name to Routes.tar.gz.
- 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.)
- 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.
- 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.
- 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.
- 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.)
- 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.
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 separate page 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.
- I am having trouble with Routes in Internet Explorer. What could cause that?
- 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.
- 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.
- 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.
- 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.
- 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.
- 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
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.
- 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.
- How can I find out if there is a new version of the
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!
- 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.
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!