WordPress-Plugin

Das petoffice-Plugin bindet die Anzeigen aus der Homepage-Integration in eine WordPress-Seite ein. Es ist bewusst schlank gehalten: petoffice liefert die fertig aufbereiteten Inhalte, und das Plugin entscheidet, wo diese auf deiner Seite erscheinen, wie die Adressen aufgebaut sind und ob optionale Layout-Stile, ein Cache oder eine Fehlersuche aktiv sind.

Der erste Teil dieses Artikels richtet sich an alle Anwender, die das Plugin installieren und einrichten. Der Abschnitt Für Entwickler und Agenturen am Ende geht auf technische Optionen ein, die nur für die Feinanpassung durch Entwickler oder die betreuende Agentur relevant sind.

Systemanforderungen

Das Plugin setzt eine aktuelle WordPress-Installation mit dem Block-Editor (Gutenberg) voraus:

• WordPress ab Version 6.6. Die mitgelieferten Editor-Blöcke nutzen Bestandteile des Block-Editors, die WordPress erst ab dieser Version bereitstellt.
• PHP in einer von WordPress 6.6 unterstützten Version, also mindestens 7.2. Empfohlen ist PHP 7.4 oder neuer (8.x).
• Aktivierte „schöne” Permalinks, damit die suchmaschinenfreundlichen Adressen für Listen- und Profilseiten funktionieren.

Bezugsquelle und Installation

Das Plugin wird dir als ZIP-Datei zum Download in den petoffice-Einstellungen unter Homepage-Integration bereitgestellt, sobald du die Erweiterung gebucht hast.

Die Installation läuft wie bei jedem WordPress-Plugin: Lade die ZIP-Datei im WordPress-Admin-Bereich unter Plugins → Installieren → Plugin hochladen hoch und aktiviere das Plugin anschließend. Danach erscheint ein neuer Eintrag petoffice unter Einstellungen.

Einrichtung

Öffne Einstellungen → petoffice im WordPress-Admin-Bereich.

Verbindung zu petoffice

Trage als Verbindungsadresse deine Homepage-Domain ein. Diese findest du in petoffice unter Einstellungen → Homepage-Integration im Abschnitt „Domain”. Gib die Adresse ohne abschließenden Schrägstrich ein. Das Plugin ergänzt die benötigten Pfade selbst.

Seiten festlegen

Das Plugin arbeitet mit zwei Seiten:

• einer Listenseite, die die Tierliste enthält,
• einer Profilseite als Vorlage für die Detailansicht eines einzelnen Tieres.

In den Einstellungen wählst du dafür bestehende WordPress-Seiten aus. Eine Einrichtungshilfe kann die beiden Seiten auch automatisch anlegen: eine Seite „Tiere” mit dem Listenblock und eine Seite „Tierprofil” mit der üblichen Abfolge der Profil-Blöcke. Die erzeugte Profilseite wird aus Menüs und Seitenlisten ausgeblendet, weil sie ohne ein konkretes Tier nicht sinnvoll aufrufbar ist. Alle Tiere teilen sich diese eine Vorlage, sodass jede Profilseite gleich aussieht.

Inhalte einbinden

Gutenberg-Blöcke

Das Plugin stellt fertige Blöcke für den Standard-Editor (Gutenberg) bereit. Auf der Listenseite verwendest du den Block Tierliste, auf der Profilseite die Profil-Blöcke:

• Tiersteckbrief: Titel
• Tiersteckbrief: Bild
• Tiersteckbrief: Galerie
• Tiersteckbrief: Videos
• Tiersteckbrief: Zusatzfelder
• Tiersteckbrief: Beschreibungstext
• Tiersteckbrief: Bewerber-Button

Der Block Tierliste bietet drei Einstellungen, die du je Liste einzeln änderst:

• Tierart (zum Beispiel „Hund” oder „Katze”). Ohne Angabe wird „Katze” verwendet.
• Tag, um die Liste fest auf eine Gruppe einzugrenzen.
• Tags anzeigen, um die anklickbaren Tag-Filter ein- oder auszublenden.

Eine Tierliste zeigt immer genau eine Tierart. Eine gemischte Liste über alle Tierarten hinweg ist nicht vorgesehen, und ein leeres Tierart-Feld führt nicht zu einer solchen Mischung, sondern fällt auf „Katze” zurück. Wenn du mehrere Tierarten anbieten möchtest, lege für jede Tierart einen eigenen Tierliste-Block an, zum Beispiel mehrere Blöcke untereinander auf einer Seite (je einen mit „Hund”, „Katze” und so weiter) oder eine eigene Listenseite pro Tierart.

Jedes Tier in der Liste verlinkt automatisch auf die zugehörige Profilseite. Im Editor zeigen die Profil-Blöcke eine realistische Vorschau anhand eines Beispieltiers.

Shortcodes für andere Seitenbaukästen

Nutzt du keinen Gutenberg-Editor, sondern einen Seitenbaukasten wie Elementor, Divi oder Bricks, dienen Shortcodes als Bridge. Fast jeder Baukasten bietet ein Shortcode-Element. Für die Tierliste verwendest du:

[petoffice_pet_list]

mit optionalen Angaben:

[petoffice_pet_list species="Katze" tag="Paerchen" show_tags="true"]

Für die Profilseite stehen passende Shortcodes bereit:

[petoffice_pet_profile_title]
[petoffice_pet_profile_image]
[petoffice_pet_profile_gallery]
[petoffice_pet_profile_videos]
[petoffice_pet_profile_extra]
[petoffice_pet_profile_description]
[petoffice_pet_profile_apply_button]

Die Profil-Shortcodes funktionieren nur auf der konfigurierten Profilseite beziehungsweise in einer Vorlage, die über deren Adresse aufgerufen wird, weil sie das aktuelle Tier aus der Adresse ableiten.

Eigene Bausteine speziell für einzelne Seitenbaukästen bietet das Plugin bewusst nicht an, um die Integration wartbar zu halten. Der Weg über Shortcodes deckt diese Fälle ab.

Adressen der Seiten

Bei aktivierten Permalinks erzeugt das Plugin suchmaschinenfreundliche Adressen.

Für die Listenseite werden folgende Formen unterstützt:

/{listenseite}/
/{listenseite}/{tierart}/
/{listenseite}/{tierart}/{tag}/

Für die Profilseite:

/{profilseite}/{id}/{name}/

Maßgeblich für das angezeigte Tier ist dabei die ID, der Name im Pfad ist nur kosmetisch. Wird die Profilseite ohne eine Tier-ID aufgerufen, liefert das Plugin eine 404-Seite aus, statt eine leere Profilseite anzuzeigen.

Auf Profilseiten ergänzt das Plugin außerdem grundlegende SEO-Angaben wie Titel, Meta-Beschreibung, kanonische Adresse und Open-Graph-Daten anhand der Inhalte des Tieres.

Gestaltung und Design

Die Inhalte kommen mit semantischen CSS-Klassen, die alle mit po- beginnen, zum Beispiel po-pet-list, po-pet, po-pet-profile__title oder po-image-gallery. Eine vollständige Übersicht findest du in der API-Dokumentation. Über diese Klassen passt du das Aussehen an dein Theme an. Weil sie über Updates hinweg stabil bleiben, sind sie die richtige Stelle für Designanpassungen durch dich oder die betreuende Agentur.

Für die grundlegende Darstellung bietet das Plugin zwei Stil-Modi:

• Minimal (Voreinstellung): Das Plugin liefert zurückhaltende Layout-Stile mit, etwa ein vierspaltiges Listenraster, quadratisch zugeschnittene Vorschaubilder, Tag-Pillen mit Hervorhebung der Auswahl und eine schlichte Gestaltung des Bewerber-Buttons. Die Ausgabe wird dabei in einen Bereich mit der Klasse po-minimal eingefasst, und alle Plugin-Stile gelten ausschließlich innerhalb dieses Bereichs.
• Keine: Das Plugin liefert keine eigenen Layout-Stile aus. Die Darstellung überlässt es vollständig deinem Theme und den vom System mitgelieferten Bausteinen.

Das Plugin gibt bewusst kein eigenes Markendesign vor. Es liefert nur Layout- und Bedienhilfen. Für das Erscheinungsbild deines Vereins überschreibst oder erweiterst du die po--Klassen in deinem Theme.

Hinweis zu YouTube-Videos

Die Videos werden über die datenschutzfreundliche Domain youtube-nocookie.com eingebunden. Trotzdem bleibt es deine Verantwortung als Seitenbetreiber, zu entscheiden, ob YouTube-Einbettungen für deine Seite und deine rechtliche Situation passen. Ein gegebenenfalls nötiger Cookie-Hinweis, eine Einwilligungslösung und die passenden Datenschutzangaben müssen in WordPress beziehungsweise im Theme oder Seitenbaukasten eingerichtet werden. Lässt sich das nicht sicherstellen, solltest du auf YouTube-Videos verzichten.

Für Entwickler und Agenturen

Die folgenden Optionen sind für die technische Feinanpassung gedacht. Für die normale Nutzung sind sie nicht erforderlich.

Cache

Optional cacht das Plugin erfolgreiche Antworten der Schnittstelle als WordPress-Transients. Im Auslieferungszustand ist das deaktiviert. Aktiviert beträgt die Standard-Cache-Dauer (TTL) 300 Sekunden. Fehlerantworten des Backends werden unabhängig davon kurz im Negative Cache gehalten (Standard 30 Sekunden), damit nicht jeder Besucher auf dieselbe langsame oder fehlschlagende Anfrage wartet. HTTP-404-Antworten landen nicht im Negative Cache.

Cache-Dauer und Verhalten lassen sich über Filter steuern:

add_filter('petoffice_integration_cache_ttl', fn ($ttl, $url) => 600, 10, 2);
add_filter('petoffice_integration_cache_enabled', fn ($enabled) => true);
add_filter('petoffice_integration_negative_cache_ttl', fn ($ttl, $url, $error) => 30, 10, 3);
add_filter('petoffice_integration_request_timeout', fn ($timeout) => 4);

Das Zeitlimit für Anfragen an die Schnittstelle liegt standardmäßig bei 4 Sekunden.

Fehlersuche (Debug)

Ist die Fehlersuche aktiviert, gibt das Plugin die rohen Antworten der Schnittstelle direkt auf Listen- und Profilseiten aus. Diese Ausgabe sehen ausschließlich angemeldete Benutzer mit der Berechtigung manage_options, niemals öffentliche Besucher. Sie ist in einen Bereich mit der Klasse petoffice-integration-debug eingefasst und lässt sich auch per Filter erzwingen:

add_filter('petoffice_integration_debug_enabled', fn ($enabled) => true);

Umgang mit HTML

Listen- und Profil-Bausteine werden vor der Ausgabe über wp_kses() bereinigt. Die Galerie- und Video-Bausteine werden dagegen unverändert ausgegeben, weil sie die für ihre Lightbox nötigen Skripte, Stile und data-*-Attribute enthalten. Die Liste der erlaubten HTML-Elemente lässt sich erweitern:

add_filter('petoffice_integration_allowed_api_html', function ($allowed) {
    $allowed['div']['data-example'] = true;
    return $allowed;
});

Fehlerverhalten

Ist keine Verbindungsadresse hinterlegt, sehen Administratoren einen Konfigurationshinweis. Antwortet die Schnittstelle mit 404, erscheint der Hinweis, dass die Homepage-Integration für die Organisation nicht aktiv ist. Andere Fehler führen zu einer entsprechenden Statusmeldung. Öffentliche Besucher sehen niemals technische Fehlerdetails.

Filter im Überblick

petoffice_integration_cache_ttl
petoffice_integration_cache_enabled
petoffice_integration_negative_cache_ttl
petoffice_integration_negative_cache_enabled
petoffice_integration_request_timeout
petoffice_integration_allowed_query_params
petoffice_integration_debug_enabled
petoffice_integration_allowed_api_html

Setze diese Filter aus deinem Theme oder einem kleinen seitenspezifischen Plugin ein, wenn du ein Verhalten brauchst, das nicht zur globalen Voreinstellung werden soll.