Livewire Navigation & Page Components

CMS content is routed by Laravel as usual. On top of that, Livewire can optionally speed up navigation between pages, and any theme template can be a full Livewire component.

Both features need @livewireStyles and @livewireScripts in your theme layout. The example theme already includes them.

Your own Route::livewire() routes in routes/web.php keep working alongside the CMS. FrankenCMS registers its catch-all route last, so your routes are matched first.

SPA-Style Navigation

Turn on wire:navigate for theme links in .env. Clicking a link then fetches the next page in the background and swaps the body, without a full page reload:

bash
CMS_LIVEWIRE_NAVIGATE=true

# Optional: prefetch pages on hover (wire:navigate.hover)
CMS_LIVEWIRE_NAVIGATE_PREFETCH=true

Menu items, breadcrumbs, and the example theme's post, category, and tag links pick this up automatically. A link only gets wire:navigate when it's internal and opens in the same tab. These always do a normal full page load:

  • External URLs, #anchors, and mailto: / tel: links
  • File URLs such as sitemap.xml or uploaded PDFs
  • Paths matching franken-cms.livewire.navigate_except (by default admin and feed)

Your Own Theme Links

Apply the same rules to links in your own templates with the directive or the helper:

blade
<a href="{{ $url }}" @frankenNavigate($url)>Read more</a>

@
<a href="{{ $url }}" {{ franken_navigate($url, $target) }}>Read more</a>

Both output nothing when navigation is turned off, so templates work either way.

Things to Know

  • Scripts that run on DOMContentLoaded only run on the first page load. Listen for livewire:navigated instead.
  • Wrap anything that should survive navigation, like an audio player, in @persist('player') … @endpersist. Don't persist a header that highlights the active menu item, or the highlight won't update.
  • Head tags are rendered on the server for every page and merged by Livewire. Search engines always do full page loads, so SEO output is unchanged.

Livewire Page Templates

A theme template can be a Livewire single-file component instead of a plain Blade view. Save it in your theme folder with the usual naming (page-…, post-…) and choose it in the editor like any other template. Don't use the ⚡ filename prefix, or the template won't appear in the template list.

resources/views/theme/page-newsletter.blade.php
<?php

use FrankenCms\Livewire\Concerns\InteractsWithFrankenPage;
use Livewire\Component;

new class extends Component {
    use InteractsWithFrankenPage; // provides $page / $post and $frankenFields

    public string $email = '';

    public function subscribe(): void
    {
        $this->validate(['email' => 'required|email']);
        // ...
    }
};
?>

<div>
    <h1>@frankenText('hero.title', ['label' => 'Title', 'default' => 'Join the list'])</h1>

    <form wire:submit="subscribe">
        <input type="email" wire:model="email">
        <button>Subscribe</button>
    </form>
</div>

Things to know:

  • @franken* fields work as they do in plain templates. They show up in the editor, and their values stay available on every render, including Livewire updates.
  • The page is wrapped in the layout set in franken-cms.livewire.layout. If that's not set, the example theme's theme.components.layouts.main.index is used when it exists, then Livewire's component_layout. A #[Layout] attribute on the component overrides all of these.
  • Blog listing and archive templates written as components load their own posts, for example with WithPagination. The CMS passes only $page or $post, never a posts paginator.
  • Plain Blade templates are never treated as components. To switch the feature off entirely, set CMS_LIVEWIRE_PAGE_COMPONENTS=false.

Configuration Reference

config/franken-cms.php
'livewire' => [
    'navigate'          => env('CMS_LIVEWIRE_NAVIGATE', false),
    'navigate_prefetch' => env('CMS_LIVEWIRE_NAVIGATE_PREFETCH', false),
    'navigate_except'   => ['admin', 'admin/*', 'feed', 'feed/*'],
    'page_components'   => env('CMS_LIVEWIRE_PAGE_COMPONENTS', true),
    'layout'            => null, // e.g. 'theme.components.layouts.main.index'
],

Next Steps