Wordpress Plugin | Anwender Handbuch

Das co*pilot Promotion Plugin verbindet deine WordPress-Website mit der co*pilot Veranstaltungssoftware. Es zeigt automatisch alle deine Events auf deiner Website an und hält sie immer aktuell.

Wir können leider keinen Support für das Plugin übernehmen.

Version: 1.0.32
Stand: 23. März 2026

Download & Voraussetzungen link

Das Plugin kann hier heruntergeladen werden:

WordPress Promotions Plugin herunterladen

Systemvoraussetzungen link

• WordPress 5.0 oder höher
• PHP 8.0 oder höher (empfohlen: PHP 8.3)
• Zugang zur co*pilot GraphQL API (API-URL + Token)

PHP-Version beim Hoster setzen: Bei einigen Hostern lässt sich die PHP-Version über folgenden Eintrag in der .htaccess setzen:

  FcgidWrapper "/home/httpd/cgi-bin/php83-fcgi-starter.fcgi" .php
  

Was kann das Plugin? link

• Automatischer Import von Events aus co*pilot
• Verschiedene Darstellungen: Event-Listen, Banner, Einzelansicht
• Intelligente Filter: Nach Künstler, Ort, Stadt, Datum und mehr filtern
• Responsive Design: Sieht auf allen Geräten gut aus
• Anpassbare Templates: Gestalte die Darstellung nach deinen Wünschen
• Automatische Updates: Neue Funktionen mit einem Klick installieren
• SEO: Strukturierte Event-Daten (schema.org) für Suchmaschinen

Installation & Einrichtung link

Schritt 1: Plugin installieren link

1. Lade die Plugin-ZIP-Datei herunter
2. Gehe in WordPress zu Plugins → Installieren
3. Klicke auf Plugin hochladen
4. Wähle die ZIP-Datei aus und klicke Jetzt installieren
5. Klicke nach der Installation auf Plugin aktivieren

Schritt 2: WordPress Konfiguration link

Damit der konfigurierte Link auf die Detailseite funktioniert, muss unter Einstellungen → Permalinks (/wp-admin/options-permalink.php) unter Permalink-Struktur “Beitragsname” gewählt werden.

Schritt 3: API-Zugangsdaten einrichten link

Nach der Aktivierung musst du die Verbindung zu co*pilot einrichten:

1. Gehe zu co*pilot → Einstellungen im WordPress-Menü
2. Trage folgende Daten ein:
   • API URL: Die GraphQL-Endpunkt-URL (z.B. https://api.copilot.cloud/graphql)
   • API Token: Dein Zugangstoken
   • Operation Name: Name der GraphQL-Operation (meist PromotionQuery)

Hinweis: Diese Daten erhältst du von deinem co*pilot Administrator. Der Token kann in der Zugangsverwaltung angelegt werden.

Das Plugin verarbeitet die Daten der co*pilot Promotions, welche über die GraphQL Schnittstelle abgerufen werden. Ein Beispiel GraphQL Schema befindet sich im root des Plugins (./promotion.graphql).

Schritt 4: Cronjob einrichten link

Da die co*pilot API durch ein Rate-Limit beschränkt ist, speichert das Plugin die Daten des API Calls in der WordPress Datenbank. Das regelmäßige Aktualisieren der Events muss über einen Cronjob erfolgen.

Option A: Server-Cronjob (empfohlen)

  # Stündliche Aktualisierung
0 * * * * /pfad/zum/script/copilot_cronjob.sh
  

Ein Beispiel-Script und weitere Anweisungen findest du im Source Code des Plugins.

Option B: WordPress Pseudo-Cronjob

Besteht keine Möglichkeit eines server-seitigen Cronjobs (z.B. Shared Hosting), kannst du alternativ den WordPress “pseudo” Cronjob aktivieren:

1. Gehe zu co*pilot → Einstellungen
2. Setze Cronjob auf “WordPress”
3. Speichern

Wichtig: Der WordPress-Cronjob läuft nur, wenn deine Website besucht wird!

Schritt 5: Erste Synchronisation link

1. Gehe zu co*pilot → Einstellungen
2. Klicke auf Jetzt synchronisieren
3. Warte, bis der Import abgeschlossen ist
4. Gehe zu co*pilot → Events um die importierten Events zu sehen

Plugin verwenden link

Es gibt zwei Möglichkeiten, Events auf einer Seite einzubinden:

Methode 1: Gutenberg-Block (empfohlen) link

1. Erstelle oder bearbeite eine Seite
2. Klicke auf + um einen neuen Block hinzuzufügen
3. Suche nach “co*pilot”
4. Wähle den co*pilot Promotion Block
5. Block-Einstellungen (in der rechten Sidebar):
   • Template: Wähle die Darstellung
     • list - Event-Liste mit Filtern (Standard)
     • banner - Banner für einzelnes Event
     • Leer - Einzelnes Event in Detailansicht
   • Pagination: Anzahl der Events pro Seite (Standard: 10)
   • Slug: Event-Slug für Einzelansicht oder Banner
   • Filter-Anzeige: Wähle, welche Filter angezeigt werden sollen
   • Künstler vorauswählen: Filtere die Liste automatisch nach einem Künstler

Methode 2: Shortcode link

Alternativ kannst du auch einen Shortcode verwenden. Füge einen Shortcode-Block hinzu und gib ein:

  [copilot_promotion]
  

⚠️ WICHTIG: Alle Shortcode-Parameter müssen in lowercase geschrieben werden!

Alle Shortcode-Parameter link

Shortcode-Beispiele link

Event-Liste mit mehr Events pro Seite:

  [copilot_promotion pagination="25"]
  

Nur wichtige Filter anzeigen:

  [copilot_promotion showfiltervenue="false" showfiltermonth="false"]
  

Künstler-Seite:

  [copilot_promotion preselectedartist="Max Mustermann" showfilterartist="false"]
  

Event-Banner:

  [copilot_promotion template="banner" slug="konzert-max-mustermann-2025"]
  

Archiv-Seite:

  [copilot_promotion isarchive="true" pagination="50"]
  

Komplett ohne Filter:

  [copilot_promotion showfiltertitle="false" showfilterdate="false" showfilterartist="false" showfiltervenue="false" showfiltercity="false" showfiltermonth="false"]
  

Verschiedene Darstellungen link

1. Event-Liste (Template: list) link

Die Standard-Darstellung zeigt eine Liste aller kommenden Events mit Filtern, Pagination und responsivem Grid-Layout.

  [copilot_promotion template="list" pagination="10"]
  

2. Event-Banner (Template: banner) link

Zeigt ein einzelnes Event als großes Banner mit Hintergrundbild. Optional mit Gesichtserkennung.

  [copilot_promotion template="banner" slug="event-slug"]
  

3. Einzelnes Event (Detailansicht) link

Zeigt alle Details zu einem Event (Bilder, Ticketlinks, Venue, Line-Up).

  [copilot_promotion slug="event-slug"]
  

4. Archiv (vergangene Events) link

  [copilot_promotion isarchive="true"]
  

Filter-System link

Das Plugin bietet verschiedene Filter, um Events zu finden. Alle Filter sind serverseitig und damit sehr schnell.

Verfügbare Filter link

1. Textsuche (Titel/Künstler) - Freie Suche nach Event-Titel oder Künstlername
2. Datumsfilter - Zeige nur Events ab einem bestimmten Datum
3. Künstler-Dropdown - Filtere nach einem bestimmten Künstler (zeigt alle Künstler aus dem LineUp)
4. Venue-Dropdown - Filtere nach einem bestimmten Veranstaltungsort
5. Stadt-Dropdown - Filtere nach einer bestimmten Stadt
6. Monats-Dropdown - Zeige nur Events aus einem bestimmten Monat

Filter kombinieren link

Du kannst mehrere Filter gleichzeitig verwenden. Alle aktiven Filter werden in der URL gespeichert und können geteilt oder als Lesezeichen gespeichert werden:

  /veranstaltungen/?filter_artist=Max+Mustermann&filter_month=2025-12
  

Filter zurücksetzen link

Sobald du Filter gesetzt hast, erscheint ein Reset-Button (⟲). Bei vordefinierten Filtern wird nur auf die Vorauswahl zurückgesetzt.

Vordefinierter Künstler-Filter link

Du kannst eine Seite erstellen, die automatisch nach einem Künstler gefiltert ist. Wähle dazu im Block den Künstler unter “Künstler vorauswählen” oder verwende den Shortcode:

  [copilot_promotion preselectedartist="Max Mustermann" showfilterartist="false"]
  

Filter ein-/ausblenden link

In den Block-Einstellungen kannst du unter “Filter-Anzeige” jeden Filter einzeln ein- oder ausschalten.

Templates link

Das Plugin verwendet Handlebars-Templates für die Darstellung. Auf Basis dieser Vorlagen und den Event-Daten wird die Ausgabe generiert. Daten werden mittels Platzhalter übergeben, die in {{ }} eingeschlossen sind. In der Ausgabe steht Bootstrap 5 zur Verfügung.

Template-Editor link

1. Gehe zu co*pilot → Templates im WordPress-Menü
2. Wähle ein Template zum Bearbeiten:
   • events.html - Event-Liste (Daten sind ein Array, iteriere mit {{#each .}}...{{/each}})
   • singleEvent.html - Einzelne Event-Ansicht (Daten sind ein einzelnes Event-Objekt)
   • banner.html - Event-Banner (Daten sind ein einzelnes Event-Objekt)

Template-Priorität: Die Templates werden in folgender Reihenfolge gesucht:

1. In der Datenbank gespeichert (über Template-Editor)
2. src/custom/templates/[name].html (Custom Templates, überleben Updates)
3. src/templates/[name].html (Standard-Templates)

Template zurücksetzen: Gehe zu co*pilot → Templates und klicke auf Template zurücksetzen.

Verfügbare Event-Daten link

Folgende Daten stehen in den Templates pro Event zur Verfügung:

  {
  slug: string            // URL-Slug des Events
  title: string           // Titel
  subtitle?: string       // Untertitel
  start: string           // Startdatum/-zeit (ISO Date)
  end?: string            // Enddatum/-zeit
  doors?: string          // Einlass-Zeit
  description?: string    // Beschreibung (Markdown/HTML)
  category?: string       // Kategorie (z.B. "Live", "Party")
  soldOut: boolean         // Ob ausverkauft
  status?: string         // "scheduled", "postponed", "rescheduled", "cancelled"
  presaleLink?: string    // Link zum Ticketkauf
  presaleInfo?: string    // Vorverkaufs-Info (Markdown/HTML)
  boxOfficeInfo?: string  // Abendkassen-Info (Markdown/HTML)

  artist?: {              // Erster Künstler
    name: string
    program?: string
    description?: string
  }
  lineUps?: [{            // Alle Künstler im LineUp
    name: string
    program?: string
    description?: string
    origin?: string
  }]
  room?: {                // Veranstaltungsraum
    name: string
    location: {
      name: string        // Venue-Name
      address: {
        street: string
        zip: string
        city: string
      }
    }
  }
  wordpressImages?: {     // WordPress-Bilder (Ausgabe über wpImage Helper)
    eventImage?: ImageData
    eventBanner?: ImageData
    artistImage?: ImageData
  }
  organizer?: { name, homepage?, logo? }
  sponsor?: { name, homepage?, logo? }
  youtube?: string
  instagram?: string
  facebook?: string
  soundcloud?: string
  rawEvent?: any          // Rohdaten (für Spezialfelder)
}
  

Im rawEvent stehen alle ungeparsten Daten des API-Requests zur Verfügung. Im singleEvent-Template gibt es zusätzlich navigation.prev und navigation.next für die Event-Navigation.

Tipp: Daten in der Konsole anzeigen link

Über den Handlebars Helper log kannst du dir ein Datenobjekt in der JavaScript-Konsole anzeigen lassen:

  {{ log this.rawEvent }}
  

Handlebars-Helper link

Zu den Standard Handlebars Helpern (if, each, unless, log) wurden folgende zusätzliche Helper implementiert:

Custom Parser (für Entwickler) link

Soll ein alternatives co*pilot Promotions Schema implementiert werden, kann im Verzeichnis src/custom/eventParser.ts ein Custom Parser angelegt werden:

  import { EventFromDB, ParsedRawEvent } from "../parser/promotionApiTypes";

export function parseEvent(event: EventFromDB) {
  try {
    const e: ParsedRawEvent = JSON.parse(event.rawEvent);

    const parsedEvent: any = {
      slug: event.slug,
      title: e.title?.value?.label,
      // ... weitere Felder
    };
    return parsedEvent;
  } catch (e) {
    console.error("Failed to parse event:", e);
    return null;
  }
}
  

Templates mit KI erstellen link

Im Plugin-Verzeichnis befindet sich die Datei TEMPLATE-KI-PROMPT.md mit einem fertig formulierten Prompt. Damit können deine Kunden sich mithilfe von KI-Tools (z.B. ChatGPT, Claude) eigene Templates generieren lassen. Einfach den Prompt kopieren und am Ende die gewünschte Beschreibung einfügen.

Bilder & Gesichtserkennung link

Beim Import und der Aktualisierung speichert das Plugin alle Bilder in der WordPress Mediathek. Falls du Änderungen an einem Bild vornimmst, beachte, dass das Bild beim Aktualisieren der Events wieder überschrieben wird, sollte sich die URL geändert haben.

Folgende Bilder stehen im Event-Objekt zur Verfügung:

1. Event-Bild: wordpressImages.eventImage
2. Banner: wordpressImages.eventBanner
3. Künstler-Bild: wordpressImages.artistImage (Bild des 1. Künstlers)

Bilder werden über den wpImage Helper ausgegeben:

  // Mittlere Auflösung des Event-Bildes
{{wpImage wordpressImages.eventImage "MEDIUM"}}

// Hohe Auflösung des Künstler-Bildes
{{wpImage wordpressImages.artistImage "LARGE"}}

// Verfügbare Größen: THUMBNAIL, MEDIUM, MEDIUM_LARGE, LARGE, FULL
  

Gesichtserkennung link

Für Bannerbilder kann über die Google Vision API eine Gesichtserkennung erfolgen. Hierfür musst du:

1. Einen Google API Key anlegen (1000 Abfragen pro Monat kostenlos)
2. Den Key in den Plugin-Einstellungen eintragen
3. Die Gesichtserkennung auf der Seite einschalten, wo du das Banner einbindest

SEO link

Auf Event-Detailseiten werden automatisch strukturierte Eventdaten nach schema.org/Event ausgegeben. Das verbessert die Darstellung in Suchmaschinen (Rich Results).

Die Inhalte können hier geprüft werden: Google Rich Results Test

Updates link

Das Plugin kann in den Settings aktualisiert werden. Wenn ein Update verfügbar ist, siehst du eine Benachrichtigung in der Plugin-Liste und in den Einstellungen.

Update installieren link

Automatisch (empfohlen):

1. Gehe zu co*pilot → Einstellungen
2. Klicke auf “Update installieren”
3. Das Plugin wird automatisch neu aktiviert

Manuell: Altes Plugin deaktivieren → löschen → neue Version installieren → aktivieren.

Was passiert beim Update? link

• ✅ Einstellungen bleiben erhalten
• ✅ Angepasste Templates bleiben erhalten (im Template-Editor)
• ✅ Custom Templates bleiben erhalten (im custom/ Ordner)
• ✅ Event-Daten bleiben erhalten
• ⚠️ Änderungen in Plugin-Dateien gehen verloren

Häufig gestellte Fragen (FAQ) link

Allgemein link

Q: Wie oft werden die Events aktualisiert?
A: Das hängt von deinem Cronjob ab. Empfohlen wird stündlich. Du kannst auch manuell synchronisieren unter co*pilot → Einstellungen.

Q: Kann ich mehrere Event-Listen auf einer Seite haben?
A: Ja! Du kannst beliebig viele Blöcke oder Shortcodes auf einer Seite verwenden.

Q: Werden auch vergangene Events gespeichert?
A: Ja, alle Events werden gespeichert. Mit dem Archiv-Modus kannst du auch vergangene Events anzeigen.

Technisch link

Q: Meine Events werden nicht angezeigt. Was tun?
A: Prüfe: 1) Sind die API-Zugangsdaten korrekt? 2) Wurde die erste Synchronisation durchgeführt? 3) Gibt es Events unter co*pilot → Events? 4) Sind die Filter zu restriktiv?

Q: Der Cronjob funktioniert nicht.
A: Prüfe die Cronjob-Konfiguration, teste die manuelle Synchronisation, oder verwende alternativ den WordPress Pseudo-Cronjob.

Q: Können Sonderzeichen in Künstlernamen Probleme machen?
A: Nein, das Plugin behandelt Sonderzeichen korrekt (z.B. “AC/DC”, “Frank Turner & The Sleeping Souls”).

Filter & Suche link

Q: Warum sehe ich bestimmte Künstler/Venues nicht im Dropdown?
A: Die Dropdowns zeigen nur Künstler/Venues, die Events in der Zukunft haben.

Q: Was ist der Unterschied zwischen Textsuche und Künstler-Dropdown?
A: Textsuche: Freie Suche in Titel UND Künstlername. Künstler-Dropdown: Exakte Filterung nach einem bestimmten Künstler.

Templates & Design link

Q: Werden meine Template-Änderungen bei Updates überschrieben?
A: Nein! Templates im Template-Editor werden in der Datenbank gespeichert und bleiben erhalten.

Q: Kann ich das Design anpassen?
A: Ja! Bearbeite die Templates unter co*pilot → Templates oder erstelle eigene CSS-Regeln in deinem Theme.

Weitere Informationen link

• co*pilot Allgemein: https://ov2b.de/
• GraphQL API: /docs/graphql/

ov2b GmbH
Die Organisations-Software für Locations, Veranstalter:innen und Agenturen zur Vernetzung der Kulturbranche.

Es wird kein offizieller Support angeboten. Diese Dokumentation soll bei der Verwendung des Plugins helfen.

*Version: 1.0.32
Letzte Aktualisierung: 23. März 2026*