Configuration & Setup

This guide covers the initial setup and the ongoing configuration of the Route Finder plugin. These settings are found under the main Routes menu in the WordPress admin sidebar.

Initial Plugin Setup (The "Setup" Page)

The Setup page, found under Routes → Setup, is the first place you should visit after installing the plugin. It handles critical prerequisites and data management.

ACF Setup

Purpose

Advanced Custom Fields (ACF) is the backbone of this plugin's data storage. Without its specific field structure, WordPress has nowhere to save crucial information like a route's distance, ascent, or associated GPX file URL. Running the import process creates this required structure in your database.

Usage Guide

  1. Confirm the ACF Plugin Status shows as "Available". If not, you must install and activate the Advanced Custom Fields Pro plugin.
  2. Click the "Import ACF Fields from JSON" button. This will read the `acf.json` file from the plugin directory and load all the necessary field groups into ACF.
  3. Once complete, the status indicators for the field groups should turn green.

User Access

This tab allows you to control which user roles can access the plugin's features, both in the backend and on the frontend.

Export/Import

This powerful tool allows you to create backups of your route data and plugin settings, or to migrate them to another website.

Data Management

This tab contains a critical setting for plugin removal. If the "Uninstall Cleanup" option is checked, ALL plugin data (routes, settings, files) will be permanently deleted when you uninstall the plugin. Leave this unchecked if you might want to reinstall the plugin later and keep your data.

Main Plugin Configuration (The "Config" Page)

The Config page, found under Routes → Config, contains all the day-to-day settings for controlling the appearance and functionality of your maps and routes. It is organised into several tabs.

Map Providers

This is the heart of the map system. You can select different map tile providers and enter the necessary API keys. The plugin supports:

You can set different default providers for different contexts, such as large single-route maps versus the small thumbnail maps on list pages.

Default Map Location & Zoom

Set the default starting geographical location (latitude/longitude) and zoom level for maps when they first load without a specific route to display.

Map Options

Fine-tune map behaviour, such as enabling scroll-wheel zoom, fullscreen buttons, and the colour and thickness of the GPX track line.

Map Search Feature

The Map Search feature adds a powerful search button to route maps, allowing users to find points of interest directly on the map.

What is Map Search?

When enabled, a search icon (🔍) appears in the top-right corner of route maps on single route pages. Users can click it to search for nearby:

Search results appear as blue markers on the map with detailed information in a side panel. Results are automatically limited to the route area plus a 2km buffer, ensuring users only see relevant nearby places.

Enabling and Disabling

Go to Routes → Config → Route Info Display tab and look for these two settings:

  1. Enable Map Search - Controls whether the search button appears on route maps. When disabled, users won't see any search functionality.
  2. Use Google for Map Search - Determines which search provider to use (see below).

Search Providers: Google vs OpenStreetMap

The plugin supports two search providers, each with different advantages:

Google Places API (Premium Option)

Advantages:

  • More comprehensive business data
  • Includes ratings and reviews
  • Better coverage of commercial establishments
  • Higher quality results

Disadvantages:

  • Requires Google Places API key setup
  • Incurs usage costs ($32 per 1,000 searches)
  • Requires IP address restrictions (not HTTP referer)

Best for: Sites with budget for API costs that need comprehensive business information with ratings/reviews.

OpenStreetMap Overpass API (Free Option)

Advantages:

  • Completely free, no API costs
  • No configuration or API key required
  • Good coverage in many areas
  • Community-maintained data

Disadvantages:

  • Less comprehensive business data
  • No ratings or reviews
  • Data quality varies by area
  • May be slower during peak times

Best for: Sites on a budget, or areas with good OpenStreetMap coverage where basic POI data is sufficient.

Setting Up Google Places Search

To use Google Places instead of OpenStreetMap:

  1. Go to the Google Cloud Console
  2. Create a new API key (or use existing one)
  3. Enable Places API (New) in the API Library
  4. Enable Geocoding API as well
  5. Under API key restrictions:
    • Set Application restrictions to IP addresses
    • Add your server's IP address
    • IMPORTANT: Do NOT use HTTP referrer restrictions - they won't work for server-side searches
  6. Consider setting daily usage quotas to control costs
  7. In WordPress, go to Routes → Setup → Map & API Configuration
  8. Find the Google Places API Key field
  9. Paste your API key and click Save API Keys
  10. Return to Routes → Config → Route Info Display
  11. Check Use Google for Map Search
  12. Click Save Changes

How Users Use Map Search

  1. User opens any single route page
  2. Clicks the search icon (🔍) in the top-right of the map
  3. A panel slides out with a search box
  4. User types what they're looking for (e.g., "bike shop", "cafe", "parking")
  5. Clicks search or presses Enter
  6. Results appear as blue markers on the map and in a list
  7. Clicking a result in the list shows its popup on the map
  8. If user pans/zooms the map, a "Search this area" button appears to refresh results

Supported Search Terms

The system intelligently interprets common search terms. Examples include:

Cost Considerations for Google Places

If using Google Places search:

Tip: Start with OpenStreetMap (free) and switch to Google Places later if you need more comprehensive business data.

Troubleshooting

No search button appears:

Google Places not working:

OpenStreetMap search slow or timing out:

Styles

Control the visual style of the plugin's frontend interface to match your site's theme. You can set the colours for many elements, including:

Filter Options

Customise the route filtering sidebar, including which options are visible (e.g., distance sliders, climbing profiles) and whether the filter box is open or closed by default when a user first visits the page.