Aangepaste functies voor het schema

Veel functies die zijn voorgesteld voor de GraphQL-specificatie zijn al geïmplementeerd in Gato GraphQL, zodat we niet hoeven te wachten.

Schema-naamruimten

Als de plugins WooCommerce en Easy Digital Downloads allebei een Product-type voor de GraphQL API zouden implementeren, konden we niet beide plugins tegelijk installeren, omdat hun typen met elkaar in conflict zouden komen.

Schema-naamruimten maken het mogelijk om conflicten in het schema te vermijden, door aan alle typenamen een naamruimte toe te voegen. Zo zou het type Product respectievelijk Woo_Product en EDD_Product worden, en konden deze typen aan hetzelfde schema worden toegevoegd.

Deze afbeelding toont een schema met naamruimten, waarbij aan de typen Event en Location het voorvoegsel EM_ is toegevoegd om naambotsingen te voorkomen:

Schema met naamruimten

Globale velden

Globale velden zijn velden die toegankelijk zijn onder elk type in het GraphQL-schema (terwijl ze maar één keer worden gedefinieerd).

Het GraphQL-schema stelt typen beschikbaar, zoals Post, User en Comment, en de velden die beschikbaar zijn voor elk type, zoals Post.title, User.name en Comment.responses. Deze velden gaan over "gegevens", omdat ze een specifiek stukje data van een entiteit ophalen.

Gato GraphQL biedt daarnaast ook een ander soort velden: velden die "functionaliteit" bieden in plaats van gegevens.

Enkele voorbeelden van globale velden:

_not
_if
_equals
_isEmpty
_echo
_sprintf
_arrayItem
_arrayAddItem
_arrayUnique
en nog veel meer

Functionele velden zijn handig voor het ophalen van gegevens die buiten WordPress zijn opgeslagen, en voor het bewerken van gegevens nadat ze zijn opgehaald. Ze stellen je in staat een veldwaarde op elke gewenste manier te transformeren en geven je krachtige mogelijkheden voor het importeren/exporteren van gegevens.

Functionele velden behoren niet tot een specifiek type, zoals Post of User, maar tot alle typen in het schema. Daarom worden ze op een bijzondere manier behandeld in Gato GraphQL, onder de naam "globale velden".

Field to input

Haal de waarde van een veld op, bewerk die, en geef hem door als input 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)
  }
}

Samengestelde richtlijnen

Vaak kan een richtlijn niet op een veld worden toegepast, omdat de input ervan verschilt van de output van het veld. De richtlijn @strUpperCase ontvangt bijvoorbeeld een string als input, waardoor ze niet kan worden toegepast op het veld User.capabilities, dat een array van strings retourneert.

Met samengestelde richtlijnen kan een richtlijn een andere richtlijn uitbreiden om haar gedrag te wijzigen of een hiaat op te vullen. Dit elimineert de noodzaak om velden of richtlijnen te dupliceren alleen om hun input- of retourtypen te wijzigen, waardoor onnodige uitbreiding wordt voorkomen.

In deze query itereert de richtlijn @underEachArrayItem over een array van strings en past de geneste richtlijn @strUpperCase toe op elk ervan, waarmee het typeverschil wordt opgelost:

query {
  users {
    capabilities
      @underEachArrayItem
        @strUpperCase
  }
}

Multi-veld richtlijnen

Pas richtlijnen toe op meerdere velden (in plaats van slechts één), voor betere prestaties en uitgebreide gebruikssituaties.

Wanneer ingeschakeld, wordt aan alle richtlijnen een argument affectAdditionalFieldsUnderPos toegevoegd, waarmee de relatieve posities van extra velden waarop de richtlijn moet worden toegepast kunnen worden opgegeven.

In de volgende query wordt de richtlijn @strTranslate bijvoorbeeld alleen toegepast op het veld content:

query {
  posts {
    excerpt
    content @strTranslate
  }
}

Het veld excerpt kan ook de richtlijn @strTranslate krijgen, door het richtlijnargument affectAdditionalFieldsUnderPos met de waarde [1] toe te voegen (omdat 1 de relatieve positie is van het veld excerpt ten opzichte van de richtlijn @strTranslate):

query {
  posts {
    excerpt
    content
      @strTranslate(
        affectAdditionalFieldsUnderPos: [1]
      )
  }
}

Versioning van velden en richtlijnen

Versie velden en richtlijnen onafhankelijk van het schema.

In plaats van het volledige schema te evolueren (wat vereist dat de naam van het gewijzigde veld of de richtlijn wordt aangepast), kunnen we:

Verschillende implementaties onder dezelfde veld- of richtlijnnaam bewaren
De verouderde implementatie beschikbaar stellen onder een tag, met semantische versioning
Een specifieke versie openen via het veld/richtlijn-argument versionConstraint

Proactieve feedback

Gebruik het entry extensions op het hoogste niveau om gegevens over verouderingen en waarschuwingen in de respons op de query te sturen.

Verouderingen: Verouderingen worden teruggegeven in dezelfde query die verouderde velden bevat, en niet alleen bij het uitvoeren van introspectie.
Waarschuwingen: Waarschuwingen zijn problemen die als niet-blokkerend kunnen worden beschouwd, d.w.z. ze verbeteren de query maar breken hem niet.

De volgende query exporteert bijvoorbeeld twee velden met dezelfde dynamische variabelenaam "prop", wat een waarschuwing genereert:

query {
  posts {
    excerpt @export(as: "prop")
    content @export(as: "prop")
  }
}

De respons bevat de sectie warnings (onder extensions) met een bijbehorend bericht:

{
  "extensions": {
    "warnings": [
      {
        "message": "Dynamic variable with name 'props' had already been set, had its value overridden",
        "locations": [
          {
            "line": 4,
            "column": 25
          }
        ]
      }
    ]
  },
  "data": {
    "posts": {
      "excerpt": "Hello world!",
      "Content": "<p>Hello world!</p>"
    }
  }
}

Functie: