Routes WordPress Plugin

Theme Modifications

This is the second page describing the Routes plugin for WordPress. If you didn't start on the first page, you might want to go back and start there.

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 page 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 page 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: blockquote class="code"> <?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 page 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.

Exact Search Form

Routes has the capability of searching by city and/or state/country (if you enter them in your routes). 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.
Updates: 
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