From 5f8935a015e397f4848a2aec5667ca61d36e69ce Mon Sep 17 00:00:00 2001 From: Kingkor Roy Tirtho Date: Sun, 3 Jul 2022 20:39:02 +0600 Subject: [PATCH] Docs Gettings started pages written --- .../_category_.json | 2 +- .../congratulations.md | 0 .../create-a-blog-post.md | 0 .../create-a-document.md | 0 .../create-a-page.md | 0 .../deploy-your-site.md | 0 .../markdown-features.mdx | 0 docs/docs/getting-started/_category_.json | 7 ++ docs/docs/getting-started/installation.md | 24 +++++ docs/docs/getting-started/overview.md | 36 +++++++ docs/docs/getting-started/quick-start.md | 99 +++++++++++++++++++ docs/docs/intro.md | 47 --------- docs/docs/tutorial-extras/_category_.json | 2 +- docs/docusaurus.config.js | 3 +- docs/src/pages/index.tsx | 2 +- 15 files changed, 171 insertions(+), 51 deletions(-) rename docs/docs/{tutorial-basics => basics}/_category_.json (92%) rename docs/docs/{tutorial-basics => basics}/congratulations.md (100%) rename docs/docs/{tutorial-basics => basics}/create-a-blog-post.md (100%) rename docs/docs/{tutorial-basics => basics}/create-a-document.md (100%) rename docs/docs/{tutorial-basics => basics}/create-a-page.md (100%) rename docs/docs/{tutorial-basics => basics}/deploy-your-site.md (100%) rename docs/docs/{tutorial-basics => basics}/markdown-features.mdx (100%) create mode 100644 docs/docs/getting-started/_category_.json create mode 100644 docs/docs/getting-started/installation.md create mode 100644 docs/docs/getting-started/overview.md create mode 100644 docs/docs/getting-started/quick-start.md delete mode 100644 docs/docs/intro.md diff --git a/docs/docs/tutorial-basics/_category_.json b/docs/docs/basics/_category_.json similarity index 92% rename from docs/docs/tutorial-basics/_category_.json rename to docs/docs/basics/_category_.json index f8bb2b9..99a4b2f 100644 --- a/docs/docs/tutorial-basics/_category_.json +++ b/docs/docs/basics/_category_.json @@ -1,6 +1,6 @@ { "label": "Basics", - "position": 2, + "position": 3, "link": { "type": "generated-index", "description": "Learn all the basic concepts of Fl-Query as well as the practical use-cases that can enhance your development experience" diff --git a/docs/docs/tutorial-basics/congratulations.md b/docs/docs/basics/congratulations.md similarity index 100% rename from docs/docs/tutorial-basics/congratulations.md rename to docs/docs/basics/congratulations.md diff --git a/docs/docs/tutorial-basics/create-a-blog-post.md b/docs/docs/basics/create-a-blog-post.md similarity index 100% rename from docs/docs/tutorial-basics/create-a-blog-post.md rename to docs/docs/basics/create-a-blog-post.md diff --git a/docs/docs/tutorial-basics/create-a-document.md b/docs/docs/basics/create-a-document.md similarity index 100% rename from docs/docs/tutorial-basics/create-a-document.md rename to docs/docs/basics/create-a-document.md diff --git a/docs/docs/tutorial-basics/create-a-page.md b/docs/docs/basics/create-a-page.md similarity index 100% rename from docs/docs/tutorial-basics/create-a-page.md rename to docs/docs/basics/create-a-page.md diff --git a/docs/docs/tutorial-basics/deploy-your-site.md b/docs/docs/basics/deploy-your-site.md similarity index 100% rename from docs/docs/tutorial-basics/deploy-your-site.md rename to docs/docs/basics/deploy-your-site.md diff --git a/docs/docs/tutorial-basics/markdown-features.mdx b/docs/docs/basics/markdown-features.mdx similarity index 100% rename from docs/docs/tutorial-basics/markdown-features.mdx rename to docs/docs/basics/markdown-features.mdx diff --git a/docs/docs/getting-started/_category_.json b/docs/docs/getting-started/_category_.json new file mode 100644 index 0000000..0a1f052 --- /dev/null +++ b/docs/docs/getting-started/_category_.json @@ -0,0 +1,7 @@ +{ + "label": "Getting Started", + "position": 1, + "link": { + "type": "generated-index" + } +} \ No newline at end of file diff --git a/docs/docs/getting-started/installation.md b/docs/docs/getting-started/installation.md new file mode 100644 index 0000000..e5012f8 --- /dev/null +++ b/docs/docs/getting-started/installation.md @@ -0,0 +1,24 @@ +--- +sidebar_position: 2 +title: Installation +--- + +Fl-Query is just another Flutter "package" so no extra installation step needed just install it straight from https://pub.dev + +```bash +$ flutter pub add fl_query +``` + +### For using with `flutter_hooks` + +If you're an ELITE `flutter_hooks` user or want to use `fl_query_hooks` you'll only need the `flutter_hooks` package & nothing else + +```bash +$ flutter pub add flutter_hooks +``` + +The hooks can be imported as follows: + +```dart +import 'package:fl_query/fl_query_hooks.dart'; +``` \ No newline at end of file diff --git a/docs/docs/getting-started/overview.md b/docs/docs/getting-started/overview.md new file mode 100644 index 0000000..b70f228 --- /dev/null +++ b/docs/docs/getting-started/overview.md @@ -0,0 +1,36 @@ +--- +sidebar_position: 1 +id: overview +--- + +# Overview + +Fl-Query is a asynchronous data manager for Flutter that caches, fetches, automatically refetches stale data. Basically, its [React-Query](react-query.tanstack.com/) but for Flutter. But that doesn't mean it's a direct port of React-Query. Instead the concept of React-Query is implemented by Fl-Query + +## What does it offer? + +- Async data caching & invalidation +- Smart refetch in the background every time data becomes stale +- Declarative way to define asynchronous operations +- Code & data reusability because of persisted data & Query/Mutation [Job](/basic/job) API +- Optimistic data support +- Lazy Loading/Fetching support +- Zero Configuration out of the box & never have to touch any Global Store +- [Flutter Hooks](https://pub.dev/packages/flutter_hooks) support out of the box + +# Why? +![The hell, why?](https://media.giphy.com/media/1M9fmo1WAFVK0/giphy.gif) + +The main purpose of Fl-Query is providing the easiest way to manage the messy server-state part requiring the least amount of code with code reusability & performance + +Some Questions and their answers: +- **Isn't `FutureBuilder` good enough?** + + Yes but it is only if your commercial server has huge load of power & you're made of money or your app is simple or mostly offline & barely requires internet connection + `FutureBuilder` isn't good for data persistency & its impossible to share data across the entire application using it. Also if you call your fetching function directly in the `build` method as `future: getData("random-id")` it'll run every time the component rebuilds & it can be mitigated only if you call the method inside `initState` which involves lots of boilerplate + +- **`FutureProvider` from [riverpod](riverpod.dev/) or [provider](https://github.com/rrousselGit/provider) should be enough, right?** + + Yeah, indeed its more than enough for many applications but what if your app needs Optimistic Updates & proper server-state synchronization or simply want a custom `cacheTime`? Although `FutureProvider` is a viable solution for most of the `Future` but still you've to manually manage the cache & it still have no support for _Lazy Loading_. + + Remi Rousselet's riverpod is definitely an inspiration for Fl-Query & the `QueryJob` & `MutationJob` API is actually inspired by riverpod & IMO is the best state management solution any library has ever provided but that's still a client state manager just like other client state manager or synchronous data manager diff --git a/docs/docs/getting-started/quick-start.md b/docs/docs/getting-started/quick-start.md new file mode 100644 index 0000000..0ac1820 --- /dev/null +++ b/docs/docs/getting-started/quick-start.md @@ -0,0 +1,99 @@ +--- +sidebar_position: 3 +title: Quick Start +--- + + +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'; + +void main() { + runApp(const MyApp()); +} + +// A QueryJob is where the Logic of how the data should be +// fetched can defined. The task callback is a PURE Function +// & have access to external resources through the second +// parameter where the first parameter is the queryKey +final successJob = QueryJob( + queryKey: "query-example", + task: (queryKey, externalData) => Future.delayed( + const Duration(seconds: 2), + () => + "The work successfully executed. Data: key=($queryKey) value=${ + Random.secure().nextInt(100) + }", + ), +); + +class MyApp extends StatelessWidget { + const MyApp({Key? key}) : super(key: key); + + @override + Widget build(BuildContext context) { + // QueryBowlScope creates a Bowl (metaphor for Collection/Store) + // for all the Queries & Mutations + return QueryBowlScope( + child: MaterialApp( + title: 'Fl-Query Quick Start', + theme: ThemeData( + useMaterial3: true, + primarySwatch: Colors.blue, + ), + home: const MyHomePage(), + ), + ); + } +} + +class BasicExample extends StatelessWidget { + const BasicExample({Key? key}) : super(key: key); + + @override + Widget build(BuildContext context) { + return Column( + crossAxisAlignment: CrossAxisAlignment.start, + children: [ + Text( + "# Basic Query Example", + style: Theme.of(context).textTheme.headline5, + ), + // QueryBuilder Widget provides the expected query + // instances through the builder callback based on + // the passed job & externalData argument + QueryBuilder( + job: successJob, + externalData: null, + builder: (context, query) { + if (!query.hasData || query.isLoading || query.isRefetching) { + return const CircularProgressIndicator(); + } + return Row( + children: [ + Text(query.data!), + ElevatedButton( + child: const Text("Refetch"), + onPressed: () async { + await query.refetch(); + }, + ), // Text + ], + ); // Row + }, + ), // QueryBuilder + ], + ); + } +} +``` + +:::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 + +Also you can browse [Spotube/fl_query_integrate](https://github.com/KRTirtho/spotube/tree/fl_query_integrate) branch of [Spotube](https://github.com/KRTirtho/spotube/) where Fl-Query is used in a real-world application experimentally +::: \ No newline at end of file diff --git a/docs/docs/intro.md b/docs/docs/intro.md deleted file mode 100644 index 52441ef..0000000 --- a/docs/docs/intro.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -sidebar_position: 1 ---- - -# Getting Started - -Let's discover **Docusaurus in less than 5 minutes**. - -## Getting Started - -Get started by **creating a new site**. - -Or **try Docusaurus immediately** with **[docusaurus.new](https://docusaurus.new)**. - -### What you'll need - -- [Node.js](https://nodejs.org/en/download/) version 14 or above: - - When installing Node.js, you are recommended to check all checkboxes related to dependencies. - -## Generate a new site - -Generate a new Docusaurus site using the **classic template**. - -The classic template will automatically be added to your project after you run the command: - -```bash -npm init docusaurus@latest my-website classic -``` - -You can type this command into Command Prompt, Powershell, Terminal, or any other integrated terminal of your code editor. - -The command also installs all necessary dependencies you need to run Docusaurus. - -## Start your site - -Run the development server: - -```bash -cd my-website -npm run start -``` - -The `cd` command changes the directory you're working with. In order to work with your newly created Docusaurus site, you'll need to navigate the terminal there. - -The `npm run start` command builds your website locally and serves it through a development server, ready for you to view at http://localhost:3000/. - -Open `docs/intro.md` (this page) and edit some lines: the site **reloads automatically** and displays your changes. diff --git a/docs/docs/tutorial-extras/_category_.json b/docs/docs/tutorial-extras/_category_.json index a8ffcc1..832c3d1 100644 --- a/docs/docs/tutorial-extras/_category_.json +++ b/docs/docs/tutorial-extras/_category_.json @@ -1,6 +1,6 @@ { "label": "Tutorial - Extras", - "position": 3, + "position": 4, "link": { "type": "generated-index" } diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js index c9da4bf..c7fdfcc 100644 --- a/docs/docusaurus.config.js +++ b/docs/docusaurus.config.js @@ -79,7 +79,7 @@ const config = { items: [ { type: 'doc', - docId: 'intro', + docId: 'getting-started/overview', position: 'left', label: 'Documentation', }, @@ -135,6 +135,7 @@ const config = { prism: { theme: lightCodeTheme, darkTheme: darkCodeTheme, + additionalLanguages: ["dart"] }, }), }; diff --git a/docs/src/pages/index.tsx b/docs/src/pages/index.tsx index 2b6b223..7b08a0a 100644 --- a/docs/src/pages/index.tsx +++ b/docs/src/pages/index.tsx @@ -17,7 +17,7 @@ function HomepageHeader() {
+ to="/docs/getting-started/overview"> Get Started