Docs Gettings started pages written
This commit is contained in:
Kingkor Roy Tirtho
@@ -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"
|
||||
@@ -0,0 +1,7 @@
|
||||
{
|
||||
"label": "Getting Started",
|
||||
"position": 1,
|
||||
"link": {
|
||||
"type": "generated-index"
|
||||
}
|
||||
}
|
||||
@@ -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';
|
||||
```
|
||||
@@ -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 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
|
||||
@@ -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<String, void>(
|
||||
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<String, void>(
|
||||
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
|
||||
:::
|
||||
@@ -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.
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"label": "Tutorial - Extras",
|
||||
"position": 3,
|
||||
"position": 4,
|
||||
"link": {
|
||||
"type": "generated-index"
|
||||
}
|
||||
|
||||
@@ -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"]
|
||||
},
|
||||
}),
|
||||
};
|
||||
|
||||
@@ -17,7 +17,7 @@ function HomepageHeader() {
|
||||
<div className='space-x-5'>
|
||||
<Link
|
||||
className="button button--primary button--lg"
|
||||
to="/docs/intro">
|
||||
to="/docs/getting-started/overview">
|
||||
Get Started
|
||||
</Link>
|
||||
<Link
|
||||
|
||||
Reference in New Issue
Block a user