diff --git a/README.md b/README.md index c13c7c01e..3909153f8 100644 --- a/README.md +++ b/README.md @@ -62,7 +62,7 @@ diverged, it has become necessary to separate the projects into specific wrapper - [SymbolLayer](/docs/components/SymbolLayer.md) - [HeatmapLayer](/docs/components/HeatmapLayer.md) -### Offline +### Modules - [OfflineManager](/docs/modules/offlineManager.md) - [SnapshotManager](/docs/modules/snapshotManager.md) @@ -70,10 +70,10 @@ diverged, it has become necessary to separate the projects into specific wrapper ### Misc - [MapLibreGL](/docs/guides/MapLibreGL.md) -- [CustomHttpHeaders](/docs/guides/CustomHttpHeaders.md) +- [Custom HTTP Headers](/docs/guides/CustomHTTPHeaders.md) - [Logger](/docs/guides/Logger.md) -## Contributing / local development +## Contributing & Development Read the [CONTRIBUTING.md](CONTRIBUTING.md) guide in order to get familiar with how we do things around here and set up your local development environment. diff --git a/docs/guides/Annotations.md b/docs/guides/Annotations.md index 0b37063e5..d1e423af1 100644 --- a/docs/guides/Annotations.md +++ b/docs/guides/Annotations.md @@ -1,12 +1,14 @@ -Comparsion of various annotations available in MapLibre React Native: +# Annotations -|*Feature* | *SymbolLayer* |*PointAnnotation* |*MarkerView* |*CircleLayer* | -|-----------------------|--------------------|--------------------------------------|-------------------------|---------------------| -|Can use images | ✓ | | | | -|RN Views as childern | iOS: static |iOS: interactive
android: static|interactive | | -|Interactions | click |iOS: full
android: click & drag & callout | supports full interactivity in the sense that inside MarkerViews one can place any RN View, which can be interacted with. Not to be misunderstood with drag n drop interactivity. | click | -|Control Z-index | ✓ |iOS: always on top, android: n/a |always on top | ✓ | -|Clustering | ✓ | | | ✓ | -|Style with expressions | ✓ | | | ✓ | -|iOS implementation | [MLNSymbolStyleLayer](https://maplibre.org/maplibre-gl-native/ios/api/Classes/MLNSymbolStyleLayer.html) |[MLNAnnotationView](https://maplibre.org/maplibre-gl-native/ios/api/Classes/MLNAnnotationView.html) |[MLNAnnotationView](https://maplibre.org/maplibre-gl-native/ios/api/Classes/MLNAnnotationView.html) |[MLNCircleStyleLayer](https://maplibre.org/maplibre-gl-native/ios/api/Classes/MLNCircleStyleLayer.html) | -|android implementation | [SymbolLayer](https://maplibre.org/maplibre-gl-native/android/api/com/mapbox/mapboxsdk/style/layers/SymbolLayer.html)|[annotation.Symbol](https://docs.mapbox.com/android/api/plugins/annotation/0.8.0/com/mapbox/mapboxsdk/plugins/annotation/Symbol.html)|[annotation.Marker](https://docs.mapbox.com/android/api/plugins/markerview/0.4.0/com/mapbox/mapboxsdk/plugins/markerview/MarkerView.html) |[CircleLayer](https://maplibre.org/maplibre-gl-native/android/api/com/mapbox/mapboxsdk/style/layers/CircleLayer.html)| +Comparison of various annotations available in MapLibre React Native: + +| Feature | `SymbolLayer` | `PointAnnotation` | `MarkerView` | `CircleLayer` | +| ---------------------- | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | +| Can use images | ✓ | | | | +| RN Views as childern | iOS: static | iOS: interactive
android: static | interactive | | +| Interactions | click | iOS: full
android: click & drag & callout | supports full interactivity in the sense that inside MarkerViews one can place any RN View, which can be interacted with. Not to be misunderstood with drag n drop interactivity. | click | +| Control Z-index | ✓ | iOS: always on top, android: n/a | always on top | ✓ | +| Clustering | ✓ | | | ✓ | +| Style with expressions | ✓ | | | ✓ | +| iOS implementation | [MLNSymbolStyleLayer](https://maplibre.org/maplibre-gl-native/ios/api/Classes/MLNSymbolStyleLayer.html) | [MLNAnnotationView](https://maplibre.org/maplibre-gl-native/ios/api/Classes/MLNAnnotationView.html) | [MLNAnnotationView](https://maplibre.org/maplibre-gl-native/ios/api/Classes/MLNAnnotationView.html) | [MLNCircleStyleLayer](https://maplibre.org/maplibre-gl-native/ios/api/Classes/MLNCircleStyleLayer.html) | +| android implementation | [SymbolLayer](https://maplibre.org/maplibre-gl-native/android/api/com/mapbox/mapboxsdk/style/layers/SymbolLayer.html) | [annotation.Symbol](https://docs.mapbox.com/android/api/plugins/annotation/0.8.0/com/mapbox/mapboxsdk/plugins/annotation/Symbol.html) | [annotation.Marker](https://docs.mapbox.com/android/api/plugins/markerview/0.4.0/com/mapbox/mapboxsdk/plugins/markerview/MarkerView.html) | [CircleLayer](https://maplibre.org/maplibre-gl-native/android/api/com/mapbox/mapboxsdk/style/layers/CircleLayer.html) | diff --git a/docs/guides/CustomHttpHeaders.md b/docs/guides/CustomHTTPHeaders.md similarity index 61% rename from docs/guides/CustomHttpHeaders.md rename to docs/guides/CustomHTTPHeaders.md index e4890c876..d3c419b1b 100644 --- a/docs/guides/CustomHttpHeaders.md +++ b/docs/guides/CustomHTTPHeaders.md @@ -1,23 +1,23 @@ -## Custom http headers +# Custom HTTP Headers -### Intro +## Intro -Custom headers are implemented using OkHttp interseptor for android and method swizzling for iOS. +Custom headers are implemented using OkHttp interceptor for android and method swizzling for iOS. [Method swizzling](https://en.wikipedia.org/wiki/Monkey_patch) is done on the `[NSMutableURLRequest requestWithURL:]` to allow adding headers during runtime. -### Prerequisites +## Prerequisites -#### Android +### Android None -#### IOS +### iOS To enable this on iOS you need to call `[[MLRNCustomHeaders sharedInstance] initHeaders]` pretty early in the lifecycle of the application. This will swizzle the custom method. Suggested location is `[AppDelegate application: didFinishLaunchingWithOptions:]` -#### Working example (AppDelegate.m) +### Working Example `AppDelegate.m` ```obj-c // (1) Include the header file @@ -45,43 +45,34 @@ Suggested location is `[AppDelegate application: didFinishLaunchingWithOptions:] @end ``` -### Sending custom http headers with the tile requests +## Sending custom HTTP Headers with the Tile Requests -You can configure sending of custom http headers to your tile server. This is to support custom authentication or custom metadata which can't be included in the url. +You can configure sending of custom HTTP headers to your tile server. This is to support custom authentication or custom metadata which can't be included in the url. You can add and remove headers at runtime. -#### To add a header +### Adding a Header ```javascript - MapLibreGL.addCustomHeader('Authorization', '{auth header}'); +MapLibreGL.addCustomHeader("Authorization", "{auth header}"); ``` -#### To remove a header +### Removing a Header ```javascript - MapLibreGL.removeCustomHeader('Authorization'); +MapLibreGL.removeCustomHeader("Authorization"); ``` -#### Working example +### Working Example ```javascript -export default class HelloWorldApp extends Component { - componentDidMount () { - MapLibreGL.addCustomHeader('Authorization', '{auth header}'); - } - - render () { - MapLibreGL.addCustomHeader('X-Some-Header', 'my-value'); - return ( - - - - - - ); - } +export default function App() { + useEffect(() => { + MapLibreGL.addCustomHeader("Authorization", "{auth header}"); + }, []); + + MapLibreGL.addCustomHeader("X-Some-Header", "my-value"); + + return ; } ``` diff --git a/docs/guides/Logger.md b/docs/guides/Logger.md index c7c5f2fca..8c1a0b276 100644 --- a/docs/guides/Logger.md +++ b/docs/guides/Logger.md @@ -1,23 +1,23 @@ -## Logger -### +# Logger -### methods -#### setLogLevel(LogLevel) +## Methods -##### arguments -| Name | Type | Required | Description | -| ---- | :--: | :------: | :----------: | -| `LogLevel` | `String` | `Yes` | required level of logging, can be `"error" | "warning" | "info" | "debug" | "verbose"` | +### `setLogLevel(LogLevel)` -##### Description -sets the amount of logging +Sets the amount of logging. -#### setLogCallback(LogCallback) +#### Arguments -##### arguments -| Name | Type | Required | Description | -| ---- | :--: | :------: | :----------: | -| `LogCallback` | `function` | `Yes` | callback taking a log object `{ message: String, level: LogLevel, tag: String }` as param. If callback return falsy value then default logging will take place. | +| Name | Type | Required | Description | +| ---------- | :------: | :------: | :----------------------------------------: | --------- | ------ | ------- | ---------- | +| `LogLevel` | `String` | `Yes` | required level of logging, can be `"error" | "warning" | "info" | "debug" | "verbose"` | -##### Description -overwrite logging - good to mute specific errors/ warnings \ No newline at end of file +### `setLogCallback(LogCallback)` + +Overwrite logging, possibility to mute specific errors/warnings. + +#### Arguments + +| Name | Type | Required | Description | +| ------------- | :--------: | :------: | :-------------------------------------------------------------------------------------------------------------------------------------------------------------: | +| `LogCallback` | `function` | `Yes` | callback taking a log object `{ message: String, level: LogLevel, tag: String }` as param. If callback return falsy value then default logging will take place. | diff --git a/docs/guides/MapLibreGL.md b/docs/guides/MapLibreGL.md index c93c8dad9..f93e5b097 100644 --- a/docs/guides/MapLibreGL.md +++ b/docs/guides/MapLibreGL.md @@ -1,65 +1,59 @@ -## MapLibreGL -### +# MapLibreGL -### methods -#### setAccessToken(accessToken) +## Methods -##### arguments -| Name | Type | Required | Description | -| ---- | :--: | :------: | :----------: | -| `accessToken` | `String` | `Yes` | access token to pull Mapbox-hosted tiles; can be `null` for other tile hosts | +### `setAccessToken(accessToken)` -##### Description sets the accessToken, which is required when you want to use mapbox tiles not required when using other tiles -#### getAccessToken() +#### Arguments -##### arguments -| Name | Type | Required | Description | -| ---- | :--: | :------: | :----------: | -| `accessToken` | `String` | `Yes` | access token to pull Mapbox-hosted tiles; can be `null` if for other tile hosts | +| Name | Type | Required | Description | +| ------------- | :------: | :------: | :--------------------------------------------------------------------------: | +| `accessToken` | `String` | `Yes` | access token to pull Mapbox-hosted tiles; can be `null` for other tile hosts | + +### `getAccessToken()` -##### Description gets the accessToken +#### Arguments + +| Name | Type | Required | Description | +| ------------- | :------: | :------: | :-----------------------------------------------------------------------------: | +| `accessToken` | `String` | `Yes` | access token to pull Mapbox-hosted tiles; can be `null` if for other tile hosts | -#### addCustomHeader(headerName, headerValue) +### `addCustomHeader(headerName, headerValue)` -##### arguments -| Name | Type | Required | Description | -| ---- | :--: | :------: | :----------: | -| `headerName` | `String` | `Yes` | name for customHeader | -| `headerValue` | `String` | `Yes` | value for customHeader | +#### Arguments -##### Description -also see [CustomHttpHeaders](/docs/guides/CustomHttpHeaders.md) +also see [Custom HTTP Headers](/docs/guides/CustomHTTPHeaders.md) +| Name | Type | Required | Description | +| ------------- | :------: | :------: | :--------------------: | +| `headerName` | `String` | `Yes` | name for customHeader | +| `headerValue` | `String` | `Yes` | value for customHeader | -#### removeCustomHeader(headerName) +### `removeCustomHeader(headerName)` -##### arguments -| Name | Type | Required | Description | -| ---- | :--: | :------: | :----------: | -| `headerName` | `String` | `Yes` | name of customHeader to be removed | +Also see [Custom HTTP Headers](/docs/guides/CustomHTTPHeaders.md) -##### Description -also see [CustomHttpHeaders](/docs/guides/CustomHttpHeaders.md) +#### Arguments +| Name | Type | Required | Description | +| ------------ | :------: | :------: | :--------------------------------: | +| `headerName` | `String` | `Yes` | name of customHeader to be removed | -### Android only -#### requestAndroidLocationPermissions() -##### Description -Opens Android Location Permission prompt. -Returns a Promise which resolves into a boolean. -Either permission was granted or denied. +### `requestAndroidLocationPermissions()` +Android only, opens Location Permission prompt. Returns a Promise which resolves into a boolean. Either permission was granted or denied. -#### setConnected(connected) -##### arguments -| Name | Type | Required | Description | -| ---- | :--: | :------: | :----------: | -| `connected` | `Boolean` | `Yes` | whether or not the SDK should assume it is online | +### `setConnected(connected)` -#### Description If you want to fully block map tile requests over the network, such as for a low-data / offline application. + +#### arguments + +| Name | Type | Required | Description | +| ----------- | :-------: | :------: | :-----------------------------------------------: | +| `connected` | `Boolean` | `Yes` | whether or not the SDK should assume it is online | diff --git a/docs/guides/setup/GettingStarted.md b/docs/guides/setup/GettingStarted.md index 6854defff..9835338f8 100644 --- a/docs/guides/setup/GettingStarted.md +++ b/docs/guides/setup/GettingStarted.md @@ -45,48 +45,24 @@ npm install @maplibre/maplibre-react-native --save Check out the installation guide(s) for additional information about platform-specific setup, quirks, and steps required before running. -- [Android](/docs/guides/setup/Android) -- [iOS](/docs/guides/setup/iOS) -- [Expo](/docs/guides/setup/Expo) +- [Android](/docs/guides/setup/Android.md) +- [iOS](/docs/guides/setup/iOS.md) +- [Expo](/docs/guides/setup/Expo.md) ## Adding a map -Here is an example minimal App.js +Here is an example minimal `App.tsx`: -```js -import React, {Component} from 'react'; -import {StyleSheet, View} from 'react-native'; -import MapLibreGL from '@maplibre/maplibre-react-native'; +```tsx +import React from "react"; +import MapLibreGL from "@maplibre/maplibre-react-native"; // Will be null for most users (only Mapbox authenticates this way). // Required on Android. See Android installation notes. MapLibreGL.setAccessToken(null); -const styles = StyleSheet.create({ - page: { - flex: 1, - justifyContent: 'center', - alignItems: 'center', - backgroundColor: '#F5FCFF', - }, - map: { - flex: 1, - alignSelf: 'stretch', - }, -}); - -export default class App extends Component { - render() { - return ( - - - - ); - } +export default function App() { + return ; } ```