docs: update Query docs
This commit is contained in:
Kingkor Roy Tirtho
+24
-122
@@ -81,145 +81,47 @@ Both `QueryBuilder` and `useQuery` accepts error and success callbacks as well a
|
||||
|
||||
## Query
|
||||
|
||||
The `query` from the `builder` callback or returned from `useQuery` is the appropriate `Query` created based on the logic & configuration defined in the passed `QueryJob`
|
||||
The `Query` is passed to the `builder` callback or returned by `useQuery`
|
||||
|
||||
The `query` parameter aka `Query` contains all the useful getters, properties & methods for rendering data from the query. It contains the state of the current query, the data, the error, the loading status etc along with useful methods such as `refetch` and `setQueryData`
|
||||
The `query` parameter aka `Query` contains all the useful getters, properties & methods for rendering data from the query. It contains the state of the current query, the data, the error, the loading status etc along with useful methods such as `refresh` and `setData`
|
||||
|
||||
But more importantly, it contains the status of the current `Query`. It has to types of status one is Query Progression status & another is data availability status
|
||||
### Statuses
|
||||
|
||||
The `query` contains the status of the current query. It has 2 types of status: 1. Query Progression status 2. Data availability status
|
||||
|
||||
You can access them as follows:
|
||||
|
||||
- Progressive status of Query
|
||||
- `isSuccess`: When the task function returned data successfully
|
||||
- `isError`: When the task function returned an error
|
||||
- `isInitial`: When the passed `initialData` is being used and the query hasn't been fetched yet
|
||||
- `isLoading`: When the task function is running
|
||||
- `isRefetching`: When new data is being fetched or simply the `refetch` method is executing
|
||||
- `isIdle`: When there's no data & `Query`'s task has not been yet run
|
||||
- `isRefreshing`: When new data is being fetched or simply the `refresh` method is executing
|
||||
- `isInactive`: When a query isn't used by any Widget (query isn't mounted)
|
||||
- Data availability status of Query
|
||||
- `hasData`: When query contains data (expired or not)
|
||||
- `hasData`: When query contains data
|
||||
- `hasError`: When the query contains error
|
||||
|
||||
Now the most important part of query: Data and Error. You can access the data returned from the task using `query.data` or the error `query.error`. Both the data can be null. So always check if the data/error is null before accessing it
|
||||
Now the most important part of query: Data and Error. You can access the data returned from the task using `query.data` or the error `query.error`. Both can be null. So always check if the data/error is null before accessing it
|
||||
|
||||
:::info
|
||||
Don't use only `query.isLoading` to check if the data is available or not as the query can be failed & at this time `data` which can cause UI Exceptions. So use `query.hasData` always to check if `data` is available yet or not or use both together
|
||||
:::
|
||||
|
||||
Another important part of this is `refetch`. Well, you can use it to manually trigger refetch or want the query to get newest data
|
||||
### Refresh
|
||||
|
||||
Finally, you can use `setQueryData` to manually set the data of the query. This is useful when you want to refresh the query but the newest data is already available in the application. It can be used to reduce network traffic by saving network calls to the server. Or you can use it with `Mutations` to optimistically set data before the Mutation is executed & then update the query with actual data
|
||||
Another important part is `Query.refresh`. You can use it to manually trigger refresh or force the query to get the latest data
|
||||
|
||||
```dart
|
||||
await query.refresh();
|
||||
```
|
||||
|
||||
### Set data Manually
|
||||
|
||||
Finally, you can use `setData` to manually set the data of the query. This is useful when you want to refresh the query but the newest data is already available in the application. It can be used to reduce network traffic by saving network calls to the server. Or you can use it with `Mutations` to optimistically set data before the Mutation is executed & then update the query with actual data
|
||||
|
||||
```dart
|
||||
await query.setData("new data"); // type of 'data' has to match the DataType
|
||||
```
|
||||
|
||||
:::tip
|
||||
You can learn more about Optimistic Updates in the [Mutation Tutorial](/docs/basics/mutations)
|
||||
:::
|
||||
|
||||
Here's an real-world example of `Query` & `QueryBuilder`
|
||||
|
||||
The job:
|
||||
|
||||
```dart
|
||||
final anotherJob = QueryJob<String, Client>(
|
||||
queryKey: "another-unique-key",
|
||||
task: (queryKey, httpClient){
|
||||
return httpClient
|
||||
.get("https://jsonplaceholder.typicode.com/todos/1")
|
||||
.then((response) => response.body);;
|
||||
}
|
||||
);
|
||||
```
|
||||
|
||||
The Widget:
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="vanilla" label="Vanilla">
|
||||
|
||||
```dart
|
||||
class Example extends StatelessWidget {
|
||||
const Example({Key? key}) : super(key: key);
|
||||
|
||||
@override
|
||||
Widget build(BuildContext context) {
|
||||
// getting the instance of Client provided by the [provider] package
|
||||
final client = Provider.of<Client>(context);
|
||||
|
||||
return QueryBuilder<String, Client>(
|
||||
job: job,
|
||||
// passing the client as externalData
|
||||
externalData: client,
|
||||
builder: (context, query) {
|
||||
// checking if data availability along with progressive status
|
||||
if (!query.hasData || query.isLoading) {
|
||||
return const CircularProgressIndicator();
|
||||
}
|
||||
// remember to always show a fallback widget/screen for errors too.
|
||||
// It keeps the user aware of status of the application their using
|
||||
// & saves their time
|
||||
else if(query.hasError && query.isError){
|
||||
return Text(
|
||||
"My disappointment is immeasurable & my day is ruined for this stupid error: $error",
|
||||
);
|
||||
}
|
||||
return Row(
|
||||
children: [
|
||||
Text(query.data["title"]),
|
||||
ElevatedButton(
|
||||
child: const Text("Refetch"),
|
||||
onPressed: () async {
|
||||
await query.refetch();
|
||||
},
|
||||
),
|
||||
],
|
||||
);
|
||||
},
|
||||
);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
|
||||
<TabItem value="hooks" label="Flutter Hooks">
|
||||
|
||||
```dart
|
||||
class Example extends HookWidget {
|
||||
const Example({Key? key}) : super(key: key);
|
||||
|
||||
@override
|
||||
Widget build(BuildContext context) {
|
||||
// getting the instance of Client provided by the [provider] package
|
||||
final client = Provider.of<Client>(context);
|
||||
final query = useQuery<String, Client>(
|
||||
job,
|
||||
// passing the client as externalData
|
||||
externalData: client
|
||||
);
|
||||
|
||||
// checking if data availability along with progressive status
|
||||
if (!query.hasData || query.isLoading) {
|
||||
return const CircularProgressIndicator();
|
||||
}
|
||||
// remember to always show a fallback widget/screen for errors too.
|
||||
// It keeps the user aware of status of the application their using
|
||||
// & saves their time
|
||||
else if(query.hasError && query.isError){
|
||||
return Text(
|
||||
"My disappointment is immeasurable & my day is ruined for this stupid error: $error",
|
||||
);
|
||||
}
|
||||
return Row(
|
||||
children: [
|
||||
Text(query.data["title"]),
|
||||
ElevatedButton(
|
||||
child: const Text("Refetch"),
|
||||
onPressed: () async {
|
||||
await query.refetch();
|
||||
},
|
||||
),
|
||||
],
|
||||
);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
Reference in New Issue
Block a user