So verweisen Sie in BigCommerce-Stencil-Vorlagendateien auf benutzerdefinierte Metafelder

BigCommerce, Bigcommerce Stencil

Metafelder sind die Methode von BigCommerce, um strukturierte, benutzerdefinierte Daten an ein Produkt, eine Kategorie, eine Marke oder einen Warenkorb anzuhängen – also Informationen, die über die Standardfelder hinausgehen. Sie sind unter einem Namensraum und einem Schlüssel organisiert, sodass mehrere Apps oder Funktionen ihre eigenen Daten speichern können, ohne sich gegenseitig zu behindern. Metafelder sind ein wirklich nützlicher Bestandteil der Plattform. Sie gehören aber auch zu den Dingen, deren Einbindung in eine Shop-Seite am meisten Verwirrung stiftet.

Jemand versucht, ein Metafeld in eine Stencil-Vorlage einzubinden, und greift dabei auf dasselbe Muster zurück, das bei benutzerdefinierten Feldern funktioniert: Man durchläuft ein Array des Produktobjekts, gleicht es mit einem Namen ab und gibt den Wert aus. Doch dann wird nichts angezeigt – weder eine Fehlermeldung noch eine leere Zeichenfolge, einfach gar nichts, weil das Array, das man durchläuft, gar nicht existiert. Das ist meist der Moment, in dem jemand erkennt, dass Metafelder und benutzerdefinierte Felder in einer Vorlage völlig unterschiedlich behandelt werden.

Warum unterscheiden sich Metafelder von benutzerdefinierten Feldern?

Benutzerdefinierte Felder sind der einfache Fall. Sie sind bereits im Seitenkontext vorhanden, wenn Ihre Vorlage ausgeführt wird, und zwar als „product.custom_fields“, ein Array aus {Name, Wert}-Paaren. Eine Schleife, abgleichen, fertig.

{{#each product.custom_fields}}
  {{#if (eq this.name "thread_count")}}
    <span class="thread-count">{{this.value}}</span>
  {{/if}}
{{/each}}

Metafelder haben damit nichts zu tun. Sie sind nicht Teil des Standard-Produktkontexts, den Stencil erstellt. Wenn Sie in einer Standardvorlage von Cornerstone nach „product.metafields“ suchen, werden Sie nichts finden. Keine noch so ausgeklügelte Schleife kann Daten zurückgeben, die gar nicht erst abgerufen wurden.

Legen Sie den richtigen „permission_set“ für die Metafelder fest

Bevor Sie überhaupt eine Vorlage bearbeiten, gibt es ein Feld im Metafeld selbst, das entscheidet, ob es für den Storefront überhaupt sichtbar ist. Jedes Metafeld verfügt über einen „permission_set“ mit einem der folgenden Werte: „app_only“, „read“, „write“, „read_and_sf_access“ oder „write_and_sf_access“. Nur die beiden Varianten mit „_sf_access“ sind für die GraphQL-API des Storefront sichtbar. Stencil nutzt die GraphQL-API, um Metafelddaten in eine Seite zu laden.

Verwenden Sie GraphQL-Frontmatter, um Metafelder abzurufen

Da Metafelder nicht im Standardkontext enthalten sind, müssen Sie sie selbst abrufen. Dazu müssen Sie eine GraphQL-Abfrage im Front Matter der Vorlage verwenden. Der Front Matter befindet sich am Anfang einer Stencil-Vorlage zwischen den Markierungen „—“. Ein dortiger GQL-Block führt vor dem Rendern der Seite eine Abfrage an die Storefront-GraphQL-API durch und fügt das Ergebnis unter einem von Ihnen gewählten Namen wieder in den Seitenkontext ein.

---
gql: |
  query productMetafieldsById($productId: Int!) {
    site {
      product(entityId: $productId) {
        entityId
        metafields(namespace: "shared") {
          edges {
            node {
              key
              value
            }
          }
        }
      }
    }
  }
---

{{#each data.site.product.metafields.edges}}
  {{#if (eq this.node.key "size-guide")}}
    <div class="size-guide">{{{this.node.value}}}</div>
  {{/if}}
{{/each}}

Beachten Sie, dass es keinen separaten Variablenblock gibt, der „productId“ einer Variablen zuordnet. „$productId“ ist eine der speziellen Variablen, die Stencil je nach Seitentyp automatisch erkennt. Auf der Produktseite fügt Stencil die aktuelle „productId“ in eine Abfrage ein, die eine Variable mit genau diesem Namen deklariert. Sie müssen diese nicht selbst füllen. Wenn Sie nicht auf eine dieser speziellen Variablen zurückgreifen, können Sie auch eine Abfrage ganz ohne Variablen schreiben.

Das Argument „namespace“ übernimmt hier die eigentliche Arbeit. Metafelder werden gezielt nach Namespaces gruppiert, damit du eine Abfrage auf eine bestimmte Gruppe beschränken kannst. Du musst nicht jedes an ein Produkt angehängte Metafeld abrufen, unabhängig davon, ob du es benötigst oder nicht. Wenn ein Feld nicht angezeigt wird, überprüfe, ob der Namespace in deiner Abfrage genau mit dem übereinstimmt, unter dem es gespeichert wurde. Ein Fehler wird hier stillschweigend ignoriert – ein Tippfehler führt lediglich dazu, dass das Metafeld so aussieht, als würde es nicht existieren.

Warum ist die Einheitlichkeit bei der Namensgebung hier so wichtig?

Sowohl der Namespace als auch der Schlüssel dürfen maximal 64 Zeichen lang sein. BigCommerce behandelt beide als wörtliche Zeichenfolgen, sodass weder Groß-/Kleinschreibung berücksichtigt wird noch eine unscharfe Suche stattfindet. Wenn Sie etwas unter dem Namespace „Shared“ speichern und dann nach „shared“ suchen, erhalten Sie kein Ergebnis. Es sieht so aus, als hätte das Feld nie existiert. Aus diesem Grund ist es hilfreich, sich frühzeitig auf eine Namenskonvention zu einigen. Kleinbuchstaben und Bindestriche funktionieren gut. Das scheint auf den ersten Blick eine Kleinigkeit zu sein. Sobald jedoch drei Personen mit drei unterschiedlichen Schreibgewohnheiten Metafelder zum selben Shop hinzufügen, wird dies zu einem wirklich lästigen Fehler, der nur schwer aufzuspüren ist.

Warum funktioniert das nicht automatisch in jeder Vorlage?

Der Abruf befindet sich im Front Matter einer bestimmten Vorlage und gilt daher nur dort. Das Hinzufügen eines GQL-Blocks zu „product.html“ macht diese Daten weder in „category.html“ noch an anderer Stelle verfügbar. Stattdessen benötigt jede Vorlage, die ein bestimmtes Metafeld benötigt, eine eigene Kopie dieses Front-Matter-Blocks. Das vergisst man leicht, besonders wenn man von benutzerdefinierten Feldern kommt, da diese ohne jegliche Einrichtung überall angezeigt werden. Wenn also ein Metafeld auf der Produktseite einwandfrei dargestellt wird, aber in einer wiederverwendeten Komponente – beispielsweise einem Partial für verwandte Produkte – verschwindet, ist das in der Regel der Grund dafür. Das Partial hat nie nach den Daten gefragt. Nur die übergeordnete Vorlage hat dies getan.

Wo dies tatsächlich zum Einsatz kommt

Größentabellen, Pflegehinweise und ausführlichere Datenblätter sind die üblichen Anwendungsfälle – alles, was strukturierter ist als ein einfaches benutzerdefiniertes Feld, aber nicht ganz in die Hauptproduktbeschreibung passt. Metafelder tauchen auch auf eine zweite, weniger sichtbare Weise auf: Apps schreiben oft ihre eigenen Metafelder rein für den internen Gebrauch, die mit „app_only“ gekennzeichnet sind und direkt neben den _sf_access-Feldern stehen, die auf der Seite angezeigt werden sollen. Beide Arten können gleichzeitig für dasselbe Produkt vorhanden sein. Doch egal, wie die Abfrage geschrieben ist: Nur die Felder, die explizit für den Shop freigegeben wurden, werden jemals in eine Vorlage übernommen.

Kontaktieren Sie uns unter wargis@bay20.com / manish@bay20.com oder rufen Sie uns unter +91-9582784309 oder +91-8800519180 an, wenn Sie Unterstützung zu BigCommerce benötigen.