[ios, docs] Refresh "Adding points to a map" guide #11496
Conversation
captainbarbosa
force-pushed
the
nb-marker-guide-edits
branch
from
ce999fd
to
b4ed80c
Compare
| mapView.addAnnotation(annotation) | ||
| ``` | ||
| **MGLAnnotationImage** is an annotation class that is easily customizable with any `UIImage`. | ||
| It is highly performant, as the images are rendered directly in OpenGL. However, if you need to animate your annotations or control z-layer ordering, consider working with **MGLAnnotationView** which supports basic CALayer animations and can be stacked by using `zPosition` property on `CALayer`. |
There was a problem hiding this comment.
which supports basic CALayer animations
This could be interpreted to mean that we only support “basic CALayer animations” (which could incidentally also be confused with CABasicAnimation). MGLAnnotationView aims to support any animation that can be applied to a UIView, which could be from Core Animation/UIKit or elsewhere.
| mapView.addAnnotation(annotation) | ||
| ``` | ||
| **MGLAnnotationImage** is an annotation class that is easily customizable with any `UIImage`. | ||
| It is highly performant, as the images are rendered directly in OpenGL. However, if you need to animate your annotations or control z-layer ordering, consider working with **MGLAnnotationView** which supports basic CALayer animations and can be stacked by using `zPosition` property on `CALayer`. |
There was a problem hiding this comment.
can be stacked by using
zPositionproperty onCALayer
This property only controls ordering within an individual view. To re-order the view hierarchy, you would use methods such as -[UIView bringSubviewToFront:].
|
|
||
| See the `MGLMapViewDelegate` method `-mapView:annotationCanShowCallout:` and similar methods for allowing interaction with a callout ([example](https://www.mapbox.com/ios-sdk/examples/callout-delegate/)). | ||
| **MGLAnnotationView** is an annotation class that is easily customizable with a `UIView`. Use this class if you need your markers to be dynamic or animatable. MGLAnnotationView has a significant advantage over MGLAnnotationImage when you need every annotation to be unique. For example, annotation views are ideal for showing user locations on a map using high-resolution profile pictures. However, the map can get slow down when many annotation views are visible at the same time, so if you need to add a very large amount of markers, consider using our runtime styling APIs instead. |
There was a problem hiding this comment.
is easily customizable with a
UIView
MGLAnnotationView a subclass of UIView, so “with a” doesn’t make sense here.
|
|
||
| See the `MGLMapViewDelegate` method `-mapView:annotationCanShowCallout:` and similar methods for allowing interaction with a callout ([example](https://www.mapbox.com/ios-sdk/examples/callout-delegate/)). | ||
| **MGLAnnotationView** is an annotation class that is easily customizable with a `UIView`. Use this class if you need your markers to be dynamic or animatable. MGLAnnotationView has a significant advantage over MGLAnnotationImage when you need every annotation to be unique. For example, annotation views are ideal for showing user locations on a map using high-resolution profile pictures. However, the map can get slow down when many annotation views are visible at the same time, so if you need to add a very large amount of markers, consider using our runtime styling APIs instead. |
There was a problem hiding this comment.
the map can
getslow down
|
|
||
| ## Displaying annotations | ||
| Both MGLAnnotationImage and MGLAnnotationView can become interactive with the addition of a single line of code. When the user taps an annotation, the annotation’s name appears in a basic callout. An annotation view can additionally respond to drag-and-drop gestures. |
There was a problem hiding this comment.
a single line of code
This feels like a minor tease — “what is this line of code?”, the reader might ask. Provide a link to the API or example that’s being alluded to.
|
|
||
| ### Annotation Images (`MGLAnnotationImage`) | ||
| For absolute full control of how points are displayed on a map, consider using our [runtime styling](#) APIs. It is the most performant approach for adding hundreds of markers because markers are rendered in GL directly. The runtime styling API provides support for labels rendered together with icons, finer control of z-ordering, and clustering. |
There was a problem hiding this comment.
It is the most performant approach for adding hundreds of markers because markers are rendered in GL directly.
This sentence is a slightly differently worded version of the one in MGLAnnotationImage that uses the same explanation, without clarifying the difference/similarity. It might be good to relate Runtime Styling directly to MGLAnnotationImage, saying that both are performant because they’re “rendered directly using OpenGL”.
|
|
||
| Annotation images are the quickest and most performant way to display annotations, but are also the most basic. | ||
| If you need to implement callouts with the runtime styling API, you will need to implement your own tap gesture recognizer that calls `-[MGLMapView visibleFeaturesAtPoint:inStyleLayersWithIdentifiers:]` to get the tapped point feature, then show a UIView you provide. Additionally, if you need to animate markers when using the runtime styling APIs, consider using an NSTimer and updating the source data coordinates accordingly. |
There was a problem hiding this comment.
I’d be less specific and just say “a timer” (rather than NSTimer) or “on a timer”.
|
|
||
| By default, annotations added to the map are displayed with a red pin ([example](https://www.mapbox.com/ios-sdk/examples/marker/)). To use custom images, you can implement `MGLMapViewDelegate` `-mapView:imageForAnnotation:` ([example](https://www.mapbox.com/ios-sdk/examples/marker-image/)). | ||
| Our runtime styling API is the most powerful option if you need to create rich data visualizations within in your map. This API includes our `MGLSymbolStyleLayer` and `MGLCircleStyleLayer` classes that can be used to dynamically display on markers on map when used in conjunction with either an MGLVectorSource or an MGLShapeSource. |
There was a problem hiding this comment.
This seems to push users in the direction of RtS (of course I’m going to want the “most powerful option”), but it glosses over the relative complexity.
|
|
||
| * Annotation images are purely static and cannot be animated | ||
| * No control over z-ordering | ||
| Still undecided on which approach will work best for your use case? Reach out to our support team. |
There was a problem hiding this comment.
Reach out to our support team.
How does one do this? A link would be helpful.
|
|
||
| ### Annotation Views (`MGLAnnotationView`) | ||
| Mapbox offers a few different ways to add points to a map, each with different tradeoffs. See the table below for a summary of the different approaches: |
There was a problem hiding this comment.
Mapbox offers a few different ways to add points to a map
The opening to this sentence feels like an introduction meant for the top of the page, but perhaps not here, after the reader has already read about the different types of annotations.
There was a problem hiding this comment.
I don’t see any huge issues with the technical details, but I’ve tagged in @colleenmcginnis, as perhaps she has suggestions re: organization, flow, and/or style.
|
|
||
| ## **Runtime Styling API** | ||
|
|
||
| For absolute full control of how markers are displayed on a map, consider using our [runtime styling](#) APIs. Like `MGLAnnotationImage`, it is a performant approach to adding markers because they rendered directly using OpenGL. However, the runtime styling APIs also provide support for rendering labels together with icons, finer control of z-ordering, and clustering, so consider using this set of APIs if you need to display a large amount of highly customizable markers. |
There was a problem hiding this comment.
This link to runtime styling doesn’t currently go anywhere.
|
|
||
| The runtime styling API includes our `MGLSymbolStyleLayer` and `MGLCircleStyleLayer` classes that can be used to dynamically display on markers on map when used in conjunction with either an `MGLVectorSource` or an `MGLShapeSource`. | ||
|
|
||
| If you need to implement callouts with the `MGLSymbolStyleLayer` or `MGLCircleStyleLayer`, you will need to implement your own tap gesture recognizer that calls `-[MGLMapView visibleFeaturesAtPoint:inStyleLayersWithIdentifiers:]` to get the tapped point feature, then show a UIView you provide. Additionally, if you need to animate markers when using the runtime styling APIs, consider using an timer to update the source data coordinates accordingly. |
There was a problem hiding this comment.
Nit: put ticks around UIView.
There was a problem hiding this comment.
@captainbarbosa this looks good! I left a couple comments. We should also talk about redirecting adding-points-to-a-map to /adding-markers-to-a-map. I'll follow up with you about that.
| **MGLAnnotationImage** is an annotation class that is easily customizable with any `UIImage`. | ||
| It is highly performant, as the images are rendered directly using OpenGL. However, if you need to animate your annotations or control z-layer ordering, consider working with **MGLAnnotationView** which supports any animation that can be applied to a `UIView`. View hierarchy can also be manipulated by using `zPosition` property on `CALayer` to order an individual view, or by using other instance methods available on `UIView` such as `-[UIView bringSubviewToFront:]`. | ||
|
|
||
| **MGLAnnotationView** is an annotation class that is an easily customizable `UIView`. Use this class if you need your markers to be dynamic or animatable. `MGLAnnotationView` has a significant advantage over `MGLAnnotationImage` when you need every annotation to be unique. For example, annotation views are ideal for showing user locations on a map using high-resolution profile pictures. However, the map can slow down when many annotation views are visible at the same time, so if you need to add a very large amount of markers, consider using our runtime styling APIs instead. |
There was a problem hiding this comment.
animatable
I don't think this is a word. Either use able to be animated or maybe just animated (if that makes sense in the context).
There was a problem hiding this comment.
While not strictly a word, “animatable” is a common and well-understood term in the Apple/Cocoa ecosystem.
There was a problem hiding this comment.
(But yeah, in this case I agree that “animated” works better.)
| **MGLAnnotationImage** is an annotation class that is easily customizable with any `UIImage`. | ||
| It is highly performant, as the images are rendered directly using OpenGL. However, if you need to animate your annotations or control z-layer ordering, consider working with **MGLAnnotationView** which supports any animation that can be applied to a `UIView`. View hierarchy can also be manipulated by using `zPosition` property on `CALayer` to order an individual view, or by using other instance methods available on `UIView` such as `-[UIView bringSubviewToFront:]`. | ||
|
|
||
| **MGLAnnotationView** is an annotation class that is an easily customizable `UIView`. Use this class if you need your markers to be dynamic or animatable. `MGLAnnotationView` has a significant advantage over `MGLAnnotationImage` when you need every annotation to be unique. For example, annotation views are ideal for showing user locations on a map using high-resolution profile pictures. However, the map can slow down when many annotation views are visible at the same time, so if you need to add a very large amount of markers, consider using our runtime styling APIs instead. |
There was a problem hiding this comment.
so if you need to add a very large amount of markers
Change "amount" to "number"? (just a preference)
|
|
||
| ## **Runtime Styling API** | ||
|
|
||
| For absolute full control of how markers are displayed on a map, consider using our [runtime styling](#) APIs. Like `MGLAnnotationImage`, it is a performant approach to adding markers because they rendered directly using OpenGL. However, the runtime styling APIs also provide support for rendering labels together with icons, finer control of z-ordering, and clustering, so consider using this set of APIs if you need to display a large amount of highly customizable markers. |
There was a problem hiding this comment.
For absolute full control
This is redundant. Use either "absolute" or "full."
|
|
||
| For absolute full control of how markers are displayed on a map, consider using our [runtime styling](#) APIs. Like `MGLAnnotationImage`, it is a performant approach to adding markers because they rendered directly using OpenGL. However, the runtime styling APIs also provide support for rendering labels together with icons, finer control of z-ordering, and clustering, so consider using this set of APIs if you need to display a large amount of highly customizable markers. | ||
|
|
||
| Our runtime styling API is the most powerful option if you need to create rich data visualizations within in your map, but it is the most complex and has a steeper learning curve than our annotations API. |
There was a problem hiding this comment.
Runtime Styling API
runtime styling API
runtime styling APIs
annotations API
I'm not sure if these are specific API names or just words describing an API. If they are names they should be consistently formatted as Runtime Styling API. If not, they should be consistently formatted as runtime styling API(s) (is it one or multiple?) and the heading should be in sentence case, Runtime styling API(s).
captainbarbosa
force-pushed
the
nb-marker-guide-edits
branch
from
c490f8d
to
5565062
Compare
Including feedback edits as suggested by @friedbunny
captainbarbosa
force-pushed
the
nb-marker-guide-edits
branch
from
5565062
to
a778b8c
Compare
| | `MGLAnnotationImage` | `MGLAnnotationView` | | ||
|
|
||
| **MGLAnnotationImage** is an annotation class that is easily customizable with any `UIImage`. | ||
| It is highly performant, as the images are rendered directly using OpenGL. However, if you need to animate your annotations or control z-layer ordering, consider working with **MGLAnnotationView** which supports any animation that can be applied to a `UIView`. View hierarchy can also be manipulated by using `zPosition` property on `CALayer` to order an individual view, or by using other instance methods available on `UIView` such as `-[UIView bringSubviewToFront:]`. |
There was a problem hiding this comment.
using
zPositionproperty onCALayerto order an individual view
CALayer.zPosition manipulates the z-ordering of layers within a single view. Since we’re talking about z-ordering of views relative to other views here, let’s remove this bit.
|
|
||
| The runtime styling API includes our `MGLSymbolStyleLayer` and `MGLCircleStyleLayer` classes that can be used to dynamically display on markers on map when used in conjunction with either an `MGLVectorSource` or an `MGLShapeSource`. | ||
|
|
||
| If you need to implement callouts with the `MGLSymbolStyleLayer` or `MGLCircleStyleLayer`, you will need to implement your own tap gesture recognizer that calls `-[MGLMapView visibleFeaturesAtPoint:inStyleLayersWithIdentifiers:]` to get the tapped point feature, then show a `UIView` you provide. Additionally, if you need to animate markers when using the runtime styling APIs, consider using an timer to update the source data coordinates accordingly. |
There was a problem hiding this comment.
consider using
ana timer
This refreshes the "Adding Points to a Map" guide to include new imagery and further explanation for when to use certain classes of the Mapbox Maps SDK for iOS to add markers on a map.