Umfassender Leitfaden zur SwupJS-Integration für WordPress/Bricks Builder

Technischer Hintergrund

Was ist Swup?

Swup ist eine JavaScript-Bibliothek, die traditionelle Multi-Page-Websites in Erlebnisse verwandelt, die sich wie Single Page Applications (SPAs) anfühlen. Anstatt bei Klicks auf Links vollständige Browser-Seitenreloads durchzuführen, macht Swup Folgendes:

Warum Swup mit Bricks Builder verwenden?

Bricks Builder erzeugt standardmäßige WordPress-Seiten mit vollständigen HTML-Dokumenten. Ohne Swup führt jede Seitennavigation zu Folgendem:

Mit Swup erhält Ihre mit Bricks erstellte Website:

Wie das Skript funktioniert

Die Datei swup-bricks-integration.js ist eine eigenständige Integration, die:

  1. Swup und Plugins von einem CDN lädt – Keine npm-Installation erforderlich
  2. Übergangs-CSS automatisch einfügt – Styles werden dem Dokument-head hinzugefügt
  3. Alle Optionen zentral konfiguriert – Das Objekt SWUP_CONFIG bündelt die Einstellungen
  4. WordPress-/Bricks-spezifische Besonderheiten behandelt – Schließt Admin-Links aus, berücksichtigt häufige Plugins
  5. Hooks zur Reinitialisierung bereitstellt – Die Funktion reinitializeScripts behandelt Skripte von Drittanbietern

Installationsanleitung

Methode 1: Bricks-Einstellungen (empfohlen)

1. Auf Bricks-Einstellungen zugreifen

Navigieren Sie zu WordPress Admin → Bricks → Einstellungen
Wechseln Sie zum Tab „Custom Code“

2. Das Skript hinzufügen

Suchen Sie den Bereich „Body (footer) scripts“
Fügen Sie den gesamten Inhalt von swup-bricks-integration.js ein, umschlossen von <script>-Tags:

3. Einstellungen speichern

Klicken Sie unten auf „Save Settings“

Methode 2: Code-Element im Template

1. Ihr Header-/Footer-Template bearbeiten

Öffnen Sie den Bricks Builder für Ihr Header- oder Footer-Template
Fügen Sie am Ende des Templates ein „Code“-Element hinzu

2. Das Code-Element konfigurieren

Setzen Sie das Rendering auf „Execute Code“
Fügen Sie das Skript mit <script>-Tags ein

3. Speichern und veröffentlichen

Speichern Sie das Template und veröffentlichen Sie die Änderungen

Methode 3: Child Theme (fortgeschritten)

1. functions.php erstellen oder bearbeiten

2. Die Skriptdatei einfügen

<script>
// Fügen Sie hier den gesamten Skriptinhalt ein
</script>

function enqueue_swup_integration() {
    wp_enqueue_script(
        'swup-bricks',
        get_stylesheet_directory_uri() . '/js/swup-bricks-integration.js',
        array(),
        '1.0.0',
        true // Im Footer laden
    );
}
add_action('wp_enqueue_scripts', 'enqueue_swup_integration');

Erstellen Sie einen Ordner js in Ihrem Child Theme
Speichern Sie das Skript als swup-bricks-integration.js

Konfigurationsleitfaden

Wesentliche Einstellungen

Inhalts-Container

Die wichtigste Einstellung ist containers. Sie definiert, welche Bereiche der Seite Swup ersetzen soll.

Technische Erklärung:
Swup sucht auf der aktuellen und auf der geladenen Seite nach Elementen, die diesen Selektoren entsprechen, und ersetzt dann das innerHTML des aktuellen Elements durch den neuen Inhalt. Der Standardwert #brx-content ist der Haupt-Content-Wrapper von Bricks.

Wichtige Anforderungen:

Häufige Bricks-Container:

Animations-Selektor

Technische Erklärung:
Dieser CSS-Attributselektor trifft auf jedes Element zu, dessen Klasse transition- enthält. Swup überwacht diese Elemente auf transitionend- und animationend-Events, um zu erkennen, wann Animationen abgeschlossen sind.

Verwendung:

  1. Fügen Sie transition-fade, transition-slide oder transition-scale Ihrem Content-Wrapper in Bricks hinzu
  2. Das eingefügte CSS übernimmt die eigentlichen Animationen
  3. Swup wartet, bis diese Elemente fertig animiert sind, bevor neuer Inhalt angezeigt wird
containers: ['#brx-content'],
animationSelector: '[class*="transition-"]',

Animationseinstellungen

Native View Transitions

Technische Erklärung:
Die View Transitions API ist eine neue Browser-Funktion (Chrome 111+, Edge 111+), die hardwarebeschleunigte Übergänge zwischen Seitenzuständen ermöglicht. Wenn aktiviert:

Wann aktivieren:
Nur wenn Ihre Zielgruppe überwiegend Chrome/Edge nutzt und Sie flüssigere Animationen möchten.

Animationsbereich

Optionen:

Empfehlung:
Bei 'html' bleiben, da CSS-Selektoren wie html.is-animating .transition-fade einfacher zu verwenden sind.

Cache-Konfiguration

Cache-TTL (Time-To-Live)

Technische Erklärung:
Swup speichert geladenes Seiten-HTML in einem JavaScript-Map-Objekt im Speicher. Die TTL bestimmt, wie lange zwischengespeicherte Seiten gültig bleiben. Nach Ablauf lädt Swup eine frische Version.

Überlegungen:

Maximale Cache-Einträge

Technische Erklärung:
Begrenzt die Speichernutzung, indem die ältesten Cache-Einträge entfernt werden, sobald das Limit überschritten wird. Dies wird über den Hook cache:set umgesetzt.

nativeViewTransitions: false,
animationScope: 'html',
cacheTTL: 5 * 60 * 1000, // 5 Minuten in Millisekunden
maxCacheEntries: 20,

Preload-Einstellungen

Wie Preloading funktioniert:

  1. Hover-Preload: Wenn der Benutzer über einen Link hovert, lädt Swup diese Seite sofort
  2. Sichtbare Links: Die Intersection Observer API erkennt Links, die in den Viewport kommen
  3. Throttle: Begrenzung gleichzeitiger Requests, um den Server nicht zu überlasten

Technischer Vorteil:
Bis der Benutzer klickt, liegt die Seite bereits im Cache und die Navigation wirkt sofort.

WordPress-spezifische Einstellungen

Ignore-Selektoren

Technische Erklärung:
Die Funktion buildIgnoreVisit erstellt einen Callback, der jeden Link-Klick gegen diese Selektoren prüft. Passende Links verwenden normale Browser-Navigation statt Swup-Übergänge.

Warum diese ignorieren:

preloadEnabled: true,
preloadOnHover: true,
preloadVisibleLinks: false,
preloadThrottle: 3,

ignoreSelectors: [
  '[data-no-swup]',
  '#wpadminbar a',
  'a[href*="wp-admin"]',
  'a[href*="wp-login"]',
  'a[href*="/cart"]',
  // ... weitere
],

Übergänge zu Ihrer Bricks-Seite hinzufügen

Schritt 1: Übergangsklasse zum Inhalt hinzufügen

  1. Öffnen Sie den Bricks Builder in Ihrem Haupttemplate (meist „Single“ oder „Archive“)
  2. Wählen Sie Ihren Haupt-Content-Wrapper
  3. Gehen Sie zu Style → CSS Classes
  4. Fügen Sie die Klasse transition-fade hinzu

Alternativ können Sie den Standard-Bricks-Content-Wrapper direkt in Ihrem CSS ansprechen:

#brx-content {
  /* Dies wird das animierte Element */
}

Und den animationSelector im Skript anpassen:

animationSelector: '#brx-content',

Schritt 2: Übergangsstile anpassen

Das Skript fügt Standard-Styles über die Konstante TRANSITION_CSS ein. Sie können diese in Bricks unter „Custom CSS“ überschreiben:

/* Langsamerer Fade-Übergang */
html .is-changing .transition-fade {
  transition: opacity 0.5s ease-in-out;
}

/* Benutzerdefinierte Slide-Richtung */
html .is-leaving .transition-slide {
  transform: translateX(-100%);
}

html .is-rendering .transition-slide {
  transform: translateX(100%);
}

Schritt 3: Übergänge testen

  1. Öffnen Sie Ihre Website (nicht im Bricks-Editor)
  2. Öffnen Sie die Browser-DevTools → Konsole
  3. Aktivieren Sie den Debug-Modus im Skript:
debug: true,

Umgang mit Drittanbieter-Skripten

Das Reinitialisierungsproblem

Technischer Hintergrund:
Wenn Swup Inhalte ersetzt, wird neues HTML eingefügt, aber JavaScript nicht erneut ausgeführt. Skripte, die:

... funktionieren auf dem neuen Inhalt nicht mehr, da sie nur beim initialen Laden ausgeführt wurden.

Lösung: Die Funktion reinitializeScripts

Die Funktion reinitializeScripts wird nach jedem Seitenübergang aufgerufen:

function reinitializeScripts() {
  // Bricks Frontend-JS
  if (typeof bricksInit === 'function') {
    bricksInit();
  }

  // Benutzerdefiniertes Event für Ihre Skripte
  document.dispatchEvent(new CustomEvent('swup:contentReplaced', {
    detail: { swup: window.swup }
  }));

  // Reinitialisierungen von Drittanbietern...
}

Eigene Reinitialisierungen hinzufügen

Methode 1: Funktion direkt erweitern

function reinitializeScripts() {
  // ... bestehender Code ...

  // Ihre benutzerdefinierte Initialisierung
  if (typeof MyCustomSlider !== 'undefined') {
    MyCustomSlider.init();
  }
}

Methode 2: Auf ein benutzerdefiniertes Event hören

document.addEventListener('swup:contentReplaced', function(event) {
  // Ihre Skripte hier erneut initialisieren
  initializeMyComponents();
});

Methode 3: Den onPageView-Callback verwenden

Im Objekt SWUP_CONFIG:

onPageView: function(visit) {
  // Wird nach jedem Seitenübergang aufgerufen
  console.log('Navigiert zu:', visit.to.url);

  // Komponenten neu initialisieren
  initializeLightboxes();
  initializeSliders();
}

Analytics-Integration

Google Analytics 4

Das Skript enthält GA4-Tracking in onPageView:

if (typeof gtag !== 'undefined') {
  gtag('config', 'GA_MEASUREMENT_ID', {
    page_path: visit.to.url
  });
}

Wichtig:
Ersetzen Sie GA_MEASUREMENT_ID durch Ihre echte Measurement-ID (z. B. G-XXXXXXXXXX).

Matomo/Piwik

Ebenfalls enthalten:

if (typeof _paq !== 'undefined') {
  _paq.push(['setCustomUrl', visit.to.url]);
  _paq.push(['trackPageView']);
}

Weitere Analytics-Plattformen

Fügen Sie ähnlichen Code in onPageView ein:

// Facebook Pixel
if (typeof fbq !== 'undefined') {
  fbq('track', 'PageView');
}

// Plausible
if (typeof plausible !== 'undefined') {
  plausible('pageview');
}

Fehlerbehebung

Problem: Harter Seitenreload statt Übergang

Ursachen:

  1. Container nicht gefunden: Stellen Sie sicher, dass #brx-content auf allen Seiten existiert
  2. Link wird ignoriert: Prüfen Sie, ob der Link zu ignoreSelectors passt
  3. Externer Link: Swup verarbeitet nur Links derselben Origin

Debug-Schritte:

  1. debug: true aktivieren
  2. Konsole auf Swup-Logs prüfen
  3. Prüfen, ob der Container existiert:
    document.querySelector('#brx-content')

Problem: Animationen funktionieren nicht

Ursachen:

  1. Fehlende Übergangsklasse: transition-fade zum Content-Wrapper hinzufügen
  2. CSS nicht eingefügt: Prüfen, ob das Style-Element #swup-transitions im <head> existiert
  3. Animationsselektor stimmt nicht: Sicherstellen, dass Ihre Klasse zum Muster von animationSelector passt

Debug-Schritte:

  1. Das <html>-Element während der Navigation auf Klassen wie is-changing, is-animating prüfen
  2. Die berechneten Styles der Übergangselemente kontrollieren

Problem: Skripte laufen nach Navigation nicht

Ursache:
JavaScript wird nur beim ersten Seitenaufruf ausgeführt.

Lösung:
Reinitialisierungscode in reinitializeScripts ergänzen oder auf das Event swup:contentReplaced hören.

Problem: Formulare werden nicht korrekt abgesendet

Ursache:
Swup verarbeitet standardmäßig keine Formularübermittlungen.

Lösungen:

  1. data-no-swup zum Submit-Link/Button hinzufügen
  2. Das Swup Forms Plugin installieren (zu den CDN-URLs hinzufügen und aktivieren)

Problem: Scroll-Position bei fixiertem Header

Lösung: scrollOffset anpassen:

scrollOffset: 80, // Höhe Ihres fixierten Headers in Pixeln

Performance-Optimierung

Empfohlene Produktionseinstellungen

const SWUP_CONFIG = {
  // Debug-Logging deaktivieren
  debug: false,

  // Caching optimieren
  cacheEnabled: true,
  maxCacheEntries: 30,
  cacheTTL: 10 * 60 * 1000, // 10 Minuten

  // Preloading aktivieren
  preloadEnabled: true,
  preloadOnHover: true,
  preloadThrottle: 5,

  // Nicht benötigte Plugins deaktivieren
  scriptsEnabled: false, // Nur aktivieren, wenn unbedingt nötig
  progressBarEnabled: true,

  // Native Transitions für unterstützte Browser aktivieren
  nativeViewTransitions: true,
};

Auswirkungen messen

Verwenden Sie die Browser-DevTools zum Vergleich von:

  1. Network Waterfall – Voller Seitenload vs. Swup-Navigation
  2. Performance-Timeline – Zeit bis zur Interaktivität messen
  3. Core Web Vitals – LCP, FID, CLS vor und nach der Implementierung beobachten

Erweiterte Anpassung

Benutzerdefinierte Animation pro Link

Verwenden Sie das Attribut data-swup-animation:

<a href="/gallery" data-swup-animation="slide">Galerie ansehen</a>

Dies fügt während des Übergangs die Klasse to-slide zu <html> hinzu. Erstellen Sie dazu passendes CSS:

html.is-changing.to-slide .transition-fade {
  transition: transform 0.4s ease;
}

html.is-leaving.to-slide .transition-fade {
  transform: translateX(-100%);
}

html.is-rendering.to-slide .transition-fade {
  transform: translateX(100%);
}

Programmatische Navigation

Greifen Sie global auf die Swup-Instanz zu:

// Zu einer Seite navigieren
window.swup.navigate('/about');

// Ohne Animation navigieren
window.swup.navigate('/contact', { animate: false });

// Cache leeren
window.swup.cache.clear();

Bestimmte Seiten ausschließen

Seiten dynamisch anhand der URL ignorieren:

ignoreVisit: function(url, { el } = {}) {
  // Checkout-Seiten ignorieren
  if (url.includes('/checkout/')) return true;

  // Bestimmte Seite ignorieren
  if (url === '/special-page/') return true;

  // Element gegen Ignore-Selektoren prüfen (Standardverhalten)
  const { ignoreSelectors } = SWUP_CONFIG;
  if (el) {
    for (const selector of ignoreSelectors) {
      if (el.closest(selector)) return true;
    }
  }

  return false;
}

Dieser Leitfaden deckt die vollständige Einrichtung und Anpassung der SwupJS-Integration für Bricks Builder ab. Bei weiteren Fragen oder Problemen beziehen Sie sich auf die offizielle Swup-Dokumentation oder prüfen Sie die ausführlichen Kommentare in der Datei swup-bricks-integration.js.

Revision #1
Created 2026-06-21 05:03:43 UTC by art10m
Updated 2026-06-21 05:04:02 UTC by art10m