Setup Wizard

Overview

The wizard automatically detects a first-time installation and will redirect you to the setup page (Routes → Setup) after you activate the plugin. It can be safely re-run at any time from the same location without duplicating settings or pages.

For advanced users, the wizard can be skipped, and all settings can be configured manually via the various sub-menus under the main "Routes" admin menu.

The 8-Step Process

The wizard guides you through eight steps, with a progress bar and clear feedback for each action.

Step 1: Import ACF Fields

This is a critical first step. The plugin uses Advanced Custom Fields (ACF) to store all route data. This step imports the necessary field definitions from the plugin's acf.json file, creating the database structure for things like distance, elevation, GPX file links, and destination details.

Step 2: Apply Default Configuration

This step populates the database with a sensible set of default settings, so the plugin works out-of-the-box. This includes:

• Setting the default map provider to OpenStreetMap (which is free and requires no API key).
• Creating default "Club Groups" (e.g., Leisurely, Moderate, Brisk).
• Creating default "Climbing Profiles" (e.g., Flat, Rolling, Hilly, Mountainous).
• Establishing default "Activity Types" (e.g., Road Cycling, Gravel, MTB, Hiking).
• Configuring default filter visibility and behaviour.
• Setting up permission and access control defaults.

Step 3: Map API Configuration (Optional)

This is an informational step that explains the different map providers available (like Thunderforest and Google Maps) and links to the configuration page where you can enter API keys if you choose to use a premium provider. No action is required here to get started, as OpenStreetMap works without any API key.

Step 4: Create Required Pages

The plugin automatically creates two essential pages on your website:

• /route-finder - This page is created with the necessary block or shortcode to display your main route filter and results interface.
• /group-routes - A page required for the route grouping features to function correctly.

If these pages already exist, the wizard will skip this step to avoid creating duplicates.

Step 5: GPX Folder Setup

This step creates a dedicated folder at /wp-content/uploads/rfcc-gpx/ for storing all your uploaded route files (GPX, KML, TCX, FIT). It sets the correct file permissions and creates a .htaccess file to ensure the files are accessible for download by your visitors.

Step 6: Configure File Upload Types

By default, WordPress does not allow uploading of GPS file formats. This step updates your site's settings to permit the uploading of the following file types through the WordPress Media Library and the plugin's uploaders:

• .gpx (GPS Exchange Format)
• .kml (Keyhole Markup Language)
• .tcx (Training Center XML)
• .fit (Flexible and Interoperable Data Transfer)

Step 7: Configuration Pages Reference

An informational step that provides a quick-reference guide with links to all the key configuration areas of the plugin:

• Routes → Config - Main plugin settings
• Routes → Config → Club Groups - Rider group definitions
• Routes → Config → Climbing Profiles - Elevation-based categorisation
• Routes → Config → Route Types - Filter shortcuts
• Routes → Config → Activity Types - Activity categorisation

Step 8: Get Started

The final step provides a launchpad for you to begin using the plugin. It includes:

• A special "Add Your First Route" link. When clicked, it opens the "All Routes" table and activates an animated spotlight effect, guiding you directly to the "Add New Route" button.
• Convenient links to manage routes, manage destinations, and view the public-facing route finder page.
• A button to mark the setup as complete.

Re-running the Setup Wizard

The wizard can be re-run at any time without causing problems:

1. Navigate to Routes → Setup in the WordPress admin menu.
2. Follow the same 8-step process.
3. Existing settings and pages will not be duplicated - the wizard checks for existing data before creating new entries.

This is safe to run multiple times, for example if you need to re-import ACF fields after a plugin update or want to reset to default configuration.

Troubleshooting

ACF Fields Not Importing

If the ACF import fails:

• Ensure the Advanced Custom Fields Pro plugin is installed and activated.
• Check that the acf.json file exists in the root of the Route Finder plugin directory.
• You can safely try running Step 1 again.

Pages Not Created

If the required pages fail to create:

• Check that your WordPress user has permission to create pages.
• Verify there are no permalink conflicts with existing pages.
• You can manually create the pages and add the appropriate shortcodes if needed.

GPX Folder Not Writable

This usually indicates a file permission issue on your server:

• Manually set the permissions of the /wp-content/uploads/ directory to 755 or 775.
• Contact your hosting provider if the issue persists - they may need to adjust server-level permissions.

File Types Not Added

Some hosting providers have strict security policies that prevent modification of allowed file types:

• Contact your hosting provider for assistance.
• You may need to add the file types manually via your site's wp-config.php file.
• Some hosts may require a security plugin exception.