Skip to content

Commit 52276c7

Browse files
AkryumAkryum
committed
docs: ApolloMutation API
1 parent 1905a09 commit 52276c7

File tree

1 file changed

+272
-16
lines changed

1 file changed

+272
-16
lines changed

‎packages/docs/src/api/apollo-mutation.md‎

Lines changed: 272 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,9 @@
11
# ApolloMutation component
22

3+
This component allows you to send mutations from your template.
4+
5+
Use [props](#props) to configure the component and the default [slot](#slot-props) to interact with it.
6+
37
Example:
48

59
```vue
@@ -26,24 +30,276 @@ Example:
2630

2731
## Props
2832

29-
- `mutation`: GraphQL query (transformed by `graphql-tag`) or a function that receives the `gql` tag as argument and should return the transformed query
30-
- `variables`: Object of GraphQL variables
31-
- `optimisticResponse`: See [optimistic UI](https://www.apollographql.com/docs/react/performance/optimistic-ui/)
32-
- `update`: See [updating cache after mutation](https://www.apollographql.com/docs/react/data/mutations/#updating-the-cache-after-a-mutation)
33-
- `refetchQueries`: See [refetching queries after mutation](https://www.apollographql.com/docs/react/caching/advanced-topics/#updating-after-a-mutation)
34-
- `clientId`: id of the Apollo Client used by the query (defined in ApolloProvider `clients` option)
35-
- `tag`: String HTML tag name (default: `div`); if `undefined`, the component will be renderless (the content won't be wrapped in a tag)
36-
- `context`: See [apollo context](https://www.apollographql.com/docs/react/api/link/apollo-link-context/)
33+
### mutation
34+
35+
GraphQL query (transformed by `graphql-tag`) or a function that receives the `gql` tag as argument and should return the transformed query.
36+
37+
```vue
38+
<ApolloMutation
39+
:mutation="gql => gql`
40+
mutation DoStuff ($name: String!) {
41+
someWork (name: $name) {
42+
success
43+
timeSpent
44+
}
45+
}
46+
`"
47+
/>
48+
```
49+
50+
### variables
51+
52+
Object of GraphQL variables.
53+
54+
```vue
55+
<ApolloMutation
56+
:variables="{
57+
name
58+
}"
59+
/>
60+
```
61+
62+
### optimisticResponse
63+
64+
Optimistic UI is a pattern that you can use to simulate the results of a mutation and update the UI even before receiving a response from the server. Once the response is received from the server, the optimistic result is thrown away and replaced with the actual result.
65+
66+
Optimistic UI provides an easy way to make your UI respond much faster, while ensuring that the data becomes consistent with the actual response when it arrives.
67+
68+
See [optimistic UI](https://www.apollographql.com/docs/react/performance/optimistic-ui/)
69+
70+
```vue
71+
<ApolloMutation
72+
:optimisticResponse="{
73+
__typename: 'Mutation',
74+
someWork: {
75+
__typename: 'SomeWorkPayload',
76+
success: true,
77+
timeSpent: 100,
78+
},
79+
}"
80+
/>
81+
```
82+
83+
### update
84+
85+
When you execute a mutation, you modify back-end data. If that data is also present in your [Apollo Client cache](https://www.apollographql.com/docs/react/caching/cache-configuration/), you might need to update your cache to reflect the result of the mutation.
86+
87+
If a mutation modifies multiple entities, or if it creates or deletes entities, the Apollo Client cache is not automatically updated to reflect the result of the mutation. To resolve this, you can include an `update` function.
88+
89+
The purpose of an update function is to modify your cached data to match the modifications that a mutation makes to your back-end data.
90+
91+
See [updating cache after mutation](https://www.apollographql.com/docs/react/data/mutations/#updating-the-cache-after-a-mutation)
92+
93+
```vue
94+
<template>
95+
<ApolloMutation
96+
:update="update"
97+
/>
98+
</template>
99+
100+
<script>
101+
export default {
102+
methods: {
103+
update(cache, { data: { addTodo } }) {
104+
cache.modify({
105+
fields: {
106+
todos(existingTodos = []) {
107+
const newTodoRef = cache.writeFragment({
108+
data: addTodo,
109+
fragment: gql`
110+
fragment NewTodo on Todo {
111+
id
112+
type
113+
}
114+
`,
115+
})
116+
return [...existingTodos, newTodoRef]
117+
},
118+
},
119+
})
120+
},
121+
},
122+
}
123+
</script>
124+
```
125+
126+
### refetchQueries
127+
128+
In some cases, just using `dataIdFromObject` is not enough for your application UI to update correctly. For example, if you want to add something to a list of objects without refetching the entire list, or if there are some objects that to which you can't assign an object identifier, Apollo Client cannot update existing queries for you. Read on to learn about the other tools at your disposal.
129+
130+
`refetchQueries` is the simplest way of updating the cache. With `refetchQueries` you can specify one or more queries that you want to run after a mutation is completed in order to refetch the parts of the store that may have been affected by the mutation.
131+
132+
See [refetching queries after mutation](https://www.apollographql.com/docs/react/caching/advanced-topics/#updating-after-a-mutation)
133+
134+
```vue
135+
<template>
136+
<ApolloMutation
137+
:refetchQueries="refetchQueriesAfterMyMutation"
138+
/>
139+
</template>
140+
141+
<script>
142+
import { gql } from '@apollo/client/core'
143+
144+
export default {
145+
computed: {
146+
refetchQueriesAfterMyMutation () {
147+
return [{
148+
query: gql`
149+
query UpdateCache($repoName: String!) {
150+
entry(repoFullName: $repoName) {
151+
id
152+
comments {
153+
postedBy {
154+
login
155+
html_url
156+
}
157+
createdAt
158+
content
159+
}
160+
}
161+
}
162+
`,
163+
variables: { repoName: 'apollographql/apollo-client' },
164+
}]
165+
},
166+
},
167+
}
168+
</script>
169+
```
170+
171+
### clientId
172+
173+
Id of the Apollo Client used by the query (defined in ApolloProvider `clients` option)
174+
175+
```vue
176+
<ApolloMutation
177+
clientId="myClient"
178+
/>
179+
```
180+
181+
### tag
182+
183+
String HTML tag name (default: `div`); if `undefined`, the component will be renderless (the content won't be wrapped in a tag)
184+
185+
```vue
186+
<ApolloMutation
187+
tag="span"
188+
/>
189+
```
190+
191+
### context
192+
193+
Pass down the Apollo link chain a context object.
194+
195+
See [apollo context](https://www.apollographql.com/docs/react/api/link/apollo-link-context/)
196+
197+
```vue
198+
<ApolloMutation
199+
:context="{
200+
answer: 42,
201+
}"
202+
/>
203+
```
204+
205+
## Slot props
206+
207+
### mutate
208+
209+
Signature:
210+
211+
```ts
212+
mutate(options = null): Promise<FetchResult>
213+
```
214+
215+
- `options`: [mutation options](https://www.apollographql.com/docs/react/api/core/ApolloClient/#ApolloClient.mutate).
216+
217+
Function to call the mutation. You can override the mutation options (for example: `mutate({ variables: { foo: 'bar } })`).
218+
219+
```vue
220+
<ApolloMutation>
221+
<template v-slot="{ mutate }">
222+
<button @click="mutate({ variables: { myVar: 42 } })">Click me</button>
223+
</template>
224+
</ApolloMutation>
225+
```
226+
227+
### loading
228+
229+
Boolean indicating that the request is in flight.
230+
231+
```vue
232+
<ApolloMutation>
233+
<template v-slot="{ loading }">
234+
<button :disabled="loading">Click me</button>
235+
</template>
236+
</ApolloMutation>
237+
```
37238

38-
## Scoped slot props
239+
### error
39240

40-
- `mutate(options = undefined)`: Function to call the mutation. You can override the mutation options (for example: `mutate({ variables: { foo: 'bar } })`)
41-
- `loading`: Boolean indicating that the request is in flight
42-
- `error`: Eventual error for the last mutation call
43-
- `gqlError`: first GraphQL error if any
241+
Eventual error for the last mutation call.
242+
243+
```vue
244+
<ApolloMutation>
245+
<template v-slot="{error }">
246+
<p v-if="error">An error occurred: {{ error }}</p>
247+
</template>
248+
</ApolloMutation>
249+
```
250+
251+
### gqlError
252+
253+
First GraphQL error if any.
254+
255+
```vue
256+
<ApolloMutation>
257+
<template v-slot="{gqlError }">
258+
<p v-if="gqlError">An error occurred: {{ gqlError.message }}</p>
259+
</template>
260+
</ApolloMutation>
261+
```
44262

45263
## Events
46264

47-
- `done(resultObject)`
48-
- `error(errorObject)`
49-
- `loading(boolean)`
265+
### done
266+
267+
Emitted when a mutation result is received.
268+
269+
Parameters:
270+
271+
- `result`: FetchResult
272+
273+
```vue
274+
<ApolloMutation
275+
@done="result => {}"
276+
/>
277+
```
278+
279+
### error
280+
281+
Emitted when a error occurs.
282+
283+
Parameters:
284+
285+
- `error`: Error object
286+
287+
```vue
288+
<ApolloMutation
289+
@error="error => {}"
290+
/>
291+
```
292+
293+
### loading
294+
295+
When the loading state changes, the `loading` event is emitted.
296+
297+
Parameters:
298+
299+
- `loading`: Boolean
300+
301+
```vue
302+
<ApolloMutation
303+
@loading="loading => {}"
304+
/>
305+
```

0 commit comments

Comments
 (0)