diff --git a/docs/docs/basics/Queries.md b/docs/docs/basics/Queries.mdx
similarity index 64%
rename from docs/docs/basics/Queries.md
rename to docs/docs/basics/Queries.mdx
index dad0569..6d483c5 100644
--- a/docs/docs/basics/Queries.md
+++ b/docs/docs/basics/Queries.mdx
@@ -3,9 +3,17 @@ title: Queries
sidebar_position: 3
---
-### QueryBuilder
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
-The defined logic in [QueryJob](/docs/basics/QueryJob) is bind to the Flutter UI using the `QueryBuilder` Widget. It's basically a `Builder` that takes a `QueryJob` through the `job` named parameter & creates/retrieves the appropriate `Query` and passes it down to the `builder` method
+### QueryBuilder and useQuery
+
+The defined logic in [QueryJob](/docs/basics/QueryJob) is bind to the Flutter UI using the `QueryBuilder` Widget (or `useQuery` hook). QueryBuilder is basically a `Builder` that takes a `QueryJob` through the `job` named parameter & creates/retrieves the appropriate `Query` and passes it down to the `builder` method
+
+On the other hand, `useQuery` is just a simple wrapper hook that does the same job as `QueryBuilder` but instead of building widgets it returns the actual `Query`
+
+
+
```dart
class Example extends StatelessWidget {
@@ -27,12 +35,34 @@ class Example extends StatelessWidget {
}
```
+
+
+
+```dart
+class Example extends HookWidget {
+ const Example({Key? key}) : super(key: key);
+
+ @override
+ Widget build(BuildContext context) {
+ final query = useQuery(job, externalData: null);
+
+ if (!query.hasData) {
+ return const CircularProgressIndicator();
+ }
+ return Text(query.data!);
+ }
+}
+```
+
+
+
+
> Here `job` is the same `QueryJob` defined at the first snippet in the [Query Job](/docs/basics/QueryJob) tutorial
The `externalData` parameter of the `QueryBuilder` is passed to the `task` function of the `QueryJob`. It was discussed previously in [Query Job#External Data](/docs/basics/QueryJob#external-data) section
### Query
-The passed query from the `builder` callback is the appropriate `Query` created based on the logic & configuration defined in the passed `QueryJob`
+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` 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`
@@ -66,6 +96,7 @@ You can learn more about Optimistic Updates in the [Mutation Tutorial](/docs/bas
Here's an real-world example of `Query` & `QueryBuilder`
+The job:
```dart
final anotherJob = QueryJob(
@@ -76,7 +107,14 @@ final anotherJob = QueryJob(
.then((response) => response.body);;
}
);
+```
+The Widget:
+
+
+
+
+```dart
class Example extends StatelessWidget {
const Example({Key? key}) : super(key: key);
@@ -85,7 +123,7 @@ class Example extends StatelessWidget {
// getting the instance of Client provided by the [provider] package
final client = Provider.of(context);
- return QueryBuilder(
+ return QueryBuilder(
job: job,
// passing the client as externalData
externalData: client,
@@ -117,4 +155,52 @@ class Example extends StatelessWidget {
);
}
}
-```
\ No newline at end of file
+```
+
+
+
+
+
+```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(context);
+ final query = useQuery(
+ 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();
+ },
+ ),
+ ],
+ );
+ }
+}
+```
+
+
+
\ No newline at end of file
diff --git a/docs/docs/getting-started/quick-start.md b/docs/docs/getting-started/quick-start.mdx
similarity index 67%
rename from docs/docs/getting-started/quick-start.md
rename to docs/docs/getting-started/quick-start.mdx
index 7ba62e5..2429d3e 100644
--- a/docs/docs/getting-started/quick-start.md
+++ b/docs/docs/getting-started/quick-start.mdx
@@ -3,11 +3,15 @@ sidebar_position: 3
title: Quick Start
---
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
This is a simple & dummy example that covers the usage of
- [Query](/)
- [QueryJob](/)
+
```dart
import 'package:fl_query/fl_query.dart';
import 'package:flutter/material.dart';
@@ -51,9 +55,14 @@ class MyApp extends StatelessWidget {
);
}
}
+```
-class BasicExample extends StatelessWidget {
- const BasicExample({Key? key}) : super(key: key);
+
+
+
+```dart
+class MyHomePage extends StatelessWidget {
+ const MyHomePage({Key? key}) : super(key: key);
@override
Widget build(BuildContext context) {
@@ -93,6 +102,52 @@ class BasicExample extends StatelessWidget {
}
```
+
+
+
+```dart
+class MyHomePage extends HookWidget {
+ const MyHomePage({Key? key}) : super(key: key);
+
+ @override
+ Widget build(BuildContext context) {
+ // useQuery hook returns the expected query
+ // instances based on the passed job & externalData argument
+ final query= useQuery(
+ job: successJob,
+ externalData: null,
+ );
+
+ return Column(
+ crossAxisAlignment: CrossAxisAlignment.start,
+ children: [
+ Text(
+ "# Basic Query Example",
+ style: Theme.of(context).textTheme.headline5,
+ ),
+ if (!query.hasData || query.isLoading || query.isRefetching)
+ const CircularProgressIndicator();
+ else
+ Row(
+ children: [
+ Text(query.data!),
+ ElevatedButton(
+ child: const Text("Refetch"),
+ onPressed: () async {
+ await query.refetch();
+ },
+ ), // Text
+ ],
+ ); // Row
+ ],
+ );
+ }
+}
+```
+
+
+
+
:::tip
If you want to explore more you can see the [Example Application](https://github.com/KRTirtho/fl-query/tree/main/packages/example) which covers a lot of use-cases