Skip to content

Commit

Permalink
docs: cleanup guides
Browse files Browse the repository at this point in the history
  • Loading branch information
@KiwiKilian
KiwiKilian committed Dec 3, 2024
1 parent d7ed017 commit 163e583
Show file tree
Hide file tree
Showing 6 changed files with 100 additions and 137 deletions.
6 changes: 3 additions & 3 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -62,18 +62,18 @@ 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)

### 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.
Expand Down
24 changes: 13 additions & 11 deletions docs/guides/Annotations.md
View file
Original file line number Diff line number Diff line change
@@ -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 <br/> android: static|interactive | |
|Interactions | click |iOS: full <br/> 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 | &check; |iOS: always on top, android: n/a |always on top | &check; |
|Clustering | &check; | | | &check; |
|Style with expressions | &check; | | | &check; |
|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 | &check; | | | |
| RN Views as childern | iOS: static | iOS: interactive <br/> android: static | interactive | |
| Interactions | click | iOS: full <br/> 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 | &check; | iOS: always on top, android: n/a | always on top | &check; |
| Clustering | &check; | | | &check; |
| Style with expressions | &check; | | | &check; |
| 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) |
53 changes: 22 additions & 31 deletions docs/guides/CustomHttpHeaders.md → docs/guides/CustomHTTPHeaders.md
View file
Original file line number Diff line number Diff line change
@@ -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
Expand Down Expand Up @@ -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 (
<View style={styles.page}>
<View style={styles.container}>
<MapLibreGL.MapView
style={styles.map}
styleURL={STYLE_URL}/>
</View>
</View>
);
}
export default function App() {
useEffect(() => {
MapLibreGL.addCustomHeader("Authorization", "{auth header}");
}, []);

MapLibreGL.addCustomHeader("X-Some-Header", "my-value");

return <MapLibreGL.MapView style={{flex: 1}} />;
}
```
34 changes: 17 additions & 17 deletions docs/guides/Logger.md
View file
Original file line number Diff line number Diff line change
@@ -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
### `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. |
78 changes: 36 additions & 42 deletions docs/guides/MapLibreGL.md
View file
Original file line number Diff line number Diff line change
@@ -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 |
42 changes: 9 additions & 33 deletions docs/guides/setup/GettingStarted.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 (
<View style={styles.page}>
<MapLibreGL.MapView
style={styles.map}
logoEnabled={false}
styleURL="https://demotiles.maplibre.org/style.json"
/>
</View>
);
}
export default function App() {
return <MapLibreGL.MapView style={{ flex: 1 }} />;
}
```

Expand Down

0 comments on commit 163e583

Please sign in to comment.