GitBook: [#5] Added Demonstration, Info For Offline Maps, And Miscell…

…aneous Improvements

README.md

@@ -14,15 +14,34 @@ layout: landing
 [![Pub.dev](https://img.shields.io/pub/v/flutter\_map.svg?label=Latest+Version)](https://pub.dev/packages/flutter\_map) [![Checks & Tests](https://badgen.net/github/checks/fleaflet/flutter\_map?label=Checks+%26+Tests\&color=orange)](https://github.com/fleaflet/flutter\_map/actions?query=branch%3Amaster) [![points](https://badges.bar/flutter\_map/pub%20points)](https://pub.dev/packages/flutter\_map/score)\
 [![stars](https://badgen.net/github/stars/fleaflet/flutter\_map?label=stars\&color=green\&icon=github)](https://github.com/fleaflet/flutter\_map/stargazers) [![likes](https://badges.bar/flutter\_map/likes)](https://pub.dev/packages/flutter\_map/score)      [![Open Issues](https://badgen.net/github/open-issues/fleaflet/flutter\_map?label=Open+Issues\&color=green)](https://github.com/fleaflet/flutter\_map/issues) [![Open PRs](https://badgen.net/github/open-prs/fleaflet/flutter\_map?label=Open+PRs\&color=green)](https://github.com/fleaflet/flutter\_map/pulls)
 
-## Source Code
-
-{% embed url="https://github.com/fleaflet/flutter_map" %}
-Visit the GitHub repository
-{% endembed %}
-
-{% embed url="https://pub.dev/packages/flutter_map" %}
-Visit the pub.dev package listing
-{% endembed %}
+## Demonstration
+
+This code snippet demonstrates everything you need for a simple map:
+
+```dart
+return FlutterMap(
+    options: MapOptions(
+        center: LatLng(51.509364, -0.128928),
+        zoom: 9.2,
+    ),
+    layers: [
+        TileLayerOptions(
+            urlTemplate: "https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png",
+            subdomains: ['a', 'b', 'c'],
+        ),
+    ],
+    nonRotatedChildren: [
+        AttributionWidget.defaultWidget(
+            source: 'OpenStreetMap contributors',
+            onSourceTapped: null,
+        ),
+    ],
+);
+```
+
+Choose an initial center and zoom (London in this case), add and credit a tile layer, and you're done!
+
+Of course, this package has much more functionality than shown here, and these are described extensively throughout this documentation.
 
 ## Feature Highlights
 
@@ -40,9 +59,9 @@ Vector tile support is not built in, but it is supported in beta by a plugin!
 
 <summary>Simple Setup</summary>
 
-No need for API keys or excessive platform specific setup. Just depend on it and set it up in less than 5 minutes.
+No need for API keys or excessive platform specific setup. Just depend on it and set it up in less than 5 minutes. The snippet above really does work!
 
-After that, you can add a map controller to programmatically control your map, such as position, zoom, and more!
+After that, you can add a map controller to programmatically control your map, such as position, zoom, and more.
 
 </details>
 
@@ -56,6 +75,26 @@ From tracking the user's location to caching tiles for offline use, this is all
 
 </details>
 
+<details>
+
+<summary>Supports Markers, Polygons, and Polylines Properly</summary>
+
+... and none of that complicated, confusing setup you need with the Google Maps package either. Just needs a normal widget builder or some coordinates, and nothing else.
+
+Using these is simple and quick, and the power of Flutter's `StreamBuilder` can make all of these a truly dynamic solution.
+
+</details>
+
+## Source Code
+
+{% embed url="https://github.com/fleaflet/flutter_map" %}
+Visit the GitHub repository
+{% endembed %}
+
+{% embed url="https://pub.dev/packages/flutter_map" %}
+Visit the pub.dev package listing
+{% endembed %}
+
 ## Support & Contact
 
 Having trouble with 'flutter\_map'? We hope we can help get you sorted.

SUMMARY.md

@@ -23,11 +23,12 @@
   * [WMS Usage](usage/layers/wms-usage.md)
 * [Controller](usage/controller.md)
 * [Common Issues](usage/common-issues.md)
+* [Full API Reference](https://pub.dev/documentation/flutter\_map/latest/flutter\_map/flutter\_map-library.html)
 
 ## Plugins
 
-* [Plugins List](plugins/plugins-list.md)
-* [How To Make A Plugin](plugins/how-to-make-a-plugin.md)
+* [Plugins List](plugins/list.md)
+* [How To Make A Plugin](plugins/guide.md)
 
 ## Tile Servers
 
@@ -41,8 +42,5 @@
 
 * [To v1.1.0](migration/to-v1.1.0.md)
 * [To v1.0.0](migration/to-v1.0.0.md)
-* [To v0.14.0](migration/to-v0.14.0.md)
-
-***
-
-* [Contributing](contributing.md)
+* [To v0.15.0](migration/to-v0.15.0.md)
+* [Contributing](migration/contributing.md)

getting-started/explanation.md

@@ -1,5 +1,11 @@
 # How Does It Work?
 
+{% hint style="info" %}
+If you don't know about standard map things, such as the latitude/longitude system and projections, you should probably read about these first!
+
+If you want a truly British insight into this, look no further than: [https://youtu.be/3mHC-Pf8-dU](https://youtu.be/3mHC-Pf8-dU) & [https://youtu.be/jtBV3GgQLg8](https://youtu.be/jtBV3GgQLg8). Otherwise I'd recommend something else.
+{% endhint %}
+
 This library is similar to most other mapping libraries in other languages, so this applies to most other mapping libraries as well.
 
 A mapping library is usually just a wrapper for a particular language that handles requests to servers called 'tile servers'.

contributing.md → migration/contributing.md

@@ -4,7 +4,7 @@
 
 Therefore, your contribution would be greatly appreciated, so we've written a guide to help you contribute successfully:
 
-## Rough Guide
+## Contribution Guide
 
 **Do you think your contribution is essential to 'flutter\_map'/useful to all users?**
 

migration/to-v1.0.0.md

@@ -4,5 +4,5 @@ This documentation was partially written during this update's lifetime.
 
 Some breaking changes were implemented. Notably:
 
-* `placeholderImage` was deprecated with no replacement or workaround
-* Some streams were changed from `Stream<Null>` to `Stream<void>`
+* `placeholderImage` was deprecated with no replacement or workaround. Remove it from your code before the next major release.
+* Some streams were changed from `Stream<Null>` to `Stream<void>`. These changes are simple to reflect in your code should you need to.

migration/to-v1.1.0.md

@@ -1,3 +1,5 @@
 # To v1.1.0
 
-The old method of adding attribution has been deprecated. You should now use [`AttributionWidget`](../usage/layers/attribution-layer.md).
+The old method of adding attribution through `attributionBuilder` on a `TileLayer` has been deprecated. You should now use [`AttributionWidget`](../usage/layers/attribution-layer.md), as this fixes issues with the old implementation.
+
+There are other bug fixes, but no other breaking changes associated with this release.

tile-servers/using-google-maps.md

@@ -11,4 +11,4 @@ Google Maps is a popular pay-as-you-go tile provider solution, especially for la
 
 Unfortunately, Google Maps does not officially document - and therefore support - a static raster tile server. There is an open and free endpoint (findable by doing a small amount of digging online), but it is unclear whether it violates their ToS or not, so it is not listed as usable here.
 
-To use Google Maps properly, you will need to use the official Flutter package.
+To use Google Maps properly, you will (unfortunately!) need to use the official Flutter package.

tile-servers/using-mapbox.md

@@ -1,7 +1,7 @@
 # Using Mapbox
 
 {% hint style="info" %}
-No Association 'flutter\_map' is in no way associated or related with Mapbox.
+'flutter\_map' is in no way associated or related with Mapbox.
 
 Mapbox's Maps home page: [mapbox.com/maps](https://www.mapbox.com/maps)\
 Mapbox's Maps pricing page: [mapbox.com/pricing#maps](https://www.mapbox.com/pricing#maps)\
@@ -18,9 +18,13 @@ Mapbox offers a variety of ready-made map styles that don't require customizatio
 
 First, create a custom map Style in the Studio. You can personalise to your heart's content, or leave it at default for a more vanilla feeling. You'll also need an [access token](https://docs.mapbox.com/help/getting-started/access-tokens/).
 
-Then make the map style public, and open the share dialog, as seen below: ![Mapbox Map Style Share Dialog](<../.gitbook/assets/flutter\_map wiki mapbox1>)
+Then make the map style public, and open the share dialog, as seen below:&#x20;
 
-Scroll to the bottom of the dialog, and select Third Party. Then from the drop down box, select 'CARTO': ![Mapbox Map Style Share Dialog](<../.gitbook/assets/flutter\_map wiki mapbox2>)
+![Opening the Sharing dialog](<../.gitbook/assets/flutter\_map wiki mapbox1>)
+
+Scroll to the bottom of the dialog, and select Third Party. Then from the drop down box, select 'CARTO':&#x20;
+
+![Retrieving the appropriate URL](<../.gitbook/assets/flutter\_map wiki mapbox2>)
 
 You'll then need to copy the URL and use it in 'flutter\_map', like in the code below.
 

usage/basics.md

@@ -16,6 +16,4 @@ We recommend placing it on it's own page and not restricting it's size, because
 
 However, if you wanted to show a widget that didn't need to interact with the map (but was related to the map) on top of the map (such as a compass), it would be recommended to place the `FlutterMap()` inside a `Stack()`, and then display that widget over the map in the stack.
 
-You should place this widget inside the build method of a stateful widget. However, avoid rebuilding this widget unnecessarily, and wherever possible use a `MapController` instead of changing state directly; this won't be possible for changing layer properties however.
-
 It takes three main properties: options, children/layers, and a map controller which you can use to control the map from behind the scenes. These will be described in the following sections.

usage/layers/tile-layer.md

@@ -23,6 +23,8 @@ FlutterMap(
 
 None of the properties are programmatically required, but the bare minimum required to display anything is `urlTemplate`.
 
+Below are some of the main parameters you are likely to need, but there are more available from the API Reference.
+
 ## URL Template (`urlTemplate:`)
 
 Takes a string that is a valid URL, which is the template to use when the tile provider constructs the URL to request a tile from a tile server. For example:
@@ -93,6 +95,16 @@ It will only cache tiles in memory, so do not rely on it at all to cache past an
 
 These tile providers use the `templateUrl` to get the appropriate tile from the asset store of the app, or from a file on the users device, respectively. On the web, `FileTileProvider()` will automatically use `NetworkImage()` behind the scenes.
 
+#### Offline Maps
+
+The `AssetTileProvider` is particularly useful to provide a set of map tiles to all your users without having to download it after the application is installed. Note that this is different to the [Caching](tile-layer.md#caching) section below.
+
+The filesystem should be structured like this: 'assets/offlineMap/{z}/{x}/{y}.png', where every png is a tile. 
+
+If you have a raster-format .mbtiles file, for example from TileMill, you should use [mbtilesToPngs](https://github.com/alfanhui/mbtilesToPngs) to convert it to the correct structure.
+
 ### Caching
 
 Whilst `FileTileProvider()` can be used for caching, better solutions can either be constructed yourself using other packages (such as [`cached_network_image`](https://pub.dev/packages/cached\_network\_image)), or by using an existing [community maintained plugin (`flutter_map_tile_caching`)](https://github.com/JaffaKetchup/flutter\_map\_tile\_caching) which handles caching and statistics for you, as well as offering methods to bulk download areas of maps.
+
+If you prefer to offer a set of map tiles to all your users before runtime, consider using the [Offline Maps](tile-layer.md#undefined) solution instead.