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

Source: https://www.jpkc.com/db/guides/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:

- WordPress **6.9+** und PHP **8.3+**
- [Advanced Custom Fields Pro](https://www.advancedcustomfields.com/) (v6.0+)
- [ACF Quick Edit Fields](https://wordpress.org/plugins/acf-quickedit-fields/) (für Inline-Bearbeitung)

Optional: [WPML](https://wpml.org/) für mehrsprachige Referenzen (deutsche Übersetzungen sind enthalten).

### Installation

1. Lade die aktuelle Release-ZIP von der [GitHub-Releases-Seite](https://github.com/JPKCom/jpkcom-acf-references/releases) 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:

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

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

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

Taxonomien lassen sich separat ausgeben:

```text
[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

- Quellcode auf GitHub: <https://github.com/JPKCom/jpkcom-acf-references>
- API-Dokumentation (PHPDoc): <https://jpkcom.github.io/jpkcom-acf-references/docs/>
- Voraussetzungen: [ACF Pro](https://www.advancedcustomfields.com/), [ACF Quick Edit Fields](https://wordpress.org/plugins/acf-quickedit-fields/)
- [Changelog dieses Projekts](https://www.jpkc.com/db/changelog/jpkcom-acf-references/)