From bf85e6cd3b768fed2847e53bd7e5b3f21019ff48 Mon Sep 17 00:00:00 2001 From: Joscha <34318751+josxha@users.noreply.github.com> Date: Wed, 24 Jan 2024 19:58:14 +0100 Subject: [PATCH] Update README.md --- README.md | 183 +++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 139 insertions(+), 44 deletions(-) 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).