From fe0df69b6eee37b62f6b1049ba7b3fc04ab2ba0c Mon Sep 17 00:00:00 2001 From: Kingkor Roy Tirtho Date: Fri, 23 Sep 2022 11:12:27 +0600 Subject: [PATCH] docs: add flutter hooks code for quick start and queries --- docs/docs/basics/{Queries.md => Queries.mdx} | 96 ++++++++++++++++++- .../{quick-start.md => quick-start.mdx} | 59 +++++++++++- 2 files changed, 148 insertions(+), 7 deletions(-) rename docs/docs/basics/{Queries.md => Queries.mdx} (64%) rename docs/docs/getting-started/{quick-start.md => quick-start.mdx} (67%) 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