Fluent Commerce Logo
Docs
Sign In

GraphQL Data Provider Component

UI 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 NameCore

The standard library of mystique components. 

0000-00-00

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`
property for more details.

The pagination feature takes into account pagination variables in the query. For example, if

`first: 20`
is specified, it will iterate over pages with size 20. (By default it fetches in pages of 10). This is only really observable when the Loading Behavior is set to Pass Immediately, as you will see the data come in page by page.

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`
to control the page size of an orders query. (Avoid setting values for
`after`
and
`before`
as the data provider will not be able to paginate properly if the values have already been set.)

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`
. This is a string field that provides information on the current state of the data provider's fetching as provided in the table below. This can be used as either:

  • 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`
can provide the following values:

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

`string`

Yes

N/A

The graphql query to execute

path

`JsonPath`

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

`Record<String, Object>`

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:

`"variables":{`

`"retailer_id":"{{activeRetailer.id}}"`

`}`

max

`integer`

No

1000

The maximum number of root level entities to automatically fetch, if automatically paginating. (Cannot be set above 1000)

descendants

`MystiqueComponentInstance[]`

No

N/A

The descendants that you want to receive data from this provider.

loadingBehavior

`'wait' | 'wait-with-animation' | 'pass-immediately'`

No

pass-immediately

While data is being fetched, this specifies how data is passed down to children components.

`wait`
: The data provider waits for all data to be fetched before its rendering any children

`wait-with-animation`
: Same as above, but instead rendering nothing, it will show the default loading component (
`fc.loader`
).

`pass-immediately`
: Data is passed to its children as it receives each page of data. This can cause many re-renders, but is the most responsive option.

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

2023-06-03

1.0.0

Created the component

Recommended Placement

Anywhere

Copyright © 2024 Fluent Retail Pty Ltd (trading as Fluent Commerce). All rights reserved. No materials on this docs.fluentcommerce.com site may be used in any way and/or for any purpose without prior written authorisation from Fluent Commerce. Current customers and partners shall use these materials strictly in accordance with the terms and conditions of their written agreements with Fluent Commerce or its affiliates.

Fluent Logo