diff --git a/README.md b/README.md
index a51370f..8f61e05 100644
--- a/README.md
+++ b/README.md
@@ -2,6 +2,10 @@
A slim yet powerful caching plugin for flutter_map tile layers.
+Many tile providers require users in their tile usage policy to cache
+tile requests. This lowers the load on those servers and provides a better
+experience to users.
+
![Pub Likes](https://img.shields.io/pub/likes/flutter_map_cache)
![Pub Points](https://img.shields.io/pub/points/flutter_map_cache)
![Pub Popularity](https://img.shields.io/pub/popularity/flutter_map_cache)
@@ -13,50 +17,65 @@ A slim yet powerful caching plugin for flutter_map tile layers.
## Features
-The package is using [dio](https://pub.dev/packages/dio) with the
-[dio_cache_interceptor](https://pub.dev/packages/dio_cache_interceptor) package and supports the storage backend that
+The package uses [dio](https://pub.dev/packages/dio) with the
+[dio_cache_interceptor](https://pub.dev/packages/dio_cache_interceptor) package
+and supports the storage backend that
you like.
Supported storage backends are:
-- [x] In-Memory (for testing)
-- [x] File System
-- [x] [Drift (SQLite)](https://pub.dev/packages/drift)
-- [x] [Hive](https://pub.dev/packages/hive)
-- [x] [ObjectBox](https://pub.dev/packages/objectbox)
+| Storage backend | Description |
+|-------------------------------------------------|----------------------------------------------------------------------------------------------------------------|
+| In-Memory | - For testing purposes
- `flutter_map` has memory caching itself |
+| File System | - Easy to setup, no additional storage backend package required
- potentially slower than using a database |
+| [Drift](https://pub.dev/packages/drift) | - SQLite database
- good platform support |
+| [Hive](https://pub.dev/packages/hive) | - key-value database
- easy to integrate |
+| [ObjectBox](https://pub.dev/packages/objectbox) | - NoSQL, ACID compliant
- Fast library
- More complex integration |
+| [Isar](https://pub.dev/packages/isar) | - NoSQL, ACID compliant
- Fast library
- More complex integration |
-Support for [Isar](https://pub.dev/packages/isar) and other storage backends will be supported as soon as the
-underlying package [dio_cache_interceptor](https://pub.dev/packages/dio_cache_interceptor) support them. See for
-example issue [dio_cache_interceptor#122](https://github.com/llfbandit/dio_cache_interceptor/issues/122) that tracks
-the support for isar.
+Other storage backends will be supported as soon as the underlying package
+[dio_cache_interceptor](https://pub.dev/packages/dio_cache_interceptor) supports
+them.
## Getting started
-1. Add the packages you want to use to your `pubspec.yaml` file. Only add the packages for the backend you want to use.
+1. Add the packages you want to use to your `pubspec.yaml` file. Only add the
+ packages for the backend you want to use.
```yaml
dependencies:
flutter_map: ^6.0.0 # in case you don't have it yet
flutter_map_cache: ^1.3.0 # this package
+ path_provider: ^2.1.2 # in case the storage backend requires a path
+
+ # drift
+ dio_cache_interceptor_db_store: ^5.1.0
+ sqlite3_flutter_libs: ^0.5.15
- dio_cache_interceptor_db_store: ^5.1.0 # drift
- sqlite3_flutter_libs: ^0.5.15 # drift
+ # file system
+ dio_cache_interceptor_file_store: ^1.2.2
- dio_cache_interceptor_file_store: ^1.2.2 # file system
+ # hive
+ dio_cache_interceptor_hive_store: ^3.2.1
- dio_cache_interceptor_hive_store: ^3.2.1 # hive
+ # objectbox
+ dio_cache_interceptor_objectbox_store: ^1.1.3
+ objectbox_flutter_libs: ^1.4.1
- dio_cache_interceptor_objectbox_store: ^1.1.1 # objectbox
- objectbox_flutter_libs: ^1.4.1 # objectbox
+ # isar
+ isar: ^3.1.0+1
+ isar_flutter_libs: ^3.1.0+1
```
-2. The storage backends might have their own required setups. Please check them out in their package documentations.
+2. ⚠️ Some storage backends have their own required setups. Please check them
+ out in their package documentations.
## Usage
Using the cache is easy. Here is an example how to use the **Hive** backend:
-First get the cache directory of the app (i.e. with the [path_provider](https://pub.dev/packages/path_provider)
+1. First get the cache directory of the app (i.e. with
+the [path_provider](https://pub.dev/packages/path_provider)
package).
```dart
@@ -68,8 +87,9 @@ Future getPath() async {
}
```
-Then use the directory path to initialize the `HiveCacheStore`. You can wrap FlutterMap inside a `FutureBuilder` to use
-the getPath() method.
+2. Then use the directory path to initialize the `HiveCacheStore`. You can wrap
+FlutterMap inside a `FutureBuilder` to use
+the `getPath()` method.
```dart
@override
@@ -99,42 +119,117 @@ You can find additional example usages for other storage backends here:
- [In Memory (for testing)](https://github.com/josxha/flutter_map_cache/wiki/Use-the-In%E2%80%90Memory-Store-(for-testing))
- [File System](https://github.com/josxha/flutter_map_cache/wiki/Use-the-File-System)
+...or check out
+[the example app](https://github.com/josxha/flutter_map_cache/tree/main/example)
+on GitHub for a full example implementation of most storage backends.
+
## Common use cases & frequent questions
### How about web?
-This package supports the web as long as you use a storage backend that supports web.
+
+ Click here to expand.
+
+This package supports the web as long as you use a storage backend that supports
+web.
- In Memory works out of the box
- Hive uses for its web support IndexedDB under the hood to support web.
-- Drift (SqLite) requires [additional setup steps for web](https://drift.simonbinder.eu/web/)
+- Drift (SqLite)
+ requires [additional setup steps for web](https://drift.simonbinder.eu/web/)
+
+---
+
+
+### Does this package support cancellation of tile requests?
-Additionally, this package has support to cancel tile requests that are no longer needed like the
-[flutter_map_cancellable_tile_provider](https://pub.dev/packages/flutter_map_cancellable_tile_provider/) plugin.
+
+ Click here to expand.
+
+Yes. This package includes the tile cancellation that would otherwise be
+provided
+by [flutter_map_cancellable_tile_provider](https://pub.dev/packages/flutter_map_cancellable_tile_provider/)
+out of the box.
+---
+
### Remove the api key from the url before it gets used for caching
-Commercial tile providers often use an api key that is attached as a parameter to the url. While this shouldn't be a
-problem when the api key stays the same you might want to make it immune to api key changes anyway.
-
-```flutter
-final _uuid = Uuid();
-
-CachedTileProvider(
- keyBuilder: (request) {
- return _uuid.v5(
- Uuid.NAMESPACE_URL,
- request.uri.replace(queryParameters: {}).toString(),
- );
- },
- ...
-),
+
+ Click here to expand.
+
+Commercial tile providers often use an api key that is attached as a parameter
+to the url. While this shouldn't be a problem when the api key stays the same
+you might want to make it immune to api key changes anyway.
+
+```dart
+
+final _uuid = Uuid();
+
+CachedTileProvider
+(
+keyBuilder: (request) {
+return _uuid.v5(
+Uuid.NAMESPACE_URL,
+request.uri.replace(queryParameters: {}).toString(),
+);
+},
+...
+)
+,
```
+---
+
+
+### How about pre-downloading, bulk-downloading or offline map?
+
+
+ Click here to expand.
+
+This package does not provide support to download tiles automatically.
+Only tiles that were previously visited with an active internet connection
+show up on the map.
+
+If you need bulk-downloading functionality you can check out the package
+[flutter_map_tile_caching](https://pub.dev/packages/flutter_map_tile_caching)
+(Paid license is needed or your project has to be open sourced under the
+GPL-3.0 license).
+
+Please note that free tile providers such as
+[OpenStreetMap](https://www.openstreetmap.org/) forbids bulk
+downloading (more than 250 tiles on a higher zoom level) of tiles in their
+[tile usage policy](https://operations.osmfoundation.org/policies/tiles/).
+If you use a paid tile provider, bulk-downloading can cause high costs if
+you pay per tile request. Using a proper offline map solution (e.g. MBTiles)
+would be my recommendation here.
+
+---
+
+
+### What if I want to use sqflite?
+
+
+ Click here to expand.
+
+Because [dio_cache_interceptor](https://github.com/llfbandit/dio_cache_interceptor)
+already supports Drift as a SQLite solution it's unlikely that sqflite will
+be supported any day soon.
+
+If you still are required to use only sqflite, I recommend to create your own
+tile provider by using the
+[cached_network_image](https://pub.dev/packages/cached_network_image) package.
+
+---
+
+
## Additional information
-Pull requests are welcome. If you want to add support for another storage backend you can check out
+Pull requests are welcome. If you want to add support for another storage
+backend you can check out
[dio_cache_interceptor](https://github.com/llfbandit/dio_cache_interceptor).
-If you need help you can [open an issue](https://github.com/josxha/flutter_map_cache/issues/new/choose) or join
-the [flutter_map discord server](https://discord.gg/BwpEsjqMAH).
+If you need help you
+can [open an issue](https://github.com/josxha/flutter_map_cache/issues/new/choose)
+or join
+the [`flutter_map` discord server](https://discord.gg/BwpEsjqMAH).