Skip to main content

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:

  • Ein vollständiger Browser-Reload wird ausgelöst
  • HTML, CSS und JavaScript werden komplett neu eingelesen
  • Alle Skripte und Komponenten werden neu initialisiert
  • Zwischen Seiten entsteht ein sichtbares „Flackern“

Mit Swup erhält Ihre mit Bricks erstellte Website:

  • Verbesserte wahrgenommene Performance – Seiten wirken, als würden sie sofort laden
  • Sanfte visuelle Übergänge – Professionelle Fade-, Slide- oder Scale-Effekte
  • Reduzierte Serverlast – Zwischengespeicherte Seiten werden aus dem Speicher geladen
  • Bessere Benutzererfahrung – App-ähnliches Navigationsgefühl

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:

  • Der Container muss auf jeder Seite Ihrer Website vorhanden sein
  • Der Selektor darf pro Seite genau ein Element treffen
  • Der Container sollte sich innerhalb von <body> befinden

Häufige Bricks-Container:

  • #brx-content – Hauptinhaltsbereich (Standard)
  • #brx-header – Falls sich Ihr Header zwischen Seiten ändert
  • .custom-sidebar – Wenn Sie eine dynamische Sidebar haben

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:

  • Der Browser erstellt eine Momentaufnahme der aktuellen Seite
  • Neuer Inhalt wird außerhalb des sichtbaren Bereichs gerendert
  • Der Browser animiert GPU-beschleunigt zwischen den Zuständen

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

Animationsbereich

Optionen:

  • 'html' – Animationsklassen (is-changing, is-animating usw.) werden auf das <html>-Element angewendet
  • 'containers' – Klassen werden direkt auf die Container-Elemente angewendet

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:

  • Websites mit dynamischen Inhalten: Niedrige TTL (1–5 Minuten) für aktuellere Inhalte
  • Websites mit statischen Inhalten: Höhere TTL (30–60 Minuten) für bessere Performance
  • Echtzeit-Inhalte: Auf 0 setzen, um Caching vollständig zu deaktivieren

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:

  • Admin-Bar: WordPress-Admin-Links sollten immer vollständige Seitenloads auslösen
  • WooCommerce Cart/Checkout: Diese Seiten brauchen oft vollständige Reloads für Session-Management
  • Login-Seiten: Authentifizierung erfordert typischerweise klassische Formularübermittlung
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:

  • das DOM nach Elementen durchsuchen
  • Event-Listener anhängen
  • Komponenten initialisieren (Slider, Lightboxes usw.)

... 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.

Back to top