Query Functions

Manipuliere die Werte von Feldern innerhalb der GraphQL-Query, mithilfe einer Sammlung von Hilfsfunktionen und speziellen Direktiven, die Meta-Programmierung ermöglichen.

Field to Input

Hole den Wert eines Feldes, verändere ihn und übergib ihn als Eingabe an ein anderes Feld – alles innerhalb derselben Query.

query {
  posts {
    excerpt
 
    # Referencing previous field with name "excerpt"
    isEmptyExcerpt: _isEmpty(value: $__excerpt)
 
    # Referencing previous field with alias "isEmptyExcerpt"
    isNotEmptyExcerpt: _not(value: $__isEmptyExcerpt)
  }
}

Iteration und Manipulation von Feldwerten

Hinzufügen von Meta-Direktiven zum GraphQL-Schema, um die Wertelemente von Array- und Objekt-Feldern zu iterieren und zu manipulieren:

@underArrayItem
@underJSONObjectProperty
@underEachArrayItem
@underEachJSONObjectProperty
@objectClone

@underArrayItem bewirkt, dass die verschachtelte Direktive auf ein bestimmtes Element des Arrays angewendet wird.

In der folgenden Query wird nur das erste Element des Arrays mit den Kategorienamen in Großbuchstaben umgewandelt:

query {
  posts {
    categoryNames
      @underArrayItem(index: 0)
        @strUpperCase
  }
}

...mit folgendem Ergebnis:

{
  "data": {
    "posts": {
      "categoryNames": [
        "NEWS",
        "sports"
      ]
    }
  }
}

Feld auf Feld

Hinzufügen der @applyField-Direktive, um ein bestimmtes Feld auf den Wert des aufgelösten Feldes auszuführen.

Auf ein Feld angewendet ermöglicht die @applyField-Direktive, ein anderes Feld auszuführen (das auf demselben Typ verfügbar und auf dasselbe Objekt angewendet ist), und den resultierenden Wert entweder an eine weitere Direktive weiterzugeben oder den Wert des Feldes zu überschreiben.

In der folgenden Query hat das Feld Post.title des Objekts den Wert "Hello world!". Durch Hinzufügen von @applyField zum Ausführen des Feldes _strUpperCase:

{
  post(by: { id: 1 }) {
    title
      @passOnwards(as: "input")
      @applyField(
        name: "_strUpperCase"
        arguments: {
          text: $input
        },
        setResultInResponse: true
      )
  }
}

...wird der Feldwert in Großbuchstaben umgewandelt, mit folgendem Ergebnis:

{
  "data": {
    "post": {
      "title": "HELLO WORLD!"
    }
  }
}

Bedingte Feldmanipulation

Hinzufügen der Meta-Direktiven @if und @unless zum GraphQL-Schema, um eine verschachtelte Direktive bedingt auf das Feld anzuwenden.

@if führt seine verschachtelten Direktiven nur aus, wenn eine Bedingung den Wert true hat.

In dieser Query werden die Namen der Benutzer "Leo" und "Peter" in Großbuchstaben umgewandelt, da sie im Array der „Sonderbenutzer" enthalten sind, während "Martin" nicht umgewandelt wird:

query {
  users {
    name
      @passOnwards(as: "userName")
      @applyField(
        name: "_inArray"
        arguments: {
          value: $userName
          array: ["Leo", "John", "Peter"]
        }
        passOnwardsAs: "isSpecialUser"
      )
      @if(
        condition: $isSpecialUser
      )
        @strUpperCase
  }
}

...mit folgendem Ergebnis:

{
  "data": {
    "users": [
      {
        "name": "LEO"
      },
      {
        "name": "Martin"
      },
      {
        "name": "PETER"
      }
    ]
  }
}

Standard-Feldwert

Hinzufügen der @default-Direktive, um null- oder leeren Feldern einen Wert zuzuweisen.

Im folgenden Beispiel gibt das Feld featuredImage den Wert null zurück, wenn ein Beitrag kein Beitragsbild hat:

{
  post(by: { id: 1 }) {
    featuredImage {
      id
      src
    }
  }
}

{
  "data": {
    "post": {
      "featuredImage": null
    }
  }
}

Mit @default können wir ein Standardbild abrufen:

{
  post(by: { id: 1 }) {
    featuredImage @default(value: 55) {
      id
      src
    }
  }
}

{
  "data": {
    "post": {
      "featuredImage": {
        "id": 55,
        "src": "http://mysite.com/wp-content/uploads/my-default-image.webp"
      }
    }
  }
}

Entfernen von Feldern aus der Antwort

Hinzufügen der @remove-Direktive zum GraphQL-Schema, die die Ausgabe eines Feldes aus der Antwort entfernt.

In der folgenden Query generieren wir die URL für eine HTTP-Anfrage, indem wir die Site-Domain und den REST-API-Endpunkt verketten. Da die Werte dieser Komponenten für uns nicht von Interesse sind, müssen sie nicht in der Antwort erscheinen, und wir können sie mit @remove entfernen:

query {
  siteURL: optionValue(name: "siteurl")
    @remove
 
  requestURL: _sprintf(
    string: "%s/wp-json/wp/v2/comments/11/?_fields=id,content,date",
    values: [$__siteURL]
  )
    @remove
 
  _sendJSONObjectItemHTTPRequest(
    input: {
      url: $__requestURL
    }
  )
}

...mit dieser Antwort (beachte, dass die Felder siteURL und requestURL entfernt wurden):

{
  "data": {
    "_sendJSONObjectItemHTTPRequest": {
      "id": 11,
      "date": "2020-12-12T04:07:36",
      "content": {
        "rendered": "<p>Btw, I really like this stuff<\/p>\n"
      }
    }
  }
}

Fehler-Trigger in der Antwort

Hinzufügen des globalen Feldes _fail und der Direktive @fail zum GraphQL-Schema, um der Eigenschaft errors in der Antwort explizit einen Eintrag hinzuzufügen, sowie des globalen Feldes _warn und der Direktive @warn, um der Eigenschaft warnings in der Antwort einen Eintrag hinzuzufügen.

Das Feld _fail fügt den Fehler immer hinzu, während die Direktive @fail ihn nur hinzufügt, wenn die im Argument condition angegebene Bedingung erfüllt ist:

query {
  _fail(message: "Some error")
  
  posts {
    featuredImage @fail(
      condition: IS_NULL,
      message: "The post does not have a featured image"
    ) {
      id
      src
    }
  }
  
  users {
    name @fail(
      condition: IS_EMPTY,
      message: "The retrieved user does not have a name"
    )
  }
}