NXT ACF Field Display

Ein flexibler Gutenberg Block zur Ausgabe von Advanced Custom Fields (ACF) Feldern im WordPress Block Editor.

Features

• 🎯 Flexible Feldauswahl: Zeigt beliebige ACF Felder dynamisch an
• 🔄 Query Loop Support: Funktioniert nahtlos in WordPress Query Loops
• 📋 Repeater & Group Support: Ausgabe von komplexen Feldtypen mit Custom Templates
• 🖼️ Gallery Integration: Native WordPress Gallery Block Struktur mit Lightbox
• 🎨 Block Supports: Typography, Spacing, Color, Alignment
• 🔧 Customizable: Prefix/Postfix, Custom Templates, Raw HTML Option

Unterstützte Feldtypen

• Text, Textarea, WYSIWYG
• Number, Email, URL
• Image, File, Gallery
• Repeater, Group
• Relationship, Post Object
• Select, Checkbox, Radio
• Link
• True/False
• und mehr...

Anforderungen

• WordPress 6.0 oder höher
• PHP 7.4 oder höher
• Advanced Custom Fields Pro (erforderlich)

Installation

1. Laden Sie den Plugin-Ordner in /wp-content/plugins/ hoch
2. Aktivieren Sie das Plugin über das 'Plugins' Menü in WordPress
3. Stellen Sie sicher, dass ACF Pro installiert und aktiviert ist
4. Der Block ist nun im Block Inserter verfügbar

Verwendung

Basis-Verwendung

1. Fügen Sie den "ACF Field Display" Block in den Editor ein
2. Wählen Sie das gewünschte ACF Feld aus
3. Der Feldwert wird automatisch angezeigt

In Query Loops

Der Block erkennt automatisch den aktuellen Post-Kontext in Query Loops und zeigt den entsprechenden Feldwert an.

Repeater-Felder

Einfache Liste (ein Sub-Field)

1. Wählen Sie Ihr Repeater-Feld aus
2. Setzen Sie "Repeater Template Typ" auf "Einfache Liste"
3. Geben Sie den Namen des Sub-Fields ein (z.B. rr_desc)
4. Wählen Sie Wrapper und Item Tags

Benutzerdefinierte Templates

1. Wählen Sie Ihr Repeater-Feld aus
2. Setzen Sie "Repeater Template Typ" auf "Benutzerdefiniertes Template"
3. Verwenden Sie {{field_name}} als Platzhalter

Beispiel:

<strong>{{title}}</strong>: {{description}}

Gallery-Felder

Der Block verwendet die native WordPress Gallery Block Struktur:

• Spaltenanzahl: 2-6 Spalten
• Thumbnail-Größe: WordPress Bildgrößen
• Lightbox: Ein/Aus
• Bildunterschriften: Ein/Aus

Erweiterte Optionen

• Raw HTML: Gibt ungefilterten HTML-Code aus (Vorsicht bei User-Generated Content)
• Prefix/Postfix: Fügt HTML vor/nach dem Feldwert ein
• Custom Post ID: Überschreibt den aktuellen Post-Kontext

Block Supports

Der Block unterstützt alle wichtigen WordPress Block Supports:

• Typography: Font Size, Line Height, Font Weight, etc.
• Spacing: Margin, Padding
• Color: Text Color, Background Color
• Alignment: Text Alignment, Block Alignment

Template-Overrides

Granulare Template-Kontrolle

Das Plugin unterstützt granulare Template-Overrides - jeder Feldtyp hat sein eigenes Template, das individuell überschrieben werden kann.

Verfügbare Templates:

• template.php - Haupt-Block-Wrapper
• template-parts/repeater.php - Repeater-Felder
• template-parts/group.php - Group-Felder
• template-parts/gallery.php - Gallery-Felder
• template-parts/image.php - Einzelne Bilder
• template-parts/file.php - Datei-Downloads
• template-parts/relationship.php - Relationship/Post Object
• template-parts/link.php - Link-Felder
• template-parts/select.php - Select/Checkbox (Listen)

Template-Hierarchie:

1. Child Theme: /template-parts/blocks/acf-field-display/{template-name}
2. Parent Theme: /template-parts/blocks/acf-field-display/{template-name}
3. Plugin: /inc/blocks/acf-field-display/{template-name} (Fallback)

Vorteil: Sie können z.B. nur das Galerie-Template überschreiben, ohne andere Templates anzufassen!

Siehe THEME-INTEGRATION.md für detaillierte Anleitungen und praktische Beispiele.

Entwicklung

Ordnerstruktur

nxt-acf-field-display/
├── nxt-acf-field-display.php           # Plugin Hauptdatei
├── inc/
│   └── blocks/
│       └── acf-field-display/
│           ├── register.php             # Block & Field Group Registrierung
│           ├── template.php             # Haupt-Block-Template
│           └── template-parts/          # Feldtyp-Templates
│               ├── repeater.php         # Repeater-Template
│               ├── group.php            # Group-Template
│               ├── gallery.php          # Gallery-Template
│               ├── image.php            # Image-Template
│               ├── file.php             # File-Template
│               ├── relationship.php     # Relationship-Template
│               ├── link.php             # Link-Template
│               └── select.php           # Select/Checkbox-Template
├── languages/                           # Übersetzungsdateien
├── README.md                            # Plugin-Dokumentation
├── REPEATER-USAGE.md                   # Repeater/Group/Gallery Guide
├── THEME-INTEGRATION.md                # Template-Override Guide
└── TEMPLATES.md                        # Template Quick Reference

Hooks & Filter

Das Plugin bietet verschiedene WordPress Hooks für Erweiterungen:

Block Hooks

• acf/init - Block Registrierung
• acf/load_field/name=acf_field_key - Dynamisches Laden der Feldauswahl

Template Hooks

• nxt_acf_field_display_template_path - Template-Pfad überschreiben
• nxt_acf_field_display_render_array - Array-Feld Rendering anpassen
• nxt_acf_field_display_render_repeater - Repeater Rendering anpassen
• nxt_acf_field_display_render_group - Group Rendering anpassen
• nxt_acf_field_display_render_gallery - Gallery Rendering anpassen

Beispiel:

add_filter('nxt_acf_field_display_render_repeater', function($output, $field_value, $field_object) {
	// Custom Repeater Rendering
	return $output;
}, 10, 3);

Funktionen

Render-Funktionen

• nxt_acf_field_display_render_array() - Array-Felder rendern
• nxt_acf_field_display_render_object() - Objekt-Felder rendern
• nxt_acf_field_display_render_repeater() - Repeater-Felder rendern
• nxt_acf_field_display_render_group() - Group-Felder rendern
• nxt_acf_field_display_render_gallery() - Gallery-Felder rendern

Template-Funktionen

• nxt_acf_field_display_locate_template($template_name) - Findet Template mit Theme-Override-Hierarchie
• nxt_acf_field_display_get_template($template_name, $args) - Lädt Template mit Variablen

Bekannte Einschränkungen

• Nested Repeater (Repeater in Repeatern) werden derzeit nicht unterstützt
• Sub-Fields müssen String- oder Number-Werte sein (keine komplexen Objects/Arrays)
• Custom Templates unterstützen nur einfache Platzhalter-Ersetzung (kein PHP Code)

Changelog

1.0.0

• Initiales Release
• Support für alle gängigen ACF Feldtypen
• Repeater & Group Templates
• Native WordPress Gallery Integration
• Query Loop Support
• Block Supports Integration

Support

Bei Problemen oder Fragen wenden Sie sich bitte an nexTab:

• Website: https://nextab.de
• Email: kontakt@nextab.de

Lizenz

Dieses Plugin wurde von nexTab entwickelt.

Credits

Entwickelt von nexTab - WordPress Development & Design