How it fits together

Three things share the work, and knowing which owns what saves a lot of hunting:

• The plugin owns the data. Shuttles, routes, stops, timetables, fares, seats, bookings and payment all come from Magepeople Shuttle Booking. If a price is wrong or a departure is missing, it is fixed in the plugin, not here.
• The theme owns the presentation. Every colour, heading, band and layout on the public site is a theme setting.
• WordPress owns the pages. The theme creates eight of them for you and assigns the right template to each.

Plugins it knows about

Guided setup

On first activation the theme opens EasyShuttle → Guided Setup. It runs in order, and every step is safe to leave half-done — each one checks the site and reports what is already in place rather than repeating work.

1. 1
   PluginsThe booking engine
2. 2
   PagesHome, routes, booking
3. 3
   MenuHeader navigation
4. 4
   Demo contentSample routes
5. 5
   FinishStyle your site

The pages

Step two creates these. An existing page with the same slug is adopted, never overwritten, so running setup on a live site is safe.

Build modes

Under Theme Options → Page builders, choose how pages are assembled:

• Theme layouts — pages render from the templates and their Theme Options copy. Nothing to edit visually; fastest and the least that can break.
• Blocks — each section is also a block, so pages are editable in the block editor.
• Elementor — every section is an Elementor widget too.

Switching only rewrites pages the theme created and has not seen edited, and it backs up the previous state first. Pages you authored yourself are skipped.

Architecture

Load order matters and is fixed in functions.php: defaults before helpers, helpers before anything that reads options, and the shuttle data layer before the renderers that use it.

easyshuttle/
├── functions.php              load order, theme supports, enqueues
├── inc/
│   ├── defaults.php           every option's default + easyshuttle_option()
│   ├── shuttle-data.php       reads the plugin: shuttles, routes, fares
│   ├── helpers.php            presentation helpers used by templates
│   ├── sections.php           the section registry (schema for all 23)
│   ├── section-renderers.php  one render function per section
│   ├── setup.php              starter pages, asset gating, contact handler
│   ├── class-easyshuttle-theme-options.php   the admin screen
│   ├── class-easyshuttle-setup-wizard.php    guided setup
│   ├── class-easyshuttle-seo.php             titles, cards, schema
│   ├── class-easyshuttle-email-delivery.php  contact form delivery
│   └── builders/              shortcodes, blocks, Elementor, Divi, build mode
├── page-templates/            8 page templates
├── template-parts/            shared partials
└── assets/                    css, js, fonts, img, admin

The section system

This is the core idea worth understanding. A section is declared once in easyshuttle_sections() — label, description, icon and its fields. From that single declaration the theme derives, automatically:

• a shortcode
• a block, registered per section with its attributes
• an Elementor widget
• a Divi module
• the Theme Options fields that feed it, where a field declares an option

Add a section to that array and all five follow. There is no second place to register it.

Options API

Everything is stored in one option, easyshuttle_theme_options, read by dot path:

easyshuttle_option( 'header.sticky' );          // one value, with its default
easyshuttle_option( 'brand.site_name', 'Fallback' );
easyshuttle_get_options();                     // the whole merged tree

Three behaviours are worth knowing before you touch the save path:

• Defaults are merged, not copied. A key absent from the database falls back to easyshuttle_default_options(), so upgrades that add a setting need no migration.
• Saving is atomic across panels. All panels post together; a hidden panel field of all tells the sanitiser every checkbox was on screen, which is how unticking one records as off.
• A stale form is refused. Each form carries a revision hash; if the options changed elsewhere while you were editing, the save is rejected rather than clobbering.

Hooks

The theme's own extension points. Everything else is standard WordPress.

SEO module

On by default and self-effacing: easyshuttle_seo_defer_to_plugin lets it stand down when Yoast, Rank Math or similar is active, so tags are never printed twice. When it owns the output it emits the title, meta description, canonical, Open Graph and Twitter cards, and a JSON-LD graph of Organization, WebSite, WebPage and BreadcrumbList — plus route data on shuttle pages.

• Titles cap at 70 characters, descriptions at 160.
• Search results and 404s are noindexed; per-post overrides live in the editor sidebar.
• Hidden WooCommerce products — the ones the booking plugin mints per shuttle to carry a price — are kept out of both the sitemap and the index. Without that they are submitted to search engines as thin, machine-named pages.

Extending

Add a section

Declare it, then write its renderer. Nothing else is needed for the shortcode, block, Elementor and Divi versions to appear.

add_filter( 'easyshuttle_sections', function ( $sections ) {
    $sections['notice'] = array(
        'label'       => 'Service notice',
        'description' => 'A single line above the fold.',
        'icon'        => 'eicon-alert',
        'fields'      => array(
            'text' => easyshuttle_field( 'text', 'Message' ),
        ),
    );
    return $sections;
} );

function easyshuttle_section_notice( array $a ) {
    printf( '<p class="es-notice">%s</p>', esc_html( $a['text'] ) );
}

Replace the stand-in artwork

Empty image slots fall back to bundled SVGs rather than an empty panel. Swap them site-wide without touching a section:

add_filter( 'easyshuttle_default_art', function ( $url, $name ) {
    return 'fleet' === $name ? get_stylesheet_directory_uri() . '/my-fleet.jpg' : $url;
}, 10, 2 );

Tests

The theme ships its own checks. Run them after any change:

php wp-content/themes/easyshuttle/tests/static-checks.php   # no WordPress needed
wp eval-file wp-content/themes/easyshuttle/tests/wp-integration.php

The static suite asserts the things that break quietly — escaping on output, asset paths that exist, the section registry matching its renderers, and the admin behaviours that have regressed before. The integration suite is read-only apart from an options round trip it restores.