|
| 1 | +# Mutations |
| 2 | + |
| 3 | +In Isograph, mutations aren't special. The distinguishing feature of mutations is often that you want to make the network request at a specific time, for example, in response to a user clicking a button. This document describes how to make network requests in response to events, which you can use to trigger a mutation. Okay, onward! |
| 4 | + |
| 5 | +## Walkthrough |
| 6 | + |
| 7 | +### Defining the mutation field |
| 8 | + |
| 9 | +First, define a client field on the `Mutation` object that calls the mutation you care about: |
| 10 | + |
| 11 | +```js |
| 12 | +export const setTagline = iso(` |
| 13 | + field Mutation.SetTagline($input: SetPetTaglineParams!) { |
| 14 | + set_pet_tagline(input: $input) { |
| 15 | + pet { |
| 16 | + tagline |
| 17 | + } |
| 18 | + } |
| 19 | + } |
| 20 | +`)((({data})) => data); |
| 21 | +``` |
| 22 | + |
| 23 | +Make sure you select the fields that you want refetched and written into the store. In this case, we want to see the updated pet's tagline. We also return the data. |
| 24 | + |
| 25 | +:::note |
| 26 | +Note also that we're naming the field `Mutation.SetTagline`, _not_ `Mutation.set_pet_tagline`. There already is a field named `Mutation.set_pet_tagline`, defined in the schema. So, if you attempt to define a client field named `Mutation.set_pet_tagline`, the Isograph compiler will emit an error and refuse to compile! |
| 27 | +::: |
| 28 | + |
| 29 | +### Calling the mutation |
| 30 | + |
| 31 | +Next, call `useImperativeReference`. This gives you back a fragment reference and a `loadFragmentReference` function: |
| 32 | + |
| 33 | +```jsx |
| 34 | +import { useImperativeReference } from '@isograph/react'; |
| 35 | +import { UNASSIGNED_STATE } from '@isograph/react-disposable-state'; |
| 36 | + |
| 37 | +export const PetTaglineCard = iso(` |
| 38 | + field Pet.PetTaglineCard @component { |
| 39 | + id |
| 40 | + tagline |
| 41 | + } |
| 42 | +`)(function PetTaglineCardComponent({ data: pet }) { |
| 43 | + const { |
| 44 | + fragmentReference: mutationRef, |
| 45 | + loadFragmentReference: loadMutation, |
| 46 | + } = useImperativeReference(iso(`entrypoint Mutation.SetTagline`)); |
| 47 | + // ... |
| 48 | +} |
| 49 | +``` |
| 50 | +
|
| 51 | +Next, call `loadFragmentReference` (`loadMutation` in this example) when a user clicks! |
| 52 | +
|
| 53 | +```jsx |
| 54 | +{ |
| 55 | + mutationRef === UNASSIGNED_STATE ? ( |
| 56 | + <Button |
| 57 | + onClick={() => { |
| 58 | + loadMutation({ |
| 59 | + input: { |
| 60 | + id: pet.id, |
| 61 | + tagline: 'SUPER DOG', |
| 62 | + }, |
| 63 | + }); |
| 64 | + }} |
| 65 | + variant="contained" |
| 66 | + > |
| 67 | + Set tagline to SUPER DOG |
| 68 | + </Button> |
| 69 | + ) : null; |
| 70 | +} |
| 71 | +``` |
| 72 | +
|
| 73 | +Since we only want to set the tagline once, we check that `mutation === UNASSIGNED_STATE` before showing the button. |
| 74 | +
|
| 75 | +### Reading the results |
| 76 | +
|
| 77 | +What about reading the results of the mutation? There are two good ways to do this, and two additional ways that will work in the future. |
| 78 | +
|
| 79 | +First, we can wait until the network response completes and see the component re-render with the updated tagline. |
| 80 | +
|
| 81 | +For the second method, we can modify the mutation field as follows: |
| 82 | +
|
| 83 | +```js |
| 84 | +export const setTagline = iso(` |
| 85 | + field Mutation.SetTagline($input: SetPetTaglineParams!) @component { |
| 86 | + set_pet_tagline(input: $input) { |
| 87 | + pet { |
| 88 | + tagline |
| 89 | + } |
| 90 | + } |
| 91 | + } |
| 92 | +`)((({data})) => { |
| 93 | + return ( |
| 94 | + <> |
| 95 | + Nice! You updated the pet's tagline to{' '} |
| 96 | + {data.set_pet_tagline?.pet?.tagline}! |
| 97 | + </> |
| 98 | + ); |
| 99 | +}); |
| 100 | +``` |
| 101 | +
|
| 102 | +Here, we add the `@component` annotation and return some JSX. |
| 103 | +
|
| 104 | +Now, we can use this! Modify the `PetTaglineCardComponent` component as follows: |
| 105 | +
|
| 106 | +```js |
| 107 | +{ |
| 108 | + mutationRef === UNASSIGNED_STATE ? ( |
| 109 | + <Button |
| 110 | + onClick={() => { |
| 111 | + loadMutation({ |
| 112 | + input: { |
| 113 | + id: pet.id, |
| 114 | + tagline: 'SUPER DOG', |
| 115 | + }, |
| 116 | + }); |
| 117 | + }} |
| 118 | + variant="contained" |
| 119 | + > |
| 120 | + Set tagline to SUPER DOG |
| 121 | + </Button> |
| 122 | + ) : ( |
| 123 | + <Suspense fallback="Mutation in flight"> |
| 124 | + <FragmentReader fragmentReference={mutationRef} /> |
| 125 | + </Suspense> |
| 126 | + ); |
| 127 | +} |
| 128 | +``` |
| 129 | +
|
| 130 | +#### Additional methods |
| 131 | +
|
| 132 | +The following methods will be available in the future: |
| 133 | +
|
| 134 | +- When reading a fragment reference is not a hook (see [this issue](https://github.com/isographlabs/isograph/issues/273)), you should be able to read the fragment conditionally in the parent component. |
| 135 | +- `useImperativeReference` (et al) will receive a `onCompleted` parameter that will be executed when the mutation completes, and will be passed the mutation results. You can set this in state. This is probably a bad practice, and shouldn't be relied on. |
0 commit comments