GraphQL Data Provider Component
Changed on:
31 July 2024
Overview
The GraphQL Data Provider component is a wrapper component that changes the data context for its descendants. It is useful when you want to display a separate set of data that is different from the page query.
Additionally, it provides more control options on how data is queried, including the ability to paginate and fetch data in bulk. Note that the maximum amount of data retrieved with the component is restricted.
| Plugin Name | Core |
|---|
The standard library of mystique components.
v1.0.0
Initial changelog entry.
Alias
fc.provider.graphql
Detailed technical description
The primary purpose of the data provider is to allow execution of additional GraphQL queries, and to feed the results of these queries to the data provider's children components. This will cause its child components to receive data from this provider's queries, rather than from the page-level query.
Additionally, it has properties that allow you to control how the data is fetched, including the ability to automatically paginate and fetch multiple pages of a connection. Use this component if you:
- Aim to utilize information from a different GraphQL query for specific component(s) on the page.
- Have hit the complexity limit and you need to split up your GraphQL query.
- Want to fetch all data from a connection at once. This can be useful if you have a component that allows for filtering or sorting data on the client side.
About the Auto Pagination Feature
As mentioned before, the data provider is capable of automatically paginating up to one connection (IE a list of items) in the provided query. Internally, the data provider will make multiple graphql queries to fetch the list of items until it either hits the max limit or there are no pages of data left to retrieve.
To use this feature, use the path property to tell the data provider the path to the entity that you want to automatically paginate. The feature will be automatically enabled if it detects that the path points to a connection. (Refer to the configuration example for a sample usage of this).
As this component is capable of loading large amounts of data at once, you can also control the behaviour of how its children are displayed while the data is being fetched. It is capable of rendering its children and re-rendering as more data arrives, or it can wait until all data is loaded before rendering its children. See the
`loadingBehavior`The pagination feature takes into account pagination variables in the query. For example, if
`first: 20`Setting first can cause the number of results fetched to go over the configured max limit when this limit is not a multiple of the page size.
The actual pagination variable names follow the same conventions as the List Component, documented under Sort Order and Page Size. For example, use
`orders_first``after``before`This component is capable of fetching up to 1000 results of a graphql entity for the first connection in the query.
Data
The results of the graphql query will be passed to its children components through the data prop. This will replace the data that the component usually gets from the page level query.
Additionally, the data prop will also have an additional field named
`dataProviderState`- A value in a template to show different things from a manifest level. For example, multiple Conditional components could be used to swap between components depending on the value of .
`dataProviderState` - A value at the code level by a custom component to fine-tune the behaviour of the component depending on the state of its data.
The
`dataProviderState`Value | Description |
ok | Provider has finished loading all data. (Or there was no data in the response to begin with.) |
error | Provider has encountered an error from a graphql query. The error message will be displayed in an alert. |
loading | Provider is still loading data up to the max limit |
max | Provider still is reporting more pages but is at the max entity limit |
Limitations and Known Issues
The Data Provider component currently doesn't work well with the List Component's ability to paginate. The List Component was designed to show one page of results at a time, whereas the Data Provider was designed to fetch a lot of data at once. When using the data provider with the list, all data fetched by the data provider will be displayed by the list, which may not be a good user experience if the list of items is too large. Additionally, none of the list's pagination features will work as intended.
Properties
Name | Type | Required | Default | Description |
query | | Yes | N/A | The graphql query to execute |
path | | No | N/A | The JSON path where we want the pagination to commence. To use the data fetching feature, the path property has to be used to direct the data context to an entity with an edge. |
variables | | No | N/A | A dictionary of graphql variables to use in the query. Note: the provider will not take any results from the page-level query. It can take {{activeRetailer}} or {{activeLocation}} as a query variable. For example: |
max | | No | 1000 | The maximum number of root level entities to automatically fetch, if automatically paginating. (Cannot be set above 1000) |
descendants | | No | N/A | The descendants that you want to receive data from this provider. |
loadingBehavior | | No | pass-immediately | While data is being fetched, this specifies how data is passed down to children components. |
Configuration example
1 {
2 "component": "fc.provider.graphql",
3 "props": {
4 "query": "query ($ref: [String!]) { variantProducts(ref: $ref) {edges {node {ref}}}}",
5 "path": "variantProducts",
6 "variables": {
7 "ref": "%AH%"
8 },
9 "max": 200,
10 "loadingBehavior": "wait-with-animation",
11 "descendants": [
12 {
13 "component": "fc.card.attribute",
14 "props": {
15 "title": "Card with Data Provided",
16 "width": 4,
17 "attributes": [
18 {
19 "label": "First Product",
20 "template": "{{edges.0.node.ref}}"
21 },
22 {
23 "label": "Second Product",
24 "template": "{{edges.1.node.ref}}"
25 }
26 ]
27 }
28 }
29 ]
30 }
31 },Language: json
Version History
1.0.0
Created the component
Recommended Placement
Anywhere
