GraphQL
Magento has an excellent GraphQL implementation which gives you more flexibility over the REST API. Rapidez provides some handy renderless GraphQL Vue components to communicate with GraphQL.
Examples
See the usage within the Rapidez Repositories
Query
<graphql>
component example to get a list of available countries from Magento:
<graphql v-cloak query="{ countries { full_name_locale } }">
<ul v-if="data" slot-scope="{ data }">
<li v-for="country in data.countries">@{{ country.full_name_locale }}</li>
</ul>
</graphql>
Props
Prop | Type | Default | Explanation |
---|---|---|---|
query | String | Required | GraphQL query |
variables | Object | {} | GraphQL variables |
store | String | window.config.store_code | Store code |
group | String | Bundle queries by a name into 1 request see: group | |
check | String | Run a check on the response data, for example: check="data.countries[0] == 'Country'" | |
redirect | String | Where to redirect if the check fails | |
cache | String | Cache key in localstorage. Caches only when provided and will be prefixed with graphql_ . Flushes when the cache is cleared. | |
callback | Function | Called after the query | |
error-callback | Function | Notification | Called after a unsuccessful query |
TIP
With large GraphQL queries you can extract the query to a separated file, for example: resources/views/queries/countries.graphql
and include it with: query='@include('queries.countries')'
Slot scopes
Prop | Type | Explanation |
---|---|---|
data | Object | The data returned from the GraphQL request |
Mutation
<graphql-mutation>
component example with a newsletter subscription form:
<graphql-mutation v-cloak query="mutation visitor ($email: String!) { subscribeEmailToNewsletter(email: $email) { status } }" :alert="false" :clear="true">
<div slot-scope="{ mutate, variables, mutated, error }">
<strong v-if="mutated">
@lang('Thank you for subscribing!')
</strong>
<div v-else>
<form v-on:submit.prevent="mutate">
<x-rapidez::input name="email" type="email" v-model="variables.email"/>
<x-rapidez::button type="submit">
@lang('Subscribe')
</x-rapidez::button>
</form>
<p v-if="error">
@{{ error }}
</p>
</div>
</div>
</graphql-mutation>
Props
Prop | Type | Default | Explanation |
---|---|---|---|
query | String | Required | The GraphQL query |
variables | Object | {} | Set the default variables :variables="{ email: '[email protected]' }" , useful when having the mutation component within the <graphql> component |
store | String | window.config.store_code | Store code |
group | String | Bundle queries by a name into 1 request see: group | |
watch | Boolean | true | Should the variables be watched? |
redirect | String | The redirect url | |
alert | Boolean | true | Show an alert when an error occurs |
clear | Boolean | false | Clear the values after the mutation |
notify | Object | Success notification | |
before-request | Function(query, variables, options): [query, variables, options] | Called before the request is sent in order to change, must return [query, variables, options] if used | |
callback | Function | Called after the mutation | |
error-callback | Function | Called after a unsuccessful query | |
mutate-event | String | Event name to listen to, used to trigger the mutate method | |
recaptcha | Boolean | false | Sends the X-ReCaptcha header with the request |
Slot scopes
Slot scopes are useful when wanting to get or update values or functions within the components template.
Prop | Type | Explanation |
---|---|---|
mutate | Function | Run the GraphQL query |
mutated | Boolean | True if the mutation has run |
mutating | Boolean | True when mutating |
error | String | The error message if the GraphQL request failed |
variables | Object | GraphQL variables |
watch | Boolean | Can be used to toggle the watch prop |
Grouping
With the group
prop you're able to bundle multiple GraphQL requests into 1 to increasing performance. When one of them get's executed the combined query will be send.
Note
You can not combine mutations and queries. Variable names should be unique, except cart_id
We also provide a submitPartials()
helper which can be used to submit multiple queries and have a callback when they're all finished. This is used in the onestep checkout to submit each section and only continue to the success page when everything is finished.
<form v-on:sumbit.prevent="(e) => {
submitPartials(e.target?.form ?? e.target)
.then((result) => window.Turbo.visit('/success'))
.catch()
}">
<graphql ...>
<fieldset partial-submit="mutate">...</fieldset>
</graphql>
<graphql ...>
<fieldset partial-submit="mutate">...</fieldset>
</graphql>
<button type="submit">Save</button>
</form>
Keep in mind
partial-submit
must always be on the direct child of a Vue component, and have it's original function name.
Example
<!-- Correct -->
<graphql ...>
<div partial-submit="mutate">...</div>
</graphql>
<!-- Correct -->
<graphql ...>
<fieldset partial-submit="mutate">...</fieldset>
</graphql>
<!-- Inorrect -->
<graphql ...>
<fieldset>
<div partial-submit="mutate">
...
</div>
</fieldset>
</graphql>
<!-- Inorrect -->
<graphql ...>
<fieldset v-slot={ mutate: save } partial-submit="save">...</fieldset>
</graphql>