JPKCom DB
Auf GitHub ansehen (öffnet in neuem Tab)

JPKCom ACF References — Anleitung & Tipps

Referenz-Galerie mit Filterfunktion auf Basis von ACF Pro — Installation, Custom Post Types, Shortcodes, Layouts und Praxis-Tipps mit JPKCom ACF References.

JPKCom ACF References ist ein System für Referenz-Galerien mit Filterfunktion auf Basis von Advanced Custom Fields Pro. Es bringt drei Custom Post Types (References, Locations, Customers), Bildergalerien mit Lightbox, clientseitige Filter, mehrere Layouts und Shortcodes mit — gedacht für Portfolios, Case Studies und Projekt-Showcases.

Anleitung

Voraussetzungen

Zwingend erforderlich:

Optional: WPML (öffnet in neuem Tab) für mehrsprachige Referenzen (deutsche Übersetzungen sind enthalten).

Installation

  1. Lade die aktuelle Release-ZIP von der GitHub-Releases-Seite (öffnet in neuem Tab) herunter.
  2. Im Admin-Bereich: Plugins → Installieren → Plugin hochladen, ZIP wählen, Jetzt installieren, dann Aktivieren.
  3. Stelle sicher, dass ACF Pro und ACF Quick Edit Fields aktiv sind.

Alternativ per FTP nach /wp-content/plugins/ hochladen oder für die Entwicklung direkt klonen:

cd /pfad/zu/wordpress/wp-content/plugins/
git clone https://github.com/JPKCom/jpkcom-acf-references.git

Auf Multisite ist das Plugin netzwerkfähig (Netzwerk-Admin → Plugins → Netzwerkweit aktivieren).

Erste Schritte

Nach der Aktivierung erscheinen die Menüpunkte References, Locations und Customers. Empfohlener Ablauf:

  1. Lege unter Locations → Erstellen einen Standort an.
  2. Lege unter Customers → Erstellen einen Kunden an.
  3. Erstelle unter References → Erstellen eine Referenz, fülle die ACF-Felder (Typ, Standort, Kunde, Galerie) und weise rechts die Taxonomien zu.
  4. Lade Bilder in die ACF-Gallery-Feld und veröffentliche — die Referenz erscheint im Archiv unter /references/.

Referenzen ausgeben

Per Shortcode (alle Attribute optional):

[jpkcom_acf_references_list type="1,5" customer="6,8" location="1,3,7,11" limit="10" sort="DSC" layout="cards" title="Referenzen"]

customer und location erwarten Post-IDs (im Admin in der URL sichtbar, post=123). Mit interaktiven Filter-Dropdowns:

[jpkcom_acf_references_list show_filters="true" show_filter="0,1,2" reset_button="true" layout="cards"]

Taxonomien lassen sich separat ausgeben:

[jpkcom_acf_references_types id="3,7,21"]
[jpkcom_acf_references_filter_1 id="1,5"]
[jpkcom_acf_references_filter_2 id="2,8"]

Alternativ erreichst du das Archiv direkt unter /references/ oder baust eigene Ausgaben per WP_Query mit post_type => 'reference'.

Referenzen als Daten: die Abilities API

Seit Version 1.2.0 registriert das Plugin drei nur lesende Abilities. Die Abilities API ist ein WordPress-Kernregister maschinenlesbarer Fähigkeiten — KI-Assistenten, MCP-Clients und REST-Automatisierung lesen deine Referenzen damit als strukturierte Daten, statt die Seite auszulesen:

Ability Antwort
jpkcom-acf-references/list-filters welche Referenz-Typen, Kunden, Standorte und Taxonomie-Terme es auf dieser Site gibt
jpkcom-acf-references/query-references eine gefilterte, seitenweise Liste von Referenzen
jpkcom-acf-references/get-reference eine Referenz vollständig

Erreichbar sind sie unter /wp-json/wp-abilities/v1/; weil sie nur lesen, antworten sie auf GET. Es braucht einen angemeldeten Benutzer mit der Fähigkeit read — das schließt Abonnenten ein.

Zwei Punkte, die das Verhalten prägen:

  • Zurück kommen nur Referenzen, die auch dein eigenes Listing zeigt — nach derselben Regel, die [jpkcom_acf_references_list] anwendet. Kurzbeschreibung und Bildergalerie gibt es nur für eine Referenz, deren Seite ein Besucher auch öffnen könnte: Eine Referenz, die auf eine externe URL umleitet, und eine, deren Ablaufdatum vorbei ist, haben keine öffentliche Detailseite. Für sie werden diese Felder zurückgehalten und der Grund steht in der Antwort.
  • Filterst du nach einem Wert, den es auf dieser Site nicht gibt, kommen keine Referenzen zurück und der Wert wird unter unknown benannt — statt still die ganze Liste auszugeben. Ein Filter, der nur teilweise erkennbar ist, grenzt weiter nach dem erkannten Teil ein.

Komplett abschalten in der wp-config.php:

define( 'JPKCOM_ACFREFERENCES_ABILITIES', false );

Über jpkcom_acf_references_ability_capability hebst du die nötige Fähigkeit an, über jpkcom_acf_references_ability_meta steuerst du, wie die Abilities nach außen sichtbar sind (REST-Route, MCP-Freigabe, Annotationen).

Tipps & Tricks

  • Drei Layouts wählen: layout="list" (Standard, kompakt), layout="cards" (Grid mit 16:9-Bildern, Hover-Zoom) oder layout="images" (Full-Bleed-Overlay-Karten im 4:3-Format). Alle respektieren prefers-reduced-motion.
  • Interaktives Filtern ohne Reload: Mit show_filters="true" blendest du Dropdowns je Taxonomie ein. Innerhalb eines Filters gilt ODER-, zwischen Filtern UND-Logik; ein „Reset all filters"-Button räumt auf. Die Filterung läuft rein clientseitig per Vanilla-JS (kein AJAX, kein jQuery). Für die Dropdowns muss Bootstrap-5-JavaScript geladen sein.
  • Shortcode-Generator nutzen: Unter References → Shortcodes erzeugst du Shortcodes über ein Formular mit Live-Vorschau und Copy-to-Clipboard.
  • Bildergalerie mit Lightbox: Das ACF-Gallery-Feld einer Referenz erzeugt auf der Einzelseite automatisch eine Thumbnail-Grid mit Lightbox-Modal (Vor/Zurück, Pfeiltasten, Escape, Bildzähler).
  • Archiv abschalten/umleiten: Unter References → Options kannst du das Archiv /references/ deaktivieren und per HTTP-307 umleiten; Einzelseiten bleiben erreichbar.
  • Templates überschreiben (Reihenfolge der Priorität): Child-Theme (dein-child-theme/jpkcom-acf-references/), Parent-Theme (dein-theme/jpkcom-acf-references/) oder MU-Plugin (mu-plugins/jpkcom-acf-references-overrides/templates/).
  • Pfade programmatisch erweitern: Über die Filter jpkcom_acf_references_template_paths bzw. jpkcom_acfreferences_file_paths lassen sich eigene Verzeichnisse voranstellen; jpkcom_acf_references_final_template erlaubt das dynamische Überschreiben des finalen Templates.
  • ACF-Felder mit Bootstrap-5-Markup rendern: jpkcom_render_acf_fields() gibt alle ACF-Felder eines Beitrags aus; Template-Teile holst du mit jpkcom_acf_references_get_template_part( 'partials/reference/customer' ).
  • Mehrsprachig mit WPML: Über wpml-config.xml sind References, Locations, Customers und Taxonomien übersetzbar; die Felder tragen passende Strategien (translate/copy/copy-once). Auf Version 1.1.0 aktualisieren, wenn du mehrsprachig arbeitest: Bis dahin lieferten die Shortcode-Filter in jeder Sekundärsprache nichts. Ein Shortcode trägt die Term-ID der Ausgangssprache, gesucht wurde sie aber in Übersetzungen, deren Metadaten die übersetzte ID halten. Seit 1.1.0 filtern die drei Taxonomie-Filter über tax_query statt über ein meta_query mit LIKE auf den serialisierten ACF-Werten — das ist zugleich deutlich schneller, weil ein führender Platzhalter keinen Index nutzen kann.
  • Nicht-numerische Filterwerte: type, filter_1 und filter_2 erwarten Term-IDs. Steht dort etwas anderes, wird seit 1.1.0 kein Filter gesetzt, statt eines Filters, der auf nichts passt — ein Tippfehler liefert also die ungefilterte Liste statt einer leeren Seite.
  • Updates & Sicherheit: Das Plugin aktualisiert sich sicher über GitHub mit SHA256-Prüfsumme; Hinweise erscheinen unter Dashboard → Aktualisierungen und auf der Plugins-Seite.

Weiterführende Informationen