Query Functions

Manipola i valori dei campi all'interno della query GraphQL, tramite una raccolta di utilità e direttive speciali che forniscono capacità di meta-programmazione.

Field to Input

Ottieni il valore di un campo, manipolalo e passalo come input a un altro campo, tutto all'interno della stessa query.

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

Iterazione e manipolazione dei valori dei campi

Aggiunta di meta-direttive allo schema GraphQL per iterare e manipolare gli elementi di valore dei campi array e object:

@underArrayItem
@underJSONObjectProperty
@underEachArrayItem
@underEachJSONObjectProperty
@objectClone

@underArrayItem fa sì che la direttiva annidata venga applicata a un elemento specifico dell'array.

Nella query seguente, solo il primo elemento dell'array contenente i nomi delle categorie viene trasformato in maiuscolo:

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

...producendo:

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

Campo su campo

Aggiunta della direttiva @applyField, per eseguire un determinato campo sul valore del campo risolto.

Applicata a un campo, la direttiva @applyField consente di eseguire un altro campo (disponibile sullo stesso tipo e applicato allo stesso oggetto), e di passare il valore risultante a un'altra direttiva oppure di sovrascrivere il valore del campo.

Nella query seguente, il campo Post.title dell'oggetto ha valore "Hello world!". Aggiungendo @applyField per eseguire il campo _strUpperCase:

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

...il valore del campo viene trasformato in maiuscolo, producendo:

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

Manipolazione condizionale dei campi

Aggiunta delle meta-direttive @if e @unless allo schema GraphQL, per eseguire condizionalmente una direttiva annidata sul campo.

@if esegue le sue direttive annidate solo se una condizione ha valore true.

In questa query, gli utenti "Leo" e "Peter" vedono i loro nomi convertiti in maiuscolo, poiché sono presenti nell'array degli "utenti speciali", mentre "Martin" no:

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

...producendo:

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

Valore predefinito di un campo

Aggiunta della direttiva @default, per assegnare un valore ai campi nulli o vuoti.

Nell'esempio seguente, quando un articolo non ha un'immagine in evidenza, il campo featuredImage restituisce null:

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

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

Utilizzando @default, possiamo recuperare un'immagine predefinita:

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

Rimozione di un campo dalla risposta

Aggiunta della direttiva @remove allo schema GraphQL, che rimuove l'output di un campo dalla risposta.

Nella query seguente, generiamo l'URL per inviare una richiesta HTTP concatenando il dominio del sito e l'endpoint dell'API REST. Poiché i valori di questi componenti non ci interessano, non è necessario mostrarli nella risposta e possiamo rimuoverli con @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
    }
  )
}

...producendo questa risposta (si noti che i campi siteURL e requestURL sono stati rimossi):

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

Trigger di errore nella risposta

Aggiunta del campo globale _fail e della direttiva @fail allo schema GraphQL, per aggiungere esplicitamente una voce alla proprietà errors nella risposta, e del campo globale _warn e della direttiva @warn, per aggiungere una voce alla proprietà warnings nella risposta.

Il campo _fail aggiunge l'errore sempre, mentre la direttiva @fail lo aggiunge quando la condizione specificata nell'argomento condition è soddisfatta:

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