diff --git a/docs/docs/basics/OptimisticUpdates.mdx b/docs/docs/advanced/OptimisticUpdates.mdx similarity index 99% rename from docs/docs/basics/OptimisticUpdates.mdx rename to docs/docs/advanced/OptimisticUpdates.mdx index 8c7cc42..90fef8e 100644 --- a/docs/docs/basics/OptimisticUpdates.mdx +++ b/docs/docs/advanced/OptimisticUpdates.mdx @@ -1,6 +1,6 @@ --- title: Optimistic Updates -sidebar_position: 10 +sidebar_position: 1 --- import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; diff --git a/docs/docs/advanced/PersistingQueries.mdx b/docs/docs/advanced/PersistingQueries.mdx new file mode 100644 index 0000000..bfdf7e7 --- /dev/null +++ b/docs/docs/advanced/PersistingQueries.mdx @@ -0,0 +1,128 @@ +--- +title: Persisting Queries +sidebar_position: 1 +--- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +Implementing offline capabilites by your own can be hard to do (and maintain!!) so Fl-Query makes easier for developers to do it. Fl-Query uses [Hive](https://docs.hivedb.dev/#/) to persist queries to disk. Hive is a Open Source, "lightweight and buzzing-fast key-value database made for Flutter and Dart." + +We're using hive because it supports storing unstructured data and the write speed is blazingly fast + +But it is planned to support multiple types of Database for persisting using an Adapter pattern + +### Persisting Queries + +Queries can be persisted by passing `jsonConfig` argument to the `QueryBuilder` or `useQuery`. Persisted queries are stored in [hive](https://docs.hivedb.dev/) cache and are available even after the app is restarted + +First make sure your custom data type is json serializable. You can use [json_serializable](https://pub.dev/packages/json_serializable) package to generate `toJson` and `fromJson` methods for your data type + + +```dart +import 'package:json_annotation/json_annotation.dart'; + +part 'todo.g.dart'; + +@JsonSerializable() +class Todo{ + final String id; + final String title; + final bool completed; + + Todo({ + required this.id, + required this.title, + required this.completed, + }); + + factory Todo.fromJson(Map json) => _$TodoFromJson(json); + Map toJson() => _$TodoToJson(this); +} +``` + + + + +```dart +QueryBuilder( + "todos", + () => api.getTodos(), + jsonConfig: JsonConfig( + fromJson: (json) => Todo.fromJson(json), + toJson: (todo) => todo.toJson(), + ), + builder: (context, query) { + /* ... */ + }, +); +``` + + + + +```dart +useQuery( + "todos", + () => api.getTodos(), + jsonConfig: JsonConfig( + fromJson: (json) => Todo.fromJson(json), + toJson: (todo) => todo.toJson(), + ), +); +``` + + + + +Right now due to lack of reflection support and compile time macros we're unable to serialize any data type on the fly. +That's why `JsonConfig` is required. Otherwise, a simple `persistToDisk: true` would have been enough + +### Persisting InfiniteQueries + +Just like `Query`, `InfiniteQuery` also accepts `jsonConfig` argument to persist page data to disk. With persisting `InfiniteQuery` you can achieve similar results like facebook/twitter's offline mode + + + + +```dart +InfiniteQueryBuilder( + "posts", + (page) => api.getPostsPaginated(page), + nextPage: (lastPage, lastPageData) { + /// returning [null] will set [hasNextPage] to [false] + if (lastPageData.posts.length < 10) return null; + return lastPage + 1; + }, + initialPage: 0, + jsonConfig: JsonConfig( + fromJson: (json)=> PagedPosts.fromJson(json), + toJson: (pagedPosts) => pagedPosts.toJson(), + ), + builder: /*...*/ +); +``` + + + + +```dart +final query = useInfiniteQuery( + "posts", + (page) => api.getPostsPaginated(page), + nextPage: (lastPage, lastPageData) { + /// returning [null] will set [hasNextPage] to [false] + if (lastPageData.posts.length < 10) return null; + return lastPage + 1; + }, + initialPage: 0, + jsonConfig: JsonConfig( + fromJson: (json)=> PagedPosts.fromJson(json), + toJson: (pagedPosts) => pagedPosts.toJson(), + ), +); +``` + + + + +This will persist each available page to a HiveStore \ No newline at end of file diff --git a/docs/docs/advanced/_category_.json b/docs/docs/advanced/_category_.json new file mode 100644 index 0000000..580b977 --- /dev/null +++ b/docs/docs/advanced/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "Advanced", + "position": 3, + "link": { + "type": "generated-index", + "description": "Advanced caching and data manipulation techniques to make your app better" + } +} \ No newline at end of file diff --git a/docs/docs/basics/InfiniteQueries.mdx b/docs/docs/basics/InfiniteQueries.mdx index 32cacca..b92d36d 100644 --- a/docs/docs/basics/InfiniteQueries.mdx +++ b/docs/docs/basics/InfiniteQueries.mdx @@ -217,7 +217,7 @@ await Future.wait( ### Set page data manually -`InfiniteQuery` provides a method `InfiniteQuery.setPageData` to set page data manually. This can be useful if you want to set data after a mutation for [Optmisitc Updates](/docs/basics/OptimisticUpdates) +`InfiniteQuery` provides a method `InfiniteQuery.setPageData` to set page data manually. This can be useful if you want to set data after a mutation for [Optmisitc Updates](/docs/advanced/OptimisticUpdates) ```dart query.setPageData(0, [...query.pages[0], newProduct]) @@ -309,56 +309,4 @@ final query = useInfiniteQuery( ``` - - -### Persisting InfiniteQueries - -The `pages` data can be saved to disk to be loaded next time when the app starts to reduce loading time of your app. Just like [`Query`](/docs/basics/Queries#persisting-queries) persisted `InfiniteQuery`'s `pages` data are stored in [hive](https://docs.hivedb.dev/#/). This can be widely useful to add offline capabilities to the app - -For this you need to pass a `jsonConfig: JsonConfig()` argument to `InfiniteQueryBuilder` or `useInfiniteQuery`. Also make sure your `DataType` is serializable to JSON. You can use [json_serializable](https://pub.dev/packages/json_serializable) to generate the code for you. - - - - -```dart -InfiniteQueryBuilder( - "posts", - (page) => api.getPostsPaginated(page), - nextPage: (lastPage, lastPageData) { - /// returning [null] will set [hasNextPage] to [false] - if (lastPageData.posts.length < 10) return null; - return lastPage + 1; - }, - initialPage: 0, - jsonConfig: JsonConfig( - fromJson: (json)=> PagedPosts.fromJson(json), - toJson: (pagedPosts) => pagedPosts.toJson(), - ), - builder: /*...*/ -); -``` - - - - -```dart -final query = useInfiniteQuery( - "posts", - (page) => api.getPostsPaginated(page), - nextPage: (lastPage, lastPageData) { - /// returning [null] will set [hasNextPage] to [false] - if (lastPageData.posts.length < 10) return null; - return lastPage + 1; - }, - initialPage: 0, - jsonConfig: JsonConfig( - fromJson: (json)=> PagedPosts.fromJson(json), - toJson: (pagedPosts) => pagedPosts.toJson(), - ), -); -``` - - - - -This will persist each available page to a HiveStore \ No newline at end of file + \ No newline at end of file diff --git a/docs/docs/basics/Mutations.mdx b/docs/docs/basics/Mutations.mdx index cdbae50..c08191e 100644 --- a/docs/docs/basics/Mutations.mdx +++ b/docs/docs/basics/Mutations.mdx @@ -133,7 +133,7 @@ final mutation = useMutation, dynamic, Map -> Learn how to use `onMutate` & `Query.setData` to implement [optimistic updates](/docs/basics/OptimisticUpdates) +> Learn how to use `onMutate` & `Query.setData` to implement [optimistic updates](/docs/advanced/OptimisticUpdates) ### Refetch Queries and InfiniteQueries on successful mutation diff --git a/docs/docs/basics/Queries.mdx b/docs/docs/basics/Queries.mdx index 11e40ee..61c2ea9 100644 --- a/docs/docs/basics/Queries.mdx +++ b/docs/docs/basics/Queries.mdx @@ -190,70 +190,4 @@ useQuery( -Now these queries won't be executed as soon as they're mounted. Until `Query.refresh()` or `Query.fetch()` is called these will stay in initial state. If `initial` data was passed, it'll be used until the query is refreshed. Same goes for persisting queries - -### Persisting Queries - -Queries can be persisted by passing `jsonConfig` argument to the `QueryBuilder` or `useQuery`. Persisted queries are stored in [hive](https://docs.hivedb.dev/) cache and are available even after the app is restarted - -First make sure your custom data type is json serializable. You can use [json_serializable](https://pub.dev/packages/json_serializable) package to generate `toJson` and `fromJson` methods for your data type - - -```dart -import 'package:json_annotation/json_annotation.dart'; - -part 'todo.g.dart'; - -@JsonSerializable() -class Todo{ - final String id; - final String title; - final bool completed; - - Todo({ - required this.id, - required this.title, - required this.completed, - }); - - factory Todo.fromJson(Map json) => _$TodoFromJson(json); - Map toJson() => _$TodoToJson(this); -} -``` - - - - -```dart -QueryBuilder( - "todos", - () => api.getTodos(), - jsonConfig: JsonConfig( - fromJson: (json) => Todo.fromJson(json), - toJson: (todo) => todo.toJson(), - ), - builder: (context, query) { - /* ... */ - }, -); -``` - - - - -```dart -useQuery( - "todos", - () => api.getTodos(), - jsonConfig: JsonConfig( - fromJson: (json) => Todo.fromJson(json), - toJson: (todo) => todo.toJson(), - ), -); -``` - - - - -Right now due to lack of reflection support and compile time macros we're unable to serialize any data type on the fly. -That's why `JsonConfig` is required. Otherwise, a simple `persistToDisk: true` would have been enough \ No newline at end of file +Now these queries won't be executed as soon as they're mounted. Until `Query.refresh()` or `Query.fetch()` is called these will stay in initial state. If `initial` data was passed, it'll be used until the query is refreshed. Same goes for persisting queries \ No newline at end of file diff --git a/docs/docs/basics/_category_.json b/docs/docs/basics/_category_.json index 99a4b2f..f8bb2b9 100644 --- a/docs/docs/basics/_category_.json +++ b/docs/docs/basics/_category_.json @@ -1,6 +1,6 @@ { "label": "Basics", - "position": 3, + "position": 2, "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/getting-started/_category_.json b/docs/docs/getting-started/_category_.json index 0a1f052..2568d75 100644 --- a/docs/docs/getting-started/_category_.json +++ b/docs/docs/getting-started/_category_.json @@ -1,6 +1,6 @@ { "label": "Getting Started", - "position": 1, + "position": 1, "link": { "type": "generated-index" } diff --git a/docs/docs/getting-started/overview.md b/docs/docs/getting-started/overview.md index d351c7f..2eca1c3 100644 --- a/docs/docs/getting-started/overview.md +++ b/docs/docs/getting-started/overview.md @@ -1,10 +1,9 @@ --- sidebar_position: 1 +title: Overview id: overview --- -## Overview - Asynchronous data caching, refetching & invalidation library for Flutter. FL-Query lets you manage & distribute your async data without touching any global state Fl-Query makes asynchronous server state management a breeze in flutter diff --git a/docs/docs/tutorial-extras/_category_.json b/docs/docs/tutorial-extras/_category_.json deleted file mode 100644 index 832c3d1..0000000 --- a/docs/docs/tutorial-extras/_category_.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "label": "Tutorial - Extras", - "position": 4, - "link": { - "type": "generated-index" - } -} diff --git a/docs/docs/tutorial-extras/img/docsVersionDropdown.png b/docs/docs/tutorial-extras/img/docsVersionDropdown.png deleted file mode 100644 index 97e4164..0000000 Binary files a/docs/docs/tutorial-extras/img/docsVersionDropdown.png and /dev/null differ diff --git a/docs/docs/tutorial-extras/img/localeDropdown.png b/docs/docs/tutorial-extras/img/localeDropdown.png deleted file mode 100644 index e257edc..0000000 Binary files a/docs/docs/tutorial-extras/img/localeDropdown.png and /dev/null differ diff --git a/docs/docs/tutorial-extras/manage-docs-versions.md b/docs/docs/tutorial-extras/manage-docs-versions.md deleted file mode 100644 index e12c3f3..0000000 --- a/docs/docs/tutorial-extras/manage-docs-versions.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -sidebar_position: 1 ---- - -# Manage Docs Versions - -Docusaurus can manage multiple versions of your docs. - -## Create a docs version - -Release a version 1.0 of your project: - -```bash -npm run docusaurus docs:version 1.0 -``` - -The `docs` folder is copied into `versioned_docs/version-1.0` and `versions.json` is created. - -Your docs now have 2 versions: - -- `1.0` at `http://localhost:3000/docs/` for the version 1.0 docs -- `current` at `http://localhost:3000/docs/next/` for the **upcoming, unreleased docs** - -## Add a Version Dropdown - -To navigate seamlessly across versions, add a version dropdown. - -Modify the `docusaurus.config.js` file: - -```js title="docusaurus.config.js" -module.exports = { - themeConfig: { - navbar: { - items: [ - // highlight-start - { - type: 'docsVersionDropdown', - }, - // highlight-end - ], - }, - }, -}; -``` - -The docs version dropdown appears in your navbar: - -![Docs Version Dropdown](./img/docsVersionDropdown.png) - -## Update an existing version - -It is possible to edit versioned docs in their respective folder: - -- `versioned_docs/version-1.0/hello.md` updates `http://localhost:3000/docs/hello` -- `docs/hello.md` updates `http://localhost:3000/docs/next/hello` diff --git a/docs/docs/tutorial-extras/translate-your-site.md b/docs/docs/tutorial-extras/translate-your-site.md deleted file mode 100644 index da2b8a3..0000000 --- a/docs/docs/tutorial-extras/translate-your-site.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -sidebar_position: 2 ---- - -# Translate your site - -Let's translate `docs/intro.md` to French. - -## Configure i18n - -Modify `docusaurus.config.js` to add support for the `fr` locale: - -```js title="docusaurus.config.js" -module.exports = { - i18n: { - defaultLocale: 'en', - locales: ['en', 'fr'], - }, -}; -``` - -## Translate a doc - -Copy the `docs/intro.md` file to the `i18n/fr` folder: - -```bash -mkdir -p i18n/fr/docusaurus-plugin-content-docs/current/ - -cp docs/intro.md i18n/fr/docusaurus-plugin-content-docs/current/intro.md -``` - -Translate `i18n/fr/docusaurus-plugin-content-docs/current/intro.md` in French. - -## Start your localized site - -Start your site on the French locale: - -```bash -npm run start -- --locale fr -``` - -Your localized site is accessible at `http://localhost:3000/fr/` and the `Getting Started` page is translated. - -:::caution - -In development, you can only use one locale at a same time. - -::: - -## Add a Locale Dropdown - -To navigate seamlessly across languages, add a locale dropdown. - -Modify the `docusaurus.config.js` file: - -```js title="docusaurus.config.js" -module.exports = { - themeConfig: { - navbar: { - items: [ - // highlight-start - { - type: 'localeDropdown', - }, - // highlight-end - ], - }, - }, -}; -``` - -The locale dropdown now appears in your navbar: - -![Locale Dropdown](./img/localeDropdown.png) - -## Build your localized site - -Build your site for a specific locale: - -```bash -npm run build -- --locale fr -``` - -Or build your site to include all the locales at once: - -```bash -npm run build -```