Query Functions

Manipulez les valeurs des champs dans la requête GraphQL, grâce à une collection d'utilitaires et de directives spéciales offrant des capacités de méta-programmation.

Field to Input

Obtenez la valeur d'un champ, manipulez-la et transmettez-la en entrée à un autre champ, le tout dans la même requête.

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

Itération et manipulation des valeurs de champs

Ajout de méta-directives au schéma GraphQL pour itérer et manipuler les éléments de valeur des champs de type array et object :

@underArrayItem
@underJSONObjectProperty
@underEachArrayItem
@underEachJSONObjectProperty
@objectClone

@underArrayItem fait en sorte que la directive imbriquée s'applique à un élément spécifique du tableau.

Dans la requête ci-dessous, seul le premier élément du tableau contenant les noms de catégorie est transformé en majuscules :

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

...produisant :

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

Champ sur champ

Ajout de la directive @applyField, pour exécuter un certain champ sur la valeur du champ résolu.

Appliquée à un champ, la directive @applyField permet d'exécuter un autre champ (disponible sur le même type et appliqué au même objet), et soit de transmettre la valeur résultante à une autre directive, soit de remplacer la valeur du champ.

Dans la requête ci-dessous, le champ Post.title pour l'objet a la valeur "Hello world!". En ajoutant @applyField pour exécuter le champ _strUpperCase :

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

...la valeur du champ est transformée en majuscules, produisant :

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

Manipulation conditionnelle des champs

Ajout des méta-directives @if et @unless au schéma GraphQL, pour exécuter conditionnellement une directive imbriquée sur le champ.

@if exécute ses directives imbriquées uniquement si une condition a la valeur true.

Dans cette requête, les utilisateurs "Leo" et "Peter" voient leurs noms convertis en majuscules, car ils figurent dans le tableau des « utilisateurs spéciaux », tandis que "Martin" ne l'est pas :

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

...produisant :

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

Valeur par défaut d'un champ

Ajout de la directive @default, pour attribuer une valeur aux champs nuls ou vides.

Dans l'exemple ci-dessous, lorsqu'un article n'a pas d'image à la une, le champ featuredImage renvoie null :

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

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

En utilisant @default, nous pouvons alors récupérer une image par défaut :

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

Suppression d'un champ de la réponse

Ajout de la directive @remove au schéma GraphQL, qui supprime la sortie d'un champ de la réponse.

Dans la requête ci-dessous, nous générons l'URL pour envoyer une requête HTTP en concaténant le domaine du site et le point de terminaison de l'API REST. Comme les valeurs de ces composants ne nous intéressent pas, il n'est pas nécessaire de les afficher dans la réponse, et nous pouvons les supprimer avec @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
    }
  )
}

...produisant cette réponse (notez que les champs siteURL et requestURL ont été supprimés) :

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

Déclencheur d'erreur dans la réponse

Ajout du champ global _fail et de la directive @fail au schéma GraphQL, pour ajouter explicitement une entrée à la propriété errors dans la réponse, ainsi que du champ global _warn et de la directive @warn, pour ajouter une entrée à la propriété warnings dans la réponse.

Le champ _fail ajoute l'erreur systématiquement, et la directive @fail lorsque la condition spécifiée dans l'argument condition est remplie :

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