# 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:

1. **Fängt Link-Klicks ab** – Erfasst Navigationsereignisse, bevor der Browser sie verarbeitet  
2. **Lädt Seiten per AJAX** – Lädt neue Seiteninhalte im Hintergrund über die Fetch API  
3. **Ersetzt Inhalte dynamisch** – Tauscht nur die festgelegten Inhalts-Container aus und behält den Rest des DOM bei  
4. **Animiert Übergänge** – Wendet während des Übergangs CSS-Klassen für flüssige visuelle Effekte an  
5. **Verwaltet den Browser-Verlauf** – Nutzt die History API, um korrekte URL-Zustände sowie Zurück-/Vorwärtsnavigation zu erhalten  

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

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

```php
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  

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

```js
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  

```js
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:

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

Und den `animationSelector` im Skript anpassen:

```js
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:

```css
/* 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:

```js
debug: true,
```

4. Klicken Sie auf Links und beobachten Sie die Konsolenmeldungen zum Übergangsablauf

---

## 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:

```js
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

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

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

#### Methode 2: Auf ein benutzerdefiniertes Event hören

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

#### Methode 3: Den `onPageView`-Callback verwenden

Im Objekt `SWUP_CONFIG`:

```js
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`:

```js
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:

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

### Weitere Analytics-Plattformen

Fügen Sie ähnlichen Code in `onPageView` ein:

```js
// 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:

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

---

## Performance-Optimierung

### Empfohlene Produktionseinstellungen

```js
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`:

```html
<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:

```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:

```js
// 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:

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