Query Functions

Manipuleer de waarden van velden binnen de GraphQL-query, via een verzameling hulpmiddelen en speciale directives die meta-programmeermogelijkheden bieden.

Field to Input

Haal de waarde van een veld op, manipuleer die en geef hem door als invoer aan een ander veld — allemaal binnen dezelfde query.

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

Iteratie en Manipulatie van Veldwaarden

Toevoeging van meta-directives aan het GraphQL-schema, voor het itereren en manipuleren van de waarde-elementen van array- en objectvelden:

@underArrayItem
@underJSONObjectProperty
@underEachArrayItem
@underEachJSONObjectProperty
@objectClone

@underArrayItem zorgt ervoor dat de geneste directive wordt toegepast op een specifiek item uit de array.

In de onderstaande query wordt alleen het eerste item in de array met categorienamen omgezet naar hoofdletters:

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

...wat het volgende oplevert:

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

Field on Field

Toevoeging van de @applyField-directive, om een bepaald veld uit te voeren op de waarde van het opgeloste veld.

Toegepast op een veld stelt de @applyField-directive je in staat om een ander veld uit te voeren (dat beschikbaar is op hetzelfde type en wordt toegepast op hetzelfde object), en de resulterende waarde door te geven aan een andere directive of de waarde van het veld te overschrijven.

In de onderstaande query heeft het veld Post.title voor het object de waarde "Hello world!". Door @applyField toe te voegen om het veld _strUpperCase uit te voeren:

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

...wordt de veldwaarde omgezet naar hoofdletters, wat het volgende oplevert:

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

Voorwaardelijke Veldmanipulatie

Toevoeging van meta-directives @if en @unless aan het GraphQL-schema, om een geneste directive voorwaardelijk uit te voeren op het veld.

@if voert zijn geneste directives alleen uit als een voorwaarde de waarde true heeft.

In deze query worden de namen van gebruikers "Leo" en "Peter" omgezet naar hoofdletters, omdat ze in de array met "speciale gebruikers" staan, terwijl "Martin" dat niet doet:

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

...wat het volgende oplevert:

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

Standaardwaarde van een Veld

Toevoeging van de @default-directive, om een waarde in te stellen voor null- of lege velden.

In het onderstaande voorbeeld geeft het veld featuredImage null terug wanneer een bericht geen uitgelichte afbeelding heeft:

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

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

Met @default kunnen we een standaardafbeelding ophalen:

{
  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"
      }
    }
  }
}

Veld Verwijderen uit Respons

Toevoeging van de @remove-directive aan het GraphQL-schema, die de uitvoer van een veld uit de respons verwijdert.

In de onderstaande query genereren we de URL om een HTTP-verzoek naar te sturen, door het sitedomein en het REST API-eindpunt samen te voegen. Omdat de waarden van deze componenten ons niet interesseren, hoeven we ze niet in de respons weer te geven en kunnen we ze verwijderen met @remove:

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
    }
  )
}

...wat de volgende respons oplevert (let op dat de velden siteURL en requestURL zijn verwijderd):

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

Foutmelding in Respons Activeren

Toevoeging van het globale veld _fail en de directive @fail aan het GraphQL-schema, om expliciet een vermelding toe te voegen aan de eigenschap errors in de respons, en het globale veld _warn en de directive @warn, om een vermelding toe te voegen aan de eigenschap warnings in de respons.

Het veld _fail voegt de fout altijd toe, en de directive @fail wanneer aan de voorwaarde in het argument condition is voldaan:

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"
    )
  }
}