docs: add flutter hooks code for quick start and queries

2022-09-23 11:12:27 +06:00
parent 8df1fc54c3
commit fe0df69b6e
2 changed files with 148 additions and 7 deletions
@@ -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`
+
+<Tabs>
+  <TabItem value="vanilla" label="Vanilla">

 ```dart
 class Example extends StatelessWidget {
@@ -27,12 +35,34 @@ class Example extends StatelessWidget {
 }
 ```

+  </TabItem>
+  <TabItem value="hooks" label="Flutter Hooks">
+
+```dart
+class Example extends HookWidget {
+  const Example({Key? key}) : super(key: key);
+
+  @override
+  Widget build(BuildContext context) {
+    final query = useQuery<String, void>(job, externalData: null);
+
+    if (!query.hasData) {
+      return const CircularProgressIndicator();
+    }
+    return Text(query.data!);
+  }
+}
+```
+
+  </TabItem>
+</Tabs>
+
 > 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<String, Client>(
@@ -76,7 +107,14 @@ final anotherJob = QueryJob<String, Client>(
    .then((response) => response.body);;
  }
 );
+```

+The Widget:
+
+<Tabs>
+  <TabItem value="vanilla" label="Vanilla">
+
+```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<Client>(context);
    
-    return QueryBuilder<String, void>(
+    return QueryBuilder<String, Client>(
      job: job,
      // passing the client as externalData
      externalData: client,
@@ -117,4 +155,52 @@ class Example extends StatelessWidget {
    );
  }
 }
-```
+```
+
+  </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>
@@ -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);
+<Tabs>
+  <TabItem value="vanilla" label="Vanilla">
+
+```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 {
 }
 ```

+  </TabItem>
+  <TabItem value="hooks" label="Flutter Hooks">
+
+```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<String, void>(
+      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
+      ],
+    );
+  }
+}
+```
+
+  </TabItem>
+</Tabs>
+
 :::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