Shopify Metafields: anlegen, pflegen und im Theme korrekt ausgeben (OS 2.0)

Direkte Lösung in Kürze

• Lege zuerst eine Metafield-Definition an: Einstellungen → Benutzerdefinierte Daten.
• Pflege danach Werte am Objekt (z. B. Produkt): Produkte → (Produkt öffnen) → Metafelder.
• Gib das Metafield im Theme aus: im Theme-Editor per Dynamic Source oder per Liquid mit Blank-Check.
• Nutze den richtigen Typ (Text, Zahl, Datei, Referenz) und achte auf Namespace + Key.

Wann tritt das auf?

• Du willst zusätzliche Produktinfos (z. B. Material, Pflegehinweise, Herstellerdaten) pflegen, die nicht in Standardfeldern existieren.
• Du siehst im Theme-Editor kein passendes Feld unter „Dynamic Source“.
• Im Store erscheint nichts oder es steht Liquid error, obwohl ein Wert gepflegt ist.
• Du hast ein OS-2.0-Theme, aber das Metafield wird in der Section/Block nicht auswählbar.

Technischer Hintergrund: Warum passiert das?

• Shopify unterscheidet zwischen Metafield-Definition (Schema: Name, Namespace/Key, Typ, Validierung) und Metafield-Wert (konkreter Inhalt am Objekt).
• Der Theme-Editor (Dynamic Source) zeigt Metafelder nur an, wenn eine Definition existiert und der Feldtyp zum Eingabefeld passt.
• In Liquid hängt die Ausgabe vom Typ ab: viele Metafields liefern ein Objekt; häufig muss .value verwendet werden (insbesondere bei strukturierten Typen, Listen, Referenzen).
• OS-2.0-Themes nutzen JSON-Templates und Sections. Ob ein Metafield „anklickbar“ ist, hängt davon ab, ob die Section/der Block eine dynamische Quelle unterstützt.

Schritt-für-Schritt: So setzt du es um

1. Metafield-Definition anlegen

   • Öffne Einstellungen → Benutzerdefinierte Daten.
   • Wähle die Ressource, z. B. Produkte (oder Varianten, Kollektionen, Kunden, Bestellungen).
   • Klicke Definition hinzufügen.
   • Vergib einen Namen und setze Namespace und Key (z. B. custom.material).
   • Wähle den passenden Inhaltstyp (z. B. „Einzeiliger Text“, „Mehrzeiliger Text“, „Zahl“, „Datei“, „Produktreferenz“).
   • Optional: Validierung (z. B. maximale Länge) und ob das Feld für Storefronts sichtbar sein soll (je nach Shopify-UI/Version).
   • Speichern.

2. Metafield-Wert am Produkt pflegen

   • Öffne Produkte → (Produkt auswählen).
   • Scrolle zum Abschnitt Metafelder (erscheint nach dem Anlegen der Definition).
   • Trage den Wert ein (z. B. „100% Baumwolle“) und speichere das Produkt.

3. Ausgabe im Theme-Editor (Dynamic Source) – bevorzugt bei OS 2.0

   • Gehe zu Onlineshop → Themes → Anpassen.
   • Öffne eine Produktseite (Template), auf der du das Feld anzeigen willst.
   • Füge einen Block/Abschnitt hinzu, der dynamische Inhalte unterstützt (z. B. „Text“, „Collapsible row“, „Rich text“ – abhängig vom Theme).
   • Klicke beim Texteingabefeld auf das Dynamic-Source-Symbol und wähle dein Metafield (z. B. „Material“).
   • Speichern und im Frontend prüfen.

4. Ausgabe per Liquid (wenn Dynamic Source nicht möglich ist)

   • Gehe zu Onlineshop → Themes → … → Code bearbeiten.
   • Öffne die relevante Template/Section (z. B. sections/main-product.liquid oder eine Snippet-Datei, je nach Theme).
   • Füge eine Ausgabe mit Blank-Check ein (Beispiel für ein Produkt-Metafield custom.material):

   {% assign material = product.metafields.custom.material %}
   {% if material != blank %}
     <p><strong>Material:</strong> {{ material.value }}</p>
   {% endif %}

   • Speichern und Produktseite prüfen. Wenn du keinen Wert siehst: sicherstellen, dass am Produkt ein Wert gesetzt ist und Namespace/Key exakt stimmen.

5. Typ-spezifisch testen

   • Datei: Ausgabe erfolgt meist über ein Dateiobjekt; prüfe, ob dein Theme das erwartet. Oft ist Dynamic Source einfacher als Liquid.
   • Listen (z. B. Liste von Texten): du brauchst eine Schleife über metafield.value.
   • Referenzen (Produkt/Variante/Seite): .value liefert ein Objekt (z. B. Produkt), das du weiter rendern musst.

Häufige Fehler

• Metafield erscheint nicht im Theme-Editor – Ursache: Keine Definition angelegt oder falscher Ressourcentyp (z. B. Definition bei „Varianten“, Wert aber am Produkt erwartet). Fix: Definition unter der richtigen Ressource anlegen und Wert am passenden Objekt pflegen.
• Im Frontend wird nichts angezeigt – Ursache: Wert ist leer, oder Liquid prüft nicht auf blank und rendert leeren Content. Fix: Wert am Produkt setzen und Liquid mit Blank-Check nutzen.
• Liquid zeigt das Objekt statt Inhalt / gibt nichts aus – Ursache: .value fehlt (häufig bei strukturierten Typen, Listen, Referenzen). Fix: In Liquid {{ metafield.value }} verwenden und bei Listen iterieren.
• Namespace/Key stimmt nicht exakt – Ursache: Tippfehler oder anderes Namespace (z. B. custom vs. globals). Fix: In der Definition nachsehen und exakt übernehmen: product.metafields.<namespace>.<key>.
• Theme/Section unterstützt keine Dynamic Sources – Ursache: Nicht jedes Eingabefeld/Theme-Element ist „dynamic“ (theme-abhängig). Fix: anderen Block nutzen (z. B. Collapsible row) oder Liquid-Ausgabe in passender Section ergänzen.

Best Practices

• Namespace-Konvention: eigene Felder unter custom bündeln (z. B. custom.material, custom.care), statt unterschiedliche Namespaces zu mischen.
• Richtigen Typ wählen: keine „Mehrzeiliger Text“-Felder für strukturierte Daten; nutze Referenzen/Dateien/Listen passend, damit Theme-Editor und Validierung sauber funktionieren.
• Ausgabe-Logik kapseln: wiederverwendbare Metafield-Ausgaben in ein Snippet auslagern (Theme-abhängig), statt sie mehrfach in Sections zu duplizieren.
• Fallbacks definieren: wenn Metafield leer ist, entweder nichts anzeigen (Blank-Check) oder klaren Default setzen (nur wenn fachlich korrekt).
• OS-2.0 bevorzugen: wenn möglich, Dynamic Source statt Code verwenden; das reduziert Merge-Konflikte bei Theme-Updates.

Kurze Zusammenfassung

• Ohne Metafield-Definition ist das Feld weder sauber pflegbar noch zuverlässig im Theme nutzbar.
• Definition: Einstellungen → Benutzerdefinierte Daten; Wertpflege: direkt am Objekt (z. B. Produkt).
• OS-2.0: Ausgabe bevorzugt über Dynamic Source im Theme-Editor.
• Bei Liquid-Ausgabe fast immer mit Blank-Check arbeiten und je nach Typ .value verwenden.
• Die häufigsten Probleme sind falscher Ressourcentyp, falscher Namespace/Key und nicht unterstützte Dynamic Sources.