Better examples

[owenson]

It would be great to see some more detailed examples on the website.

For example, how to add the LocationComponent / puck, waypoints, right click menus, offline maps combined with GeoJSON, etc.

Would love to use the library but piecing together working code from the API docs is quite painful.

best wishes

[louwers]

@owenson

You mention:

• LocationComponent / puck
• waypoints
• right click menus
• offline maps combined with GeoJSON

Could you write a few sentences for each of these what you expect an example to cover? Which platform(s) are you interested in?

Then we can create issues for each of your suggestions.

[louwers]

These examples can probably be re-used.

https://github.com/mapbox/ios-sdk-examples

[wipfli]

The Amazon Location Samples are also published under a permissive license (MIT): https://github.com/aws-samples/amazon-location-samples

[ovivoda]

These examples can probably be re-used.

https://github.com/mapbox/ios-sdk-examples

do we need to ask for permission here @wipfli ? Do you know?

[louwers]

@ovivoda No copyright. So, no!

[wipfli]

These Mapbox iOS examples are CC0, see https://github.com/mapbox/ios-sdk-examples/blob/main/LICENSE.md. Practically this means we can use the examples on our docs website without attribution. When forking the examples, we are still going to keep the original License and will just add MapLibre contributors to the top. See other repos for how we did it...

[louwers]

Good news: some issues (with bounties) for a Getting Started guide, adding annotations and showing the current location for both platforms were just created.

Please feel free to share more ideas for examples here (but write one or two sentences with what the example should cover).

[louwers]

What should a minimal example of Offline support demonstrate? Then we can create issues for iOS and Android.

[lepigocher]

As suggested by Bart (@louwers), I start to submit ideas for future samples on Android (of course, they should also be useful for iOS)

1) In the documentation, I have been able to found that we can apply map options (https://maplibre.org/maplibre-native/android/api/-map-libre%20-native%20-android/org.maplibre.android.maps/-map-libre-map-options/index.html).

From the documentation: Defines configuration MapLibreMapOptions for a MapLibreMap. These options can be used when adding a map to your application programmatically (as opposed to via XML). If you are using a MapFragment, you can pass these options in using the static factory method newInstance(MapLibreMapOptions). If you are using a MapView, you can pass these options in using the constructor MapView(Context, MapLibreMapOptions). If you add a map using XML, then you can apply these options using custom XML tags.

Great, but without a few sample code (XML, programmatically, etc) this is not really usefull. If I want to use XML, is it another tag included in the tag <org.maplibre.android.maps.MapView ... /> or an attribute or something else? Because I'm a Kotlin/Android Platform beginner, I have no idea on how to add a map programmatically to an Activity! Moreover, I have not been able to found the factory method mentioned. We don't need a full app to show these cases, just a sample app using map options. Using XML declaration and code commented method to use the programmatic method. Of course, the same app can be used to demonstrate something more complicated! Like what comes next... ;-)

2) How to add programmaticaly a full dataset on the map (GeoJson data, layers with styles)? This is a very common case to add some dynamic data to a map and most of times GeoJson is used instead to create a second pyramid using MBTiles format.

I found the class to access a GeoJson file but it seems that some constructor signatures are deprecated. The documentation should reflect what is marked as deprecated in the code. From Android Studio: 'constructor GeoJsonSource(String?, URL)' is deprecated. use {@link #GeoJsonSource(String, URI)} instead'

val sourceURI = URI("https://mydomain.tld/myfile.geojson")
val mySource = GeoJsonSource("myGeojsonId", sourceURI)

Then I searched to create a layer for my lines from the file and I found under the namespace 'org.maplibre.android.style.layers' the class... LineLayer!

val myLineLayer = LineLayer("myLineLayerId", "myGeojsonId")

It was at this precise moment that the real problems began. Strictly no information on how to apply styles as I know how to do it with the JS version! There is a function 'getLineColor' but not equivalent (setLineColor) to define the color of the lines while there is a function 'setLineColorTransition'. So I can change the line display transition on the fly but not the color?
Of course not, but it took me a looonnngggg moment to figure out that I had to use the 'setProperties' function and a lot, much, much longer to figure out how to set an expression!
After a full day of work and a lot of reading in the source code, the API documentation AND all the samples from Mapbox! I have been able to write ~30 lines of code to show some lines in red from a GeoJson file. Not really efficient!

myLineLayer.setProperties(
	lineColor("#c82424"),
	lineWidth(
		interpolate(
			linear(), zoom(),
			stop(0F, 0.5F),
			stop(20F, 2F),
			stop(23F, 10F)
		)
	)
)

It's not really 'dynamic'. I don't know if something exists in the API to directly read and parse json style to create a layer. And I'm far than what I have been able to do with the JS version! Additionally, by showing how to do it for lines it would be easy for the reader to infer how to do it for circles and all other layer types.

So, having a sample app showing how to create a map from a background style (OSM) and how to add GeoJson source with styles will be really helpful to a lot of beginners like me.

3) How to create a simple control like the compass?

Creating a simple control like this would help to understand how to do this. I understood that the team in charge of the native version did not want to implement as many controls present in the JS version or at least do it in a separate project?
This will be valuable to understand how to get a reference to the underlying map, how to receive events and so on...

[lepigocher]

Another suggestion. It could be great to have a full sample with explanations about the offline manager. I have been able to find the test classes (https://github.com/maplibre/maplibre-native/tree/1df592c9e1d80b1ad5ec92be4c3cbba276b60d2c/platform/android/MapLibreAndroidTestApp/src/androidTest/java/org/maplibre/android/testapp/offline) but this is not obvious to understand when I should use the offline manager and when I should't. How to use it, what can I store inside, how it works in general and so on...

[lepigocher]

Another one! Is it possible to load several style on the same map like with the JS version? If yes, it could be a complement to the sample about GeoJson because it could help someone having already defined json styles to load and apply them dynamicaly. This way we could load one dataset as GeoJson and change style on the fly (day/night, different colors for visual effects, ...).

[louwers]

Yep this works.

[lepigocher]

What a good news! :) I will try to do it.

[lepigocher]

Another one! I found a class 'org.maplibre.android.geometry' in namespace 'VisibleRegion'. The explanation provided in the header seems to suit what I'm trying to do. Namely constraining movements on the map in relation to a 'bounding box'. With the JS version, just set the maxBounds property of the map options. But I didn't find anything similar with the native version.
I found the 'setLatLngBoundsForCameraTarget' function of the 'MapLibreMap' class but it is not exactly the same, the movement limits seem relative to the center of the map. In short, an example allowing you to constrain the display would be very useful.

[louwers]

There is an example of this in the example app. However, it doesn't constrain the screen, it constrains the center point.

There is an open PR to add functionality to constrain the screen bounds like in MapLibre GL JS. #2475

[lepigocher]

Thanks, I hope this will be in the next release.

[lepigocher]

Again! I found the class attributionDialogManager but I have no idea on how to use it. What I try to do is replace/complete the text from the attribution dialog and or manage a click on the control to show a full page with all attributions. With the JS version I do no show the attribution dialog but provide a full page with all attributions related to components, map (OSM), style sources, fonts used and so on...

[louwers]

Thank you for sharing your ideas! I have created issues for each. I'll be working with developers from the community to work on these and other examples.

[louwers]

I plan to make a separate docs site for documenting Android Examples based on MkDocs. Right now it is included in the mdbook which also contains architectural documentation of the core, but I don't think this is a good place because that information is not be relevant to the majority of Android users.

MkDocs is also used by MapLibre GL JS and the MapLibre Style Specification so it is nice to have some consistency. I found out that it also has great support for including snippets of code from other files (example below). This will be very helpful for the example documentation because we already have a lot of code in the Android test app.

## Setting Water Color

This example shows how the [fill layer](https://maplibre.org/maplibre-style-spec/layers/#fill) for water is retrieved and its fill color is changed at runtime.

```kotlin
--8<-- "activity/style/RuntimeStyleActivity.kt:setWaterColor"
```

Feedback welcome.

[ianthetechie]

I approve of this direction. It's always been confusing having core and Android docs in the same place.