Using composable directives

Note: This functionality will be added to the upcoming plugin's version 0.8.

Note: Module "Composable Directives" must be enabled to use this functionality (it is disabled by default). Check in guide Browsing, enabling and disabling modules on how to enable it.

Have a directive modify the behavior of another directive.

This functionality allows to be able to use a directive, when otherwise we could not use it due to a type mismatch (i.e. when a directive cannot be applied on the field, because it has an input which is different than the field's output).

For instance, field capabilities returns [String] (an array of strings), and directive @upperCase receives String. Hence, executing the following query returns an error due to the type mismatch:

query {
user(id: 1) {
capabilities @upperCase

With composable directives, we can employ directive @forEach (which iterates over an array of elements, and applies its nested directive on each of them) to set the stage before @upperCase is executed, making it receive a single element (of type String).

The query from above can be satisfied like this:

query {
user(id: 1) {
@upperCase(nestedUnder: -1)

Composing directives permalink

A directive argument nestedUnder is added to every directive on the schema, enabling to indicate which is its parent directive. This number is a negative integer, defining the parent directive's relative position.

In this example below, we have:

  • @directive1 is the parent directive
    • @directive11 is added under @directive1
    • @directive12 is added under @directive1
      • @directive 121 is added under @directive12:
@directive11(nestedUnder: -1)
@directive12(nestedUnder: -2)
@directive121(nestedUnder: -1)

Then, directives modify each other's behavior:

  • @directive1 influences @directive11 and @directive12
  • @directive12 influences @directive 121

Meta directives permalink

GraphQL API for WordPress ships with the following list of "meta" directives (whose goal is to modify the behavior of other directives):

@forEach permalink

Iterate over the elements of an array.

@advancePointerInArray permalink

Pass an element contained in the array, under a specific path.

GraphQL spec permalink

This functionality is currently not part of the GraphQL spec, but a related one has been requested:

Share on 🐦 Twitter | πŸ‘ŽπŸΎ Facebook