From 6bca06cac15703592b2d9477295bb3e4794a23f5 Mon Sep 17 00:00:00 2001 From: Luka S Date: Sat, 25 Jun 2022 14:49:13 +0100 Subject: [PATCH] Prepare For New Documentation (#1286) * Prepare for new documentation website * Fixed broken link in issue template selector Added documentation field to pubspec * Update Example README * Added Correct Date To CHANGELOG Added Credits To CHANGELOG --- .github/ISSUE_TEMPLATE/config.yml | 7 +- CHANGELOG.md | 21 +- CODE_OF_CONDUCT.md | 128 +++++++++ CONTRIBUTING.md | 7 + README.md | 432 +----------------------------- example/README.md | 17 +- pubspec.yaml | 3 +- 7 files changed, 172 insertions(+), 443 deletions(-) create mode 100644 CODE_OF_CONDUCT.md create mode 100644 CONTRIBUTING.md diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index 9c610b553..35e62dc6f 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -3,6 +3,9 @@ contact_links: - name: Discord Server url: https://discord.gg/egEGeByf4q about: Need more generalised help, or just want to talk? Join the Discord server! - - name: Community Maintained Plugins - url: https://flutter-map.vercel.app/plugins/list + - name: Common Issues + url: https://docs.fleaflet.dev/usage/common-issues + about: Check whether your issue is listed as a common issue in the documentation + - name: Plugins + url: https://docs.fleaflet.dev/plugins/list about: If you need help with a plugin, please ask on their issue tracker first diff --git a/CHANGELOG.md b/CHANGELOG.md index 42bcf1f9a..e0a55803f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,25 @@ # Changelog -## [1.1.0] - 2022 +## [1.1.1] - 2022/06/25 + +Contains the following additions/removals: + +- None + +Contains the following bug fixes: + +- None + +In other news: + +- The new documentation website is now live at . Visit it today to get much improved setup and usage instructions, and more! + +Many thanks to these contributors (in no particular order): + +- All the documentation authors: +- ... and all the maintainers + +## [1.1.0] - 2022/06/16 Contains the following additions/removals: diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 000000000..0d782d62f --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,128 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our +community a harassment-free experience for everyone, regardless of age, body +size, visible or invisible disability, ethnicity, sex characteristics, gender +identity and expression, level of experience, education, socio-economic status, +nationality, personal appearance, race, religion, or sexual identity +and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, +diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment for our +community include: + +* Demonstrating empathy and kindness toward other people +* Being respectful of differing opinions, viewpoints, and experiences +* Giving and gracefully accepting constructive feedback +* Accepting responsibility and apologizing to those affected by our mistakes, + and learning from the experience +* Focusing on what is best not just for us as individuals, but for the + overall community + +Examples of unacceptable behavior include: + +* The use of sexualized language or imagery, and sexual attention or + advances of any kind +* Trolling, insulting or derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or email + address, without their explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our standards of +acceptable behavior and will take appropriate and fair corrective action in +response to any behavior that they deem inappropriate, threatening, offensive, +or harmful. + +Community leaders have the right and responsibility to remove, edit, or reject +comments, commits, code, wiki edits, issues, and other contributions that are +not aligned to this Code of Conduct, and will communicate reasons for moderation +decisions when appropriate. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when +an individual is officially representing the community in public spaces. +Examples of representing our community include using an official e-mail address, +posting via an official social media account, or acting as an appointed +representative at an online or offline event. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported to the community leaders responsible for enforcement at +github@jaffaketchup.dev. +All complaints will be reviewed and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security of the +reporter of any incident. + +## Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in determining +the consequences for any action they deem in violation of this Code of Conduct: + +### 1. Correction + +**Community Impact**: Use of inappropriate language or other behavior deemed +unprofessional or unwelcome in the community. + +**Consequence**: A private, written warning from community leaders, providing +clarity around the nature of the violation and an explanation of why the +behavior was inappropriate. A public apology may be requested. + +### 2. Warning + +**Community Impact**: A violation through a single incident or series +of actions. + +**Consequence**: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction with +those enforcing the Code of Conduct, for a specified period of time. This +includes avoiding interactions in community spaces as well as external channels +like social media. Violating these terms may lead to a temporary or +permanent ban. + +### 3. Temporary Ban + +**Community Impact**: A serious violation of community standards, including +sustained inappropriate behavior. + +**Consequence**: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. No public or +private interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, is allowed during this period. +Violating these terms may lead to a permanent ban. + +### 4. Permanent Ban + +**Community Impact**: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of an +individual, or aggression toward or disparagement of classes of individuals. + +**Consequence**: A permanent ban from any sort of public interaction within +the community. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], +version 2.0, available at +https://www.contributor-covenant.org/version/2/0/code_of_conduct.html. + +Community Impact Guidelines were inspired by [Mozilla's code of conduct +enforcement ladder](https://github.com/mozilla/diversity). + +[homepage]: https://www.contributor-covenant.org + +For answers to common questions about this code of conduct, see the FAQ at +https://www.contributor-covenant.org/faq. Translations are available at +https://www.contributor-covenant.org/translations. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..b79bef70c --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,7 @@ +# Contributing + +*Please note: A code of conduct is present in this project, please follow it in all your interactions with this project, including contributions.* + +Read the contributing instructions on the documentation website: . + +We always appreciate your ideas and changes! diff --git a/README.md b/README.md index fa6b82bc5..932bc7240 100644 --- a/README.md +++ b/README.md @@ -13,434 +13,8 @@ Join the Discord server: ! Talk about 'flutter_map', get and give help, and receive notifications about new 'flutter_map' updates! More additions planned in the future. -## [Beta Documentation](https://fleaflet-docs.netlify.app) +## [Documentation](https://docs.fleaflet.dev/) -View the beta documentation: ! -Link liable to break and/or change. Most contents should be correct (but not yet verified), but some documentation may be missing/misleading. +Visit the [documentation website here](https://docs.fleaflet.dev/), for all information about how to use this library, including setup and usage instructions. -Any feedback is appreciated! Please comment or leave a code review on [pull request #992](https://github.com/fleaflet/flutter_map/pull/992). - ---- - -## Installation & Configuration - -Add 'flutter_map' to your 'pubspec.yaml' with the command: - -```shell -> flutter pub add flutter_map -``` - -Include in your project with: - -```dart -import 'package:flutter_map/flutter_map.dart'; -``` - -### Android - -Configure your app to use the `INTERNET` permission in the manifest file located -in `/android/app/src/main/AndroidManifest.xml`: - -```xml - -``` - -## Usage - -Configure the map using `MapOptions` and layer options: - -```dart -Widget build(BuildContext context) { - return FlutterMap( - options: MapOptions( - center: LatLng(51.5, -0.09), - zoom: 13.0, - ), - layers: [ - TileLayerOptions( - urlTemplate: "https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png", - subdomains: ['a', 'b', 'c'], - ), - MarkerLayerOptions( - markers: [ - Marker( - width: 80.0, - height: 80.0, - point: LatLng(51.5, -0.09), - builder: (ctx) => - Container( - child: FlutterLogo(), - ), - ), - ], - ), - ], - nonRotatedChildren: [ - AttributionWidget.defaultWidget( - source: 'OpenStreetMap contributors', - onSourceTapped: () {}, - ), - ], - ); -} -``` - -Alternatively, initialize the map by specifying `bounds` instead of `center` and -`zoom`. - -```dart -MapOptions( - bounds: LatLngBounds(LatLng(58.8, 6.1), LatLng(59, 6.2)), - boundsOptions: FitBoundsOptions(padding: EdgeInsets.all(8.0)), -), -``` - -### Azure Maps provider - -To configure [Azure Maps](https://azure.com/maps), use the following -`MapOptions` and layer options: - -```dart -Widget build(BuildContext context) { - return new FlutterMap( - options: new MapOptions( - center: new LatLng(51.5, -0.09), - zoom: 13.0, - ), - layers: [ - new TileLayerOptions( - urlTemplate: "https://atlas.microsoft.com/map/tile/png?api-version=1&layer=basic&style=main&tileSize=256&view=Auto&zoom={z}&x={x}&y={y}&subscription-key={subscriptionKey}", - additionalOptions: { - 'subscriptionKey': '' - }, - ), - new MarkerLayerOptions( - markers: [ - new Marker( - width: 80.0, - height: 80.0, - point: new LatLng(51.5, -0.09), - builder: (ctx) => - new Container( - child: new FlutterLogo(), - ), - ), - ], - ), - ], - ); -} -``` - -To use Azure Maps, [set up an account and get a subscription -key][azure-maps-instructions] - -### Open Street Map provider - -Configure the map to use [Open Street Map][open-street-map] by using -the following `MapOptions` and layer options: - -```dart -Widget build(BuildContext context) { - return new FlutterMap( - options: new MapOptions( - center: new LatLng(51.5, -0.09), - zoom: 13.0, - ), - layers: [ - new TileLayerOptions( - urlTemplate: "https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png", - subdomains: ['a', 'b', 'c'] - ), - new MarkerLayerOptions( - markers: [ - new Marker( - width: 80.0, - height: 80.0, - point: new LatLng(51.5, -0.09), - builder: (ctx) => - new Container( - child: new FlutterLogo(), - ), - ), - ], - ), - ], - ); -} -``` - -### Mapbox provider - -To configure [Mapbox](https://www.mapbox.com/), you should create your -[access token](https://docs.mapbox.com/help/getting-started/access-tokens/). - -You can use tiles provided and hosted by Mapbox. The list can be found -[here](https://docs.mapbox.com/api/maps/styles/#mapbox-styles). - -```dart -Widget build(BuildContext context) { - return new FlutterMap( - options: new MapOptions( - center: new LatLng(51.5, -0.09), - zoom: 13.0, - ), - layers: [ - new TileLayerOptions( - urlTemplate: "https://api.mapbox.com/styles/v1/mapbox/streets-v11/tiles/" - "{z}/{x}/{y}?access_token=$accessToken", - ), - new MarkerLayerOptions( - markers: [ - new Marker( - width: 80.0, - height: 80.0, - point: new LatLng(51.5, -0.09), - builder: (ctx) => - new Container( - child: new FlutterLogo(), - ), - ), - ], - ), - ], - ); -} -``` - -Make sure `accessToken` is properly encoded as valid URI component. -If you use Mapbox Studio with your own tile sets, just use URL like this: -`https://api.mapbox.com/styles/v1/:accountName/:tileSetId/tiles/256/{z}/{x}/{y}@2x` -where `:accountName` is your user account name and `:tileSetId` is the -ID of your tile set, more information is [here](https://docs.mapbox.com/help/glossary/style-url/). - -### Widget Layers - -__Use the new way to create layers__ (compatible with previous version) - -```dart -Widget build(BuildContext context) { - return FlutterMap( - options: MapOptions( - center: LatLng(51.5, -0.09), - zoom: 13.0, - ), - layers: [ - MarkerLayerOptions( - markers: [ - Marker( - width: 80.0, - height: 80.0, - point: LatLng(51.5, -0.09), - builder: (ctx) => - Container( - child: FlutterLogo(), - ), - ), - ], - ), - ], - children: [ - TileLayerWidget(options: TileLayerOptions( - urlTemplate: "https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png", - subdomains: ['a', 'b', 'c'] - )), - MarkerLayerWidget(options: MarkerLayerOptions( - markers: [ - Marker( - width: 80.0, - height: 80.0, - point: LatLng(51.5, -0.09), - builder: (ctx) => - Container( - child: FlutterLogo(), - ), - ), - ], - )), - ], - ); -} -``` - -### Custom CRS - -By default flutter_map supports only WGS84 (EPSG:4326) and Google Mercator -(EPSG:3857) projections. The [proj4dart][proj4dart] package provides additional reference systems (CRS). - -To use proj4dart, first define a custom CRS: - -```dart -var resolutions = [32768, 16384, 8192, 4096, 2048, 1024, 512, 256, 128]; -var maxZoom = (resolutions.length - 1).toDouble(); - -var epsg3413CRS = Proj4Crs.fromFactory( - code: 'EPSG:3413', - proj4Projection: - proj4.Projection.add('EPSG:3413', '+proj=stere +lat_0=90 +lat_ts=70 +lon_0=-45 +k=1 +x_0=0 +y_0=0 +datum=WGS84 +units=m +no_defs'), - resolutions: resolutions, -); -``` - -Then use the custom CRS in the map layer and in WMS layers: - -```dart -child: FlutterMap( - options: MapOptions( - // Set the map's CRS - crs: epsg3413CRS, - center: LatLng(65.05166470332148, -19.171744826394896), - maxZoom: maxZoom, - ), - layers: [ - TileLayerOptions( - wmsOptions: WMSTileLayerOptions( - // Set the WMS layer's CRS too - crs: epsg3413CRS, - baseUrl: 'https://www.gebco.net/data_and_products/gebco_web_services/north_polar_view_wms/mapserv?', - layers: ['gebco_north_polar_view'], - ), - ), - ], -); -``` - -For more details, see the [custom CRS README][custom-crs-readme]. - -## Run the example - -See the `example/` folder for a working example app. - -To run it, in a terminal cd into the folder. Then execute `ulimit -S -n 2048` -([ref][ulimit-comment]). Then execute `flutter run` with a running emulator. - -## Downloading and caching offline maps - -This section provides an overview of the available caching tile providers. If -you would like to provide preconfigured and prepackaged map tiles to your app -users, see the 'Preconfigured Offline Maps' section below. - -The two available options included in flutter_map - -### 1. Use `NetworkImage` by using `NonCachingNetworkTileProvider` - -Whilst the name might make you think differently, it is designed to prevent you -from using it and expecting it to cache; because it doesn't. - -The `FlutterMap` `NonCachingNetworkTileProvider` implementaion uses -`NetworkImage` which should cache images in memory until the app restart -(through `Image.network`). See the [Image.network][Image.network] docs and -[NetworkImage][NetworkImage-caching] docs for more details. - -### 2. Using the `cached_network_image` dependency - -This dependency has an `ImageProvider` that caches images to disk, which means -the cache persists through an app restart. You'll need to [include the -package](https://pub.dev/packages/cached_network_image/install) in your -`pubspec.yaml`. - -Create your own provider using the code below: - -```dart -import 'package:cached_network_image/cached_network_image.dart'; -class CachedTileProvider extends TileProvider { - const CachedTileProvider(); - @override - ImageProvider getImage(Coords coords, TileLayerOptions options) { - return CachedNetworkImageProvider( - getTileUrl(coords, options), - //Now you can set options that determine how the image gets cached via whichever plugin you use. - ); - } -} -``` - -Then, add the `CachedTileProvider` `TileProvider` to the appropriate -`TileLayerOptions`: - -```dart -TileLayerOptions( - urlTemplate: 'https://example.com/{x}/{y}/{z}', - tileProvider: const CachedTileProvider() -) -``` - -## Offline Maps using TileMill - -This section provides instructions for preconfigured and prepackaged offline -maps. To see how to setup caching and downloading, see the 'Dynamically -Downloading & Caching Offline Maps' section above. - -This guide uses an open source program called [TileMill][tilemill-homepage]. - -First, [install TileMill][install-tilemill] on your machine. Then, follow [these -instructions][tilemill]. - -Once you have your map exported to `.mbtiles`, you can use -[mbtilesToPng][mbTilesToPngs] to unpack into `/{z}/{x}/{y}.png`. - -Move this to assets folder and add the appropriate asset directories to -`pubspec.yaml`. Minimum required fields for this solution are: - -```dart -Widget build(ctx) { - return FlutterMap( - options: MapOptions( - center: LatLng(56.704173, 11.543808), - zoom: 13.0, - swPanBoundary: LatLng(56.6877, 11.5089), - nePanBoundary: LatLng(56.7378, 11.6644), - ), - layers: [ - TileLayerOptions( - tileProvider: AssetTileProvider(), - urlTemplate: "assets/offlineMap/{z}/{x}/{y}.png", - ), - ], - ); -} -``` - -A missing asset error will be thrown if the PanBoundaries are outside the -offline map boundary. - -See the `flutter_map_example/` folder for a working example. - -See also `FileTileProvider()`, which loads tiles from the filesystem. - -## Plugins - -- [flutter_map_tile_caching](https://github.com/JaffaKetchup/flutter_map_tile_caching): Provides ability to properly cache tiles for offline use & easily download a region of a map for later offline use -- [flutter_map_marker_cluster](https://github.com/lpongetti/flutter_map_marker_cluster): Provides Beautiful Animated Marker Clustering functionality -- [user_location](https://github.com/igaurab/user_location_plugin): A plugin to handle and plot the current user location in FlutterMap -- [flutter_map_location](https://github.com/Xennis/flutter_map_location): A plugin to request and display the users location and heading on the map -- [flutter_map_location_marker](https://github.com/tlserver/flutter_map_location_marker): A simple and powerful plugin display the users location and heading -- [flutter_map_tappable_polyline](https://github.com/OwnWeb/flutter_map_tappable_polyline): A plugin to add `onTap` callback to `Polyline` -- [lat_lon_grid_plugin](https://github.com/mat8854/lat_lon_grid_plugin): Adds a latitude / longitude grid as plugin to the FlutterMap -- [flutter_map_marker_popup](https://github.com/rorystephenson/flutter_map_marker_popup): A plugin to show customisable popups for markers. -- [map_elevation](https://github.com/OwnWeb/map_elevation): A widget to display elevation of a track (polyline) like Leaflet.Elevation -- [flutter_map_floating_marker_titles](https://github.com/androidseb/flutter_map_floating_marker_titles): Displaying floating marker titles on the map view -- [vector_map_tiles](https://pub.dev/packages/vector_map_tiles): A plugin that enables the use of vector tiles. -- [flutter_map_dragmarker](https://pub.dev/packages/flutter_map_dragmarker): A plugin that enables a marker to be dragged. -- [flutter_map_line_editor](https://pub.dev/packages/flutter_map_line_editor): A plugin that enables creation/editing of polylines and polygons. -- [line_animator](https://pub.dev/packages/line_animator): Interpolates along a set of LatLng (or other) points, to allow gradual drawing of lines and animating moving markers - -## Roadmap - -For the latest roadmap, please see the [Issue Tracker] - -[Issue Tracker]: https://github.com/johnpryan/flutter_map/issues -[Leaflet]: https://leafletjs.com/ -[Mapbox]: https://www.mapbox.com/ -[azure-maps-instructions]: https://docs.microsoft.com/en-us/azure/azure-maps/quick-demo-map-app -[custom-crs-readme]: ./example/lib/pages/custom_crs/Readme.md -[flutter_map_tile_caching]: https://github.com/JaffaKetchup/flutter_map_tile_caching -[mbTilesToPngs]: https://github.com/alfanhui/mbtilesToPngs -[open-street-map]: https://openstreetmap.org -[proj4dart]: https://github.com/maRci002/proj4dart -[tilemill]: https://tilemill-project.github.io/tilemill/docs/guides/osm-bright-mac-quickstart/ -[install-tilemill]: https://tilemill-project.github.io/tilemill/docs/install/ -[ulimit-comment]: https://github.com/trentpiercy/trace/issues/1#issuecomment-404494469 -[Image.network]: https://api.flutter.dev/flutter/widgets/Image/Image.network.html -[NetworkImage-caching]: https://flutter.dev/docs/cookbook/images/network-image#placeholders-and-caching -[tilemill-homepage]: https://tilemill-project.github.io/tilemill/ +Some documentation is also provided within the code and can be view inside your favourite editor. These docs are also over at the [pub.dev package](https://pub.dev/documentation/flutter_map/latest/flutter_map/flutter_map-library.html), and can be viewed from within your favourite editor. diff --git a/example/README.md b/example/README.md index a5fd18f05..d0fcd0104 100644 --- a/example/README.md +++ b/example/README.md @@ -1,16 +1,13 @@ -# flutter_map_example +# Example Application For '[flutter_map](https://github.com/fleaflet/flutter_map)' -A new Flutter project. +Showcases functionality of the library in a neat and useful format that can be used for further API references, and just to see if you want this library for your app. -## Getting Started +See the [documentation website](https://docs.fleaflet.dev/) for more information about flutter_map. -This project is a starting point for a Flutter application. +## How To Run -A few resources to get you started if this is your first Flutter project: +To run this example application, clone this repository/directory onto your local machine. Open your emulator or connect your device, then use your IDE as you normally would, or execute `flutter clean` & `flutter run` from a terminal. Note that there are no pre-built versions available. -- [Lab: Write your first Flutter app](https://flutter.dev/docs/get-started/codelab) -- [Cookbook: Useful Flutter samples](https://flutter.dev/docs/cookbook) +## What's Inside -For help getting started with Flutter, view our -[online documentation](https://flutter.dev/docs), which offers tutorials, -samples, guidance on mobile development, and a full API reference. +Each page inside the example application usually demonstrates a specific feature. Pages can be accessed through the draw in app, and have self-explanatory names both in app and for each source code file - of which there is (mostly) one per page. diff --git a/pubspec.yaml b/pubspec.yaml index 5a8f9d8c5..476bed06c 100644 --- a/pubspec.yaml +++ b/pubspec.yaml @@ -1,7 +1,8 @@ name: flutter_map description: A versatile mapping package for Flutter, based off leaflet.js, that's simple and easy to learn, yet completely customizable and configurable. -version: 1.1.0 +version: 1.1.1 repository: https://github.com/fleaflet/flutter_map +documentation: https://docs.fleaflet.dev environment: sdk: ">=2.12.0 <3.0.0"