JPKCom DB
Auf GitHub ansehen

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 für mehrsprachige Referenzen (deutsche Übersetzungen sind enthalten).

Installation

  1. Lade die aktuelle Release-ZIP von der GitHub-Releases-Seite 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'.

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