[ios] Adds guides to documentation sidebar by ericrwolfe · Pull Request #7488 · mapbox/mapbox-gl-native

ericrwolfe · 2016-12-20T00:59:31Z

3 guides to start, focused around runtime styling:

Clarity on the different ways to add points to a map
Overview of runtime styling
Prototyping runtime styling with Mapbox Studio

Also improves the way we organize guides and documentation images in the repo.

We should think about a good way to share these between the SDK docs and the /help section of the website.

TODO:

Add example gifs in Runtime Styling Overview for annotations, interactivity, and custom shapes
Update links to examples on the website

/cc @friedbunny @captainbarbosa @1ec5

mention-bot · 2016-12-20T00:59:32Z

@ericrwolfe, thanks for your PR! By analyzing this pull request, we identified @friedbunny, @incanus and @1ec5 to be potential reviewers.

1ec5

Wow, I’m excited about these guides! This will go a long way towards helping developers move beyond MapKit-style, Core Graphics–based customization.

We’ll need to be careful about how we explain the pros and cons of the three different ways to present point data to the user.

1ec5 · 2016-12-20T19:35:46Z

 The Mapbox iOS SDK is an open-source framework for embedding interactive map views with scalable, customizable vector maps into Cocoa Touch applications on iOS 7.0 and above using Objective-C, Swift, or Interface Builder. It takes stylesheets that conform to the [Mapbox Style Specification](https://www.mapbox.com/mapbox-gl-style-spec/), applies them to vector tiles that conform to the [Mapbox Vector Tile Specification](https://www.mapbox.com/developers/vector-tiles/), and renders them using OpenGL.

-![Mapbox iOS SDK screenshots](screenshot.png)
+![Mapbox iOS SDK screenshots](img/screenshot.png)


Also update platform/ios/README.md (shown on GitHub) and platform/ios/docs/pod-README.md (bundled with the SDK as README.md and also shown on CocoaPods.org).

1ec5 · 2016-12-20T19:45:10Z

+* Custom, native UIViews
+* Full support for animations
+* Familiar API to MapKit
+* Relative control over z-ordering using the `zPosition` property on `CALayer`


Another benefit is that there’s no limit to the number or size of the images you put in annotation views. The way I like to think about it is that non-view-backed annotations are optimized for extreme reuse, whereas view-backed annotations are better for situations where every annotation is unique. ❄️

Here’s a good opportunity to include a bulleted list of concrete scenarios that would be best served by annotation views (and likewise for the other two APIs). For example:

You want to display all your users’ locations on the map with their profile pictures. Each user has a different picture. Tapping on a user brings up their profile.

1ec5 · 2016-12-20T19:55:54Z

+**Cons**
+
+* Currently you must implement your own tap gesture recognizer together with `MGLMapView.visibleFeaturesAtPoint` to recognize taps and manually show callouts ([example](http://mapbox.com/ios-sdk/examples)).
+* Currently no SDK support for animations. If you need animations, consider running your own CADisplayLink and updating the layer properties accordingly.


Is CADisplayLink a good idea here? MGLMapView already uses a CADisplayLink to tie its own refresh rate to that of the screen, so I wonder whether there would be any interplay between the two. CADisplayLink is also a tricky class to work with; it’s easy to end up leaking memory. Maybe using an NSTimer would be better advice.

1ec5 · 2016-12-20T19:59:11Z

+
+### Map interactivity 
+
+You can customize the map to the point of having it respond dynamically based on the actions your users are taking. Increase the text size of streets while a user is driving, emphasize points of interest tailored a user's preferences, change your UI if user are near parks, trails, landmarks, or rivers. 


Typo: “tailored a user’s preferences”.

1ec5 · 2016-12-20T20:00:33Z

+![population](img/runtime-styling/Population.gif "an example showing population density")
+![snow levels](img/runtime-styling/SnowLevels.gif "an example visualizing snow levels in the mountains")
+
+### Powerful Annotations


Section headings in the API reference pages use title case, for consistency with Apple documentation. Most of the section headings here use sentence case, but “Powerful Annotations” is in title case. I’d be in favor of switching to sentence case across the board, but for now let’s be consistent within guides with either sentence or title case.

1ec5 · 2016-12-20T20:01:35Z

+## Resources
+
+* [Mapbox style spec](https://www.mapbox.com/mapbox-gl-style-spec/)
+* [Mapbox studio](https://www.mapbox.com/mapbox-studio/)


Capitalize “Mapbox Style Specification” and “Mapbox Studio”.

1ec5 · 2016-12-20T20:02:18Z

+For example, if you're looking to prototype points of interest, consider the `poi_label` layer; if you want to style GPS traces, the `roads` layer might be a good proxy. Take a look at what's available in [Mapbox Streets](https://www.mapbox.com/studio/tilesets/mapbox.mapbox-streets-v7/): there's probably a layer that closely matches your data.
+
+### Importing real data
+If you can't find a good approximate for your data in Mapbox Streets, consider uploading a small subset of your data into Mapbox Studio as a custom tileset. 


s/approximate/approximation/

1ec5 · 2016-12-20T20:05:43Z

+### Faking placeholder data
+If you don't have any custom data on hand in a format that works easily with the Tileset importer, you can fake placeholder data with the Dataset Editor.
+
+Head to [mapbox.com/studio/dataset](https://www.mapbox.com/studio/datasets/) and click on `New Dataset` to get started.


Instead of inlining the URL, perhaps we could explain how to get to this page.

1ec5 · 2016-12-20T20:07:21Z

+
+* Text along a line: add line with a text property
+* Text at specific points on a line or polygon: in addition to the line, create points at the specific points you'd like with text properties
+* If you want circles where scale doesn't matter relative to the geography (e.g. always 20 pixels), you can add as a point and style with a circle layer or a symbol


This might be a good opportunity to relate geometry types to specific MGLShape or MGLFeature classes, since the developer may need to create these shapes programmatically after they’re done prototyping in Studio.

I think this would be a great idea for another guide 😄.

1ec5 · 2016-12-24T01:51:42Z

@@ -0,0 +1,56 @@
+# Dynamically Styling Maps


The name of this file determines what appears in the navigation sidebar, so it and this heading should match.

1ec5

A couple things I didn’t notice originally. I’d also appreciate any feedback on how we can make the guides here and in #7542 fit together well.

1ec5 · 2017-01-04T02:14:02Z

@@ -0,0 +1,57 @@
+# Runtime Styling
+
+Mapbox's runtime styling features allow you direct control over every layer in your maps with code. It's now possible create dynamic maps and visualizations that aren't possible with other mobile maps SDKs.


Typo: now possible to create.

Also, “mobile map SDKs” sounds slightly better.

1ec5 · 2017-01-04T02:15:31Z

+
+<!-- TODO: custom storm tracks -->
+<!-- TODO: metro system -->
+<!-- TODO: indoor maps -->


Can you replace or remove these TODOs as tail work?

1ec5 · 2017-01-04T02:17:22Z

+1. Implement `MGLMapViewDelegate` `-mapView:didFinishLoadingStyle:`
+2. Add your real data as a source
+    * This can be done using vector data from tileset editor ([example](https://www.mapbox.com/ios-sdk/examples/runtime-circle-styles)), custom vector tiles, added as GeoJSON ([example](https://www.mapbox.com/ios-sdk/examples/runtime-add-line), or added manually through the app via `MGLShapeSource` ([example](https://www.mapbox.com/ios-sdk/examples/runtime-multiple-annotations))
+3. For each layer you've prototyped in studio, add it's corresponding `MGLStyleLayer` subclass: `MGLSymbolStyleLayer`, `MGLLineStyleLayer`, `MGLFillStyleLayer`, or `MGLCircleStyleLayer`.


#7542 will end up linking this page to the new “Information for Style Authors” guide.

Not sure if you meant to link to the Mapbox Studio guide from #7542 or vise versa. I rebased, so feel free to update as you intended.

ericrwolfe · 2017-01-04T19:37:52Z

Added these extra changes over in #7542.

ericrwolfe added documentation iOS Mapbox Maps SDK for iOS runtime styling ⚠️ DO NOT MERGE Work in progress, proof of concept, or on hold labels Dec 20, 2016

ericrwolfe added this to the ios-v3.4.0 milestone Dec 20, 2016

ericrwolfe self-assigned this Dec 20, 2016

1ec5 reviewed Dec 20, 2016

View reviewed changes

1ec5 reviewed Dec 24, 2016

View reviewed changes

1ec5 mentioned this pull request Dec 24, 2016

Guides for style and GeoJSON authors #7542

Merged

ericrwolfe added 4 commits January 3, 2017 11:08

Initial set of guides focused on runtime styling

e8f6fbb

Tweaks to guides

f4916e2

Added custom annotation example gif

66a8e94

Add example links and tweak guide content

2497f4e

ericrwolfe force-pushed the erw-jazzy-guides branch from 7e2fea7 to 2497f4e Compare January 3, 2017 19:50

ericrwolfe removed the ⚠️ DO NOT MERGE Work in progress, proof of concept, or on hold label Jan 3, 2017

ericrwolfe merged commit 01717af into release-ios-v3.4.0 Jan 3, 2017

1ec5 reviewed Jan 4, 2017

View reviewed changes

jfirebaugh deleted the erw-jazzy-guides branch January 5, 2017 00:08


		### Map interactivity

		You can customize the map to the point of having it respond dynamically based on the actions your users are taking. Increase the text size of streets while a user is driving, emphasize points of interest tailored a user's preferences, change your UI if user are near parks, trails, landmarks, or rivers.

		@@ -0,0 +1,57 @@
		# Runtime Styling

		Mapbox's runtime styling features allow you direct control over every layer in your maps with code. It's now possible create dynamic maps and visualizations that aren't possible with other mobile maps SDKs.

Conversation

ericrwolfe commented Dec 20, 2016 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mention-bot commented Dec 20, 2016

Uh oh!

1ec5 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

1ec5 Dec 20, 2016 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

1ec5 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ericrwolfe commented Jan 4, 2017

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

ericrwolfe commented Dec 20, 2016 •

edited

Loading

1ec5 Dec 20, 2016 •

edited

Loading