[WIP] update iOS SDK guides #8354

jmkiley · 2017-03-10T19:33:50Z

Update the For Style Authors guide to include DDS related terminology
Add a data-driven styling guide.
~~- [ ] Update Runtime Styling guide as necessary~~

The data-driven styling guide currently includes more code than the other previous guides, and may be more tutorial. It is intended to illustrate the differences between the different interpolation modes and how to use them, but it can be trimmed down.

Intended to partially address #8192 and the last two items on #7924.

1ec5 · 2017-03-10T22:33:24Z

platform/ios/docs/guides/For Style Authors.md

-you want the attribute to be set to.
+constant values) or an `MGLStyleFunction` subclass. The style value object is a
+container for the raw value or function parameters that you want the attribute
+to be set to.


Setting style functions is a subtask of configuring the map content’s appearance. I think the table mapping function types to MGLStyleFunction subclasses and MGLInterpolationMode values should be moved down here, to help progress the reader from simpler concepts to more advanced concepts.

I agree. Especially since the tables currently repeat for each property.

1ec5 · 2017-03-10T22:33:57Z

platform/ios/docs/guides/For Style Authors.md

+`exponential`                | `MGLInterpolationModeExponential`
+`interval`                   | `MGLInterpolationModeInterval`
+`categorical`                | `MGLInterpolationModeCategorical`
+`identity`                   | `MGLInterpolationModeIdentity`


Let’s split up this table into two: one for function types and the other for interpolation modes.

1ec5 · 2017-03-10T22:34:38Z

platform/ios/docs/guides/For Style Authors.md

+`zoom function`              | `MGLCameraStyleFunction`
+`property function`          | `MGLSourceStyleFunction`
+`zoom-and-property functions`| `MGLCompositeStyleFunction`
+`type`                       | `MGLInterpolationMode`


This is also a terminological difference. It’s worth mentioning that a “function type” is an “interpolation mode” up in the first table.

1ec5 · 2017-03-10T22:35:03Z

platform/ios/docs/guides/For Style Authors.md

+introduces `MGLInterpolationMode`. Individual style property documentation
+includes which subclasses of `MGLStyleFunction` are enabled for that property.
+
+In style JSON                | In the SDK


Function types (“zoom”, “property”, “zoom-and-property”) don’t appear in the style JSON, only in the style specification.

1ec5 · 2017-03-10T22:36:56Z

platform/ios/docs/guides/Data-Driven Styling.md

+            let source = MGLShapeSource(identifier: "earthquakes", url: url, options: nil)
+            style.addSource(source)
+
+            let stops = [0 : MGLStyleValue(rawValue: UIColor.yellow),


We could make this guide platform-agnostic, either by replacing UIColor with some other type like NSNumber that also exists on macOS, or by relying on type inference in Swift and the MGLColor macro in Objective-C. Then we could move this guide to platform/darwin/docs/guides/.

MGLColor is a fine internal workaround, but I don’t believe we’ve encouraged its use publicly(?). Telling developers to use MGLColor has a couple issues:

It’s not necessary for the vast majority of our developers (who are iOS-only).

MGLColor’s purpose and action is opaque — actually using it has no technical downside, but the cognitive burden of learning what it is isn’t negligible. I’d expect a significant portion of our users to just assume that it’s the required way to define colors and not understand why that’s not the case.

At this point, I think it’s more reasonable to expect macOS developers to know UIColor doesn’t exist on that platform, rather than asking iOS developers to use a macro they don’t need.

Definitely onboard with consistently using type inference in Swift, though.

Point taken about MGLColor being pedagogically problematic. In the Mapbox API Documentation examples in Objective-C, I took to using conditional compilation macros, which are better documented but even more poorly understood by less experienced developers.

What about bringing this guide under the same codegen mechanism that the “Information for Style Authors” guide uses?

Move this guide to platform/darwin/docs/guides/Data-Driven Styling.md.ejs.

Define a cocoaPrefix variable at the top.

Put a <% cocoaPrefix %> variable anywhere we’re currently saying UI.

Extend generate-style-code.js to also write out iOS- and macOS-specific versions of the guide.

Run make style-code.

With this approach, the style-related guides would be more consistent with each other even at the code level. Additionally, it’ll give us the ability to put some of these (rather substantial) code examples in unit tests and insert them into this document automatically, ensuring that the examples stay current. We already use that approach for examples embedded in API documentation.

1ec5 · 2017-03-10T22:37:05Z

platform/ios/docs/guides/For Style Authors.md

@@ -28,7 +28,7 @@ make sure the contents of these elements remain legible with the map view
 underneath.
 The user location annotation view, the attribution button, any buttons in
 callout views, and any items in the navigation bar are influenced by your
-application’s tint color, so choose a tint color that constrasts well with your
+application’s tint color, so choose a tint color that contrasts well with your


Good catch.

1ec5 · 2017-03-10T22:38:22Z

platform/ios/docs/guides/For Style Authors.md

+# Style functions and interpolation mode
+
+The runtime styling API introduced `MGLStyleFunction` to the iOS SDK.
+[Data-driven styling](data-driven-styling.html) expands `MGLStyleFunction` and


Since the DDS guide currently lives in platform/ios/docs/guides/, this link is broken in the macOS generated documentation. https://github.com/mapbox/mapbox-gl-native/pull/8354/files#r105503718 would be preferable, but if we can’t do that, then we should conditionalize this sentence on the platform. There are some examples above of only including a sentence on iOS or only on macOS.

friedbunny · 2017-03-10T22:57:28Z

platform/ios/docs/guides/Data-Driven Styling.md

+            let source = MGLShapeSource(identifier: "earthquakes", url: url, options: nil)
+            style.addSource(source)
+
+            let stops = [0 : MGLStyleValue(rawValue: UIColor.yellow),


MGLColor is a fine internal workaround, but I don’t believe we’ve encouraged its use publicly(?). Telling developers to use MGLColor has a couple issues:

It’s not necessary for the vast majority of our developers (who are iOS-only).

MGLColor’s purpose and action is opaque — actually using it has no technical downside, but the cognitive burden of learning what it is isn’t negligible. I’d expect a significant portion of our users to just assume that it’s the required way to define colors and not understand why that’s not the case.

At this point, I think it’s more reasonable to expect macOS developers to know UIColor doesn’t exist on that platform, rather than asking iOS developers to use a macro they don’t need.

friedbunny · 2017-03-10T22:58:58Z

platform/ios/docs/guides/Data-Driven Styling.md

+
+##Data-Driven Styling
+
+Mapbox's data-driven styling features allow you to use data properties to style your maps. You can style objects within the same layer differently based on their individual attributes. This enables you to style icons, routes, parks, and more based on attributes.


Use smart quotes: Mapbox's → Mapbox’s

friedbunny · 2017-03-10T22:59:56Z

platform/ios/docs/guides/Data-Driven Styling.md

+_Insert cool overview of things you can do!_
+
+### How to use Data-Driven Styling
+This guide uses earthquake data from the [U.S. Geological Survey](https://earthquake.usgs.gov/earthquakes/feed/v1.0/geojson.php) to illustrate to style a map based on attributes. For more information about how to work with GeoJSON data in our iOS SDK, please see our [working with GeoJSON data](https://www.mapbox.com/ios-sdk/api/3.5.0-beta.1/working-with-geojson-data.html) guide.


~~to illustrate~~ to style a map

friedbunny · 2017-03-10T23:02:17Z

platform/ios/docs/guides/Data-Driven Styling.md

+
+There are three subclasses of `MGLStyleFunction`:
+
+* `MGLCameraStyleFunction` - For a style value that changes with zoom level. For example, you can make the radius of a circle to increase based on zoom level. In iOS SDK v3.4, a `MGLStyleFunction` referred to what is now a `MGLCameraStyleFunction`.


referred to what is now a MGLCameraStyleFunction.

This seems like unnecessary repetition. Could we say something like: “In iOS SDK v3.4, this function was called MGLStyleFunction.”?

friedbunny · 2017-03-10T23:05:12Z

platform/ios/docs/guides/Data-Driven Styling.md

+
+`MGLInterpolationModelExponential` creates a linear effect based on the values. The key value is the base for interpolation, and the style value is based on where an attribute value falls between two keys.
+
+The stops dictionary below, for example, shows colors that continuously shift from yellow -> orange -> red -> blue -> white based on the attribute value.


Let’s convert -> to → (or some other arrow symbol).

Or “to”, since this is prose.

friedbunny · 2017-03-10T23:08:48Z

platform/ios/docs/guides/Data-Driven Styling.md

+            let source = MGLShapeSource(identifier: "earthquakes", url: url, options: nil)
+            style.addSource(source)
+
+            let stops = [0 : MGLStyleValue(rawValue: UIColor.yellow),


Definitely onboard with consistently using type inference in Swift, though.

friedbunny · 2017-03-10T23:11:01Z

platform/ios/docs/guides/Data-Driven Styling.md

+
+`MGLInterpolationModeInterval` creates a range using the keys stops dictionary. The range is from the given key to just less than the next key. The attribute values that fall into that range are then styled using the style value assigned to that key.
+
+When we use the stops dictionary given above with an interval interpolation mode, we create ranges where earthquakes with a magnitude of 0 to just less than 2.5 be yellow, 2.5 to just less than 5 would be orange, and so on.


we create ranges where earthquakes with a magnitude of 0 to just less than 2.5 would be yellow,

friedbunny · 2017-03-10T23:12:04Z

platform/ios/docs/guides/Data-Driven Styling.md

+                                                          attributeName: "mag",
+                                                          options: [.defaultValue: MGLStyleValue<UIColor>(rawValue: .green)])
+```
+<img width="320" alt="screenshot 2017-02-28 19 14 40" src="https://cloud.githubusercontent.com/assets/12474734/23444472/30d4e8b4-fdea-11e6-8184-ad9631529c74.png">


Unfortunately we can’t rely on GitHub to host these assets — be sure to commit and use the files required for this guide.

Definitely! In the process of doing that. I copied this from a gist and am still working on optimizing the screenshots

friedbunny · 2017-03-10T23:12:50Z

platform/ios/docs/guides/Data-Driven Styling.md

+```
+<img width="320" alt="screenshot 2017-02-28 19 14 40" src="https://cloud.githubusercontent.com/assets/12474734/23444472/30d4e8b4-fdea-11e6-8184-ad9631529c74.png">
+
+#####Categorical:


Remove the colon in this heading.

friedbunny · 2017-03-10T23:13:35Z

platform/ios/docs/guides/Data-Driven Styling.md

+
+
+
+#####Identity:


1ec5 · 2017-03-11T00:30:15Z

platform/ios/docs/guides/Data-Driven Styling.md

+
+`MGLInterpolationModelExponential` creates a linear effect based on the values. The key value is the base for interpolation, and the style value is based on where an attribute value falls between two keys.
+
+The stops dictionary below, for example, shows colors that continuously shift from yellow -> orange -> red -> blue -> white based on the attribute value.


Or “to”, since this is prose.

1ec5 · 2017-03-11T00:30:41Z

platform/ios/docs/guides/Data-Driven Styling.md

+
+The stops dictionary below, for example, shows colors that continuously shift from yellow -> orange -> red -> blue -> white based on the attribute value.
+
+```


Specifying swift here would get us syntax coloring.

1ec5 · 2017-03-11T00:31:39Z

platform/ios/docs/guides/Data-Driven Styling.md

+The stops dictionary below, for example, shows colors that continuously shift from yellow -> orange -> red -> blue -> white based on the attribute value.
+
+```
+  if let url = URL(string: "https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/all_week.geojson") {


URL(string:) only returns nil if the string is a malformed URL. Since the URL is formed from a string literal, we know it’s well-formed, so we can ! unwrap the optional without indenting everything below.

1ec5 · 2017-03-11T00:32:17Z

platform/ios/docs/guides/Data-Driven Styling.md

+
+```
+  if let url = URL(string: "https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/all_week.geojson") {
+            let symbolSource = MGLSource(identifier: "source")


But if we were to indent, we should use four spaces for each level of indentation.

1ec5 · 2017-03-11T00:35:41Z

platform/ios/docs/guides/Data-Driven Styling.md

+            layer.circleColor = MGLStyleValue<UIColor>(interpolationMode: .exponential,
+                                                          sourceStops: stops,
+                                                          attributeName: "mag",
+                                                          options: [.defaultValue: MGLStyleValue<UIColor>(rawValue: .green)])


This reminds me: we should find a good place to mention the ability to use #8025, even if it isn’t important enough to show in a code example.

Oh, good point. I will see if I can adjust the example to show that. Alternatively, we can use it in an upcoming example. Or both.

1ec5 · 2017-03-11T00:37:46Z

platform/ios/docs/guides/For Style Authors.md

-you want the attribute to be set to.
+constant values) or an `MGLStyleFunction` subclass. The style value object is a
+container for the raw value or function parameters that you want the attribute
+to be set to.


Per #8025 (comment), let’s take this opportunity to point out that not every interpolation mode is available for every attribute. The developer should consult the documentation for an individual layout or paint attribute to see which function types and interpolation modes it supports.

boundsj

Don't forget to update the jazzy.yml files so the new guide shows up in the generated documentation side bar for iOS and macOS.

Also, there are changes to the For Style Author.md.ejs template here that have not yet been picked up by make style-code and committed as part of this PR. I looks like we plan to create a template for the DDS guide (per #8354 (comment)) so running make style-code will happen in due time.

👍

boundsj · 2017-03-13T21:52:01Z

platform/ios/docs/guides/Data-Driven Styling.md

+
+Mapbox’s data-driven styling features allow you to use data properties to style your maps. You can style objects within the same layer differently based on their individual attributes. This enables you to style icons, routes, parks, and more based on attributes.
+
+![available bikes](img/data-driven-styling/citibikes.png)


Someday, it might be useful to include some designed images that combine a screenshot like this with a conceptual illustration of why these dots are special -- this could be something like an app screenshot on the left with a written function that maps a number to a color in the middle and an image of relevant tabular data on the right (just an idea).

Of course, nothing like this is required now but we might want to be on the lookout for images that end up in other parts of our docs or website and copy them back here.

boundsj · 2017-03-13T22:00:04Z

platform/ios/docs/guides/Data-Driven Styling.md

+
+The documentation for individual style properties will note which style functions are enabled for that property.
+
+####Stops


I noticed that 4 #s cause Stops to become STOPS in the generated documentation and that looks strange. Also, super nit, but we should probably format the headers consistently (add a space between the # and the first character of the text)

boundsj · 2017-03-13T22:01:19Z

platform/ios/docs/guides/Data-Driven Styling.md

+
+Stops are key-value pairs that that determine a style value. With a `MGLCameraSourceFunction` stop, you can use a dictionary with a zoom level for a key and a `MGLStyleValue` for the value. For example, you can use a stops dictionary with zoom levels 0, 10, and 20 as keys, and yellow, orange, and red as the values. A `MGLSourceStyleFunction` uses the relevant attribute value as the key.
+
+####`MGLInterpolationMode`


In the generated documentation, the four #s capitalization issue combined with the formatting caused by the back ticks makes this looke like MGLINTERPOLATIONMODE with a really thin font weight.

boundsj · 2017-03-13T22:03:45Z

platform/ios/docs/guides/Data-Driven Styling.md

+
+####`MGLInterpolationMode`
+
+The effect a key has on the style value is determined by the interpolation mode. There are four interpolation modes that can be used with a source style function: exponential, interval, categorical, and identity. You can also use exponential and interval interpolation modes with a camera style function.


Instead of calling out that "exponential and interval interpolation modes" can be used on a camera function, this might be a good place to add another table that shows which functions support which modes. That is:

camera: exponential & interval
source: all of them
composite: exponential, interval, categorial (but not identity)

friedbunny · 2017-03-14T18:43:07Z

Data-Driven Styling.md.ejs

@@ -0,0 +1 @@
+wat


oops that's from debugging! 😳

Addresses #8192 until #8354 lands.

1ec5 · 2017-03-17T16:33:00Z

platform/darwin/docs/guides/Data-Driven Styling.md.ejs

+  const macOS = os === 'macOS';
+  const cocoaPrefix = iOS ? 'UI' : 'NS';
+  const layers = locals.layers;
+  const renamedProperties = locals.renamedProperties;


A couple of these variables appear to be unused. You can safely remove them.

1ec5 · 2017-03-17T16:34:24Z

platform/darwin/docs/guides/Data-Driven Styling.md.ejs

+- [ ] Cluster earthquakes as an example for camera function?
+- [ ] Clean up & optimize screenshots - replace with screenshots showing circles below symbol layer
+- [ ] Link API docs
+- [ ] Add cocoaprefix so this can be moved to darwin


Looks like this item is complete.

1ec5 · 2017-03-17T16:36:09Z

platform/darwin/docs/guides/Data-Driven Styling.md.ejs

+When we use the stops dictionary given above with an interval interpolation mode, we create ranges where earthquakes with a magnitude of 0 to just less than 2.5 would be yellow, 2.5 to just less than 5 would be orange, and so on.
+
+``` swift
+layer.circleColor = MGLStyleValue<<%- cocoaPrefix %>Color>(interpolationMode: .interval,


It isn't necessary to specify NSColor/UIColor here, because Swift can infer the type from the type of circleColor.

1ec5 · 2017-03-17T16:36:52Z

platform/darwin/docs/guides/For Style Authors.md.ejs

@@ -166,6 +166,7 @@ layer                      | style layer
 property                   | attribute
 SDF icon                   | template image
 source                     | content source
+function type              | interpolation mode


Move this entry up to keep the table alphabetized by the first column.

1ec5 · 2017-03-17T16:38:07Z

platform/darwin/docs/guides/For Style Authors.md.ejs

+`property function`          | `MGLSourceStyleFunction`
+`zoom-and-property functions`| `MGLCompositeStyleFunction`
+
+### <%- camelize(type) %> interpolation mode


This table doesn't need its own subheading, but a complete sentence introducing the concept of an interpolation mode is would help to make this document flow better.

1ec5 · 2017-03-17T16:38:37Z

platform/darwin/scripts/generate-style-code.js

+fs.writeFileSync(`platform/ios/docs/guides/Data-Driven Styling.md`, ddsGuideMD({
+    os: 'iOS',
+    renamedProperties: renamedPropertiesByLayerType,
+    layers: layers,


Of these variables, it looks like only os is in use.

1ec5 · 2017-03-17T16:43:57Z

platform/darwin/docs/guides/For Style Authors.md.ejs

@@ -239,6 +240,28 @@ whose names differ from the style specification are listed below:
 <% for (const type in renamedProperties) { -%>
 <% if (renamedProperties.hasOwnProperty(type)) { -%>

+### <%- camelize(type) %> style functions
+
+The runtime styling API introduced `MGLStyleFunction` to the <%- os %> SDK.


This reads sort of like a release note. Let's cast this sentence in the present tense and talk about how the API includes style functions rather than introducing them.

Additionally, we have a tendency to use MGLStyleValue as an umbrella for both constants and functions. So even if we talk about the various style function subclasses, I think we should discuss the MGLStyleValue factory method that produces each kind of style function.

friedbunny · 2017-03-17T16:44:14Z

platform/darwin/docs/guides/Data-Driven Styling.md.ejs

@@ -0,0 +1,133 @@
+<!---
+To do - JK:


Are these to-does done?

friedbunny · 2017-03-17T16:45:21Z

platform/macos/docs/guides/Data-Driven Styling.md

@@ -0,0 +1,125 @@
+<!---
+To do - JK:


Todoooooooooo.

friedbunny · 2017-03-17T16:46:25Z

platform/ios/docs/guides/Data-Driven Styling.md

@@ -0,0 +1,125 @@
+<!---
+To do - JK:


Toooooooooodoooooooo.

friedbunny · 2017-03-17T20:54:00Z

General note: these guides would benefit greatly from linking up the method/class names to their jazzy pages.

... which is something we should look into contributing upstream to jazzy.

friedbunny · 2017-03-17T21:00:55Z

platform/darwin/docs/guides/Data-Driven Styling.md.ejs

+                 2.5 : MGLStyleValue(rawValue: <%- cocoaPrefix %>Color.orange),
+                 5: MGLStyleValue(rawValue: <%- cocoaPrefix %>Color.red),
+                 7.5 : MGLStyleValue(rawValue: <%- cocoaPrefix %>Color.blue),
+                 10 : MGLStyleValue(rawValue: <%- cocoaPrefix %>Color.white)]


Remove the spaces before the colons.

You can also remove the initial tab indentation, as it’s indenting the entire block by one.

friedbunny · 2017-03-17T21:07:51Z

platform/darwin/docs/guides/Data-Driven Styling.md.ejs

+
+#### Interval
+
+`MGLInterpolationModeInterval` creates a range using the keys stops dictionary. The range is from the given key to just less than the next key. The attribute values that fall into that range are then styled using the style value assigned to that key.


keys stops dictionary

Is this a dictionary of stops for multiple keys? Pluralization is a little awkward, but if the meaning is correct then it’s probably OK.

friedbunny · 2017-03-17T21:08:58Z

platform/darwin/docs/guides/Data-Driven Styling.md.ejs

+
+``` swift
+let categoricalStops = ["earthquake" : MGLStyleValue(rawValue: <%- cocoaPrefix %>Color.orange),
+                                    "explosion" : MGLStyleValue(rawValue: <%- cocoaPrefix %>Color.red),


Remove the spaces before the colons and realign these lines.

friedbunny · 2017-03-17T21:11:23Z

platform/darwin/docs/guides/Data-Driven Styling.md.ejs

+
+![identity mode](img/data-driven-styling/identity.png)
+
+Resources:


Promote this to a bigger header, as in the bottom of the Runtime Styling guide.

friedbunny · 2017-03-17T21:16:56Z

Are these code snippets testable? We’re dynamically inserting tested snippets into header documentation, but I’m not sure we’ve done that yet for guides.

/cc @ericrwolfe

jmkiley · 2017-03-17T22:35:13Z

ericrwolfe · 2017-03-17T23:02:56Z

Re: testability

I'd originally shied away from adding code snippets to the runtime styling guide out of concern for maintainability. But now that we have testable code examples we could certainly take a similar approach for the markdown guides.

We might be able to rework the original script from this PR #7337 to scan through the guides directory and replace placeholder tokens in the markdown files.

Note that the current examples script in platform/darwin/scripts/update-examples.js from #7569 is a bit more specific to work around the fact that the style layer classes are generated dynamically.

cc @1ec5

1ec5 · 2017-03-17T23:08:48Z

these guides would benefit greatly from linking up the method/class names to their jazzy pages.
... which is something we should look into contributing upstream to jazzy.

realm/jazzy#715

Note that the current examples script in platform/darwin/scripts/update-examples.js from #7569 is a bit more specific to work around the fact that the style layer classes are generated dynamically.

We also took that approach for the examples in the headers because jazzy documentation links to specific lines in the headers based on the source code it consumes – we didn’t want the line numbers to go out of sync because of inserted code. But that problem doesn’t affect the Markdown guides.

jmkiley · 2017-03-17T23:12:42Z

I opened a ticket so we can discuss how to make code snippets testable. #8461

jmkiley added documentation iOS Mapbox Maps SDK for iOS ⚠️ DO NOT MERGE Work in progress, proof of concept, or on hold labels Mar 10, 2017

jmkiley added this to the ios-v3.5.0 milestone Mar 10, 2017

1ec5 changed the title ~~[WIP] update iOS SDK~~ [WIP] update iOS SDK guides Mar 10, 2017

1ec5 added the macOS Mapbox Maps SDK for macOS label Mar 10, 2017

1ec5 reviewed Mar 10, 2017

View reviewed changes

friedbunny suggested changes Mar 10, 2017

View reviewed changes

friedbunny assigned jmkiley Mar 10, 2017

1ec5 reviewed Mar 11, 2017

View reviewed changes

jmkiley force-pushed the jmkiley-update-guides branch from 3a5e79a to f9f084a Compare March 12, 2017 21:32

boundsj reviewed Mar 13, 2017

View reviewed changes

boundsj mentioned this pull request Mar 13, 2017

Add documentation for data-driven styling #7924

Closed

18 tasks

jmkiley force-pushed the jmkiley-update-guides branch from 3608a12 to 1de8180 Compare March 14, 2017 00:35

friedbunny reviewed Mar 14, 2017

View reviewed changes

jmkiley force-pushed the jmkiley-update-guides branch from 1de8180 to 987fb62 Compare March 14, 2017 19:02

jmkiley mentioned this pull request Mar 15, 2017

[ios, macos] Add more information to interpolation mode docs #8425

Merged

jmkiley added a commit that referenced this pull request Mar 15, 2017

[ios, macos] Add more information to interpolation mode docs (#8425)

2c0005c

Addresses #8192 until #8354 lands.

jmkiley force-pushed the jmkiley-update-guides branch from 987fb62 to 0cbe2f7 Compare March 17, 2017 16:31

1ec5 reviewed Mar 17, 2017

View reviewed changes

friedbunny reviewed Mar 17, 2017

View reviewed changes

jmkiley added 8 commits March 17, 2017 17:12

[ios] started to update style authors guide

584bca0

[ios] added dds guide draft

9187318

[ios] more guide edits

bcd45f5

[ios, macos] moved style guide edits to darwin

c75cdc1

[ios] smart quotes

7d4c3ea

[ios] add images

ba58ef9

[ios] added a line

ed79d69

[ios, macos] updated script, started to add dds guide to darwin

4489ef8

jmkiley added 8 commits March 17, 2017 17:12

[ios, macos] switched darwin dds file to ejs

4e0bce0

[ios, macos] removed wat

30d6655

zoom level -> zoom level or attribute value

07f3a8a

[ios, macos] added polyline image

5be5911

[ios, macos] doc tweaks

0015a28

[ios, macos] revisions pt 1

e2c6be3

[ios, macos] revisions pt 2

df4fbc2

[ios, macos] elaborated on MGLStyleValue methods

bd6f1af

friedbunny reviewed Mar 17, 2017

View reviewed changes

jmkiley added 2 commits March 17, 2017 17:20

[ios, macos] revisions

07c7976

[ios, macos] spaces/colons

e6a1dfb

jmkiley force-pushed the jmkiley-update-guides branch from 8c4a636 to e6a1dfb Compare March 17, 2017 21:23

jmkiley added 2 commits March 17, 2017 17:26

[ios, macos] adjusted headers

be1b38f

[ios, macos] resized images

040496a

friedbunny approved these changes Mar 17, 2017

View reviewed changes

jmkiley added 2 commits March 17, 2017 18:40

[ios, macos] style-code -> darwin-style-code

d1ffc9f

cleaned up resources

6eaf601

friedbunny mentioned this pull request Mar 17, 2017

[ios, macos] Add testing for code in guides #8461

Closed

jmkiley merged commit 789a49d into release-ios-v3.5.0-android-v5.0.0 Mar 17, 2017

jmkiley deleted the jmkiley-update-guides branch March 17, 2017 23:13

1ec5 removed the ⚠️ DO NOT MERGE Work in progress, proof of concept, or on hold label May 6, 2017


		##Data-Driven Styling

		Mapbox's data-driven styling features allow you to use data properties to style your maps. You can style objects within the same layer differently based on their individual attributes. This enables you to style icons, routes, parks, and more based on attributes.


		There are three subclasses of `MGLStyleFunction`:

		* `MGLCameraStyleFunction` - For a style value that changes with zoom level. For example, you can make the radius of a circle to increase based on zoom level. In iOS SDK v3.4, a `MGLStyleFunction` referred to what is now a `MGLCameraStyleFunction`.


		`MGLInterpolationModelExponential` creates a linear effect based on the values. The key value is the base for interpolation, and the style value is based on where an attribute value falls between two keys.

		The stops dictionary below, for example, shows colors that continuously shift from yellow -> orange -> red -> blue -> white based on the attribute value.


		`MGLInterpolationModeInterval` creates a range using the keys stops dictionary. The range is from the given key to just less than the next key. The attribute values that fall into that range are then styled using the style value assigned to that key.

		When we use the stops dictionary given above with an interval interpolation mode, we create ranges where earthquakes with a magnitude of 0 to just less than 2.5 be yellow, 2.5 to just less than 5 would be orange, and so on.


		Mapbox’s data-driven styling features allow you to use data properties to style your maps. You can style objects within the same layer differently based on their individual attributes. This enables you to style icons, routes, parks, and more based on attributes.

		![available bikes](img/data-driven-styling/citibikes.png)


		The documentation for individual style properties will note which style functions are enabled for that property.

		####Stops


		Stops are key-value pairs that that determine a style value. With a `MGLCameraSourceFunction` stop, you can use a dictionary with a zoom level for a key and a `MGLStyleValue` for the value. For example, you can use a stops dictionary with zoom levels 0, 10, and 20 as keys, and yellow, orange, and red as the values. A `MGLSourceStyleFunction` uses the relevant attribute value as the key.

		####`MGLInterpolationMode`


		####`MGLInterpolationMode`

		The effect a key has on the style value is determined by the interpolation mode. There are four interpolation modes that can be used with a source style function: exponential, interval, categorical, and identity. You can also use exponential and interval interpolation modes with a camera style function.


		#### Interval

		`MGLInterpolationModeInterval` creates a range using the keys stops dictionary. The range is from the given key to just less than the next key. The attribute values that fall into that range are then styled using the style value assigned to that key.


		![identity mode](img/data-driven-styling/identity.png)

		Resources:




		#####Identity:

		@@ -0,0 +1 @@
		wat

[WIP] update iOS SDK guides #8354

[WIP] update iOS SDK guides #8354

Conversation

jmkiley commented Mar 10, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

friedbunny Mar 10, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jmkiley Mar 11, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

boundsj left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

boundsj Mar 13, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jmkiley Mar 14, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

friedbunny commented Mar 17, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

friedbunny commented Mar 17, 2017

jmkiley commented Mar 17, 2017 • edited Loading

ericrwolfe commented Mar 17, 2017

1ec5 commented Mar 17, 2017

jmkiley commented Mar 17, 2017

jmkiley commented Mar 10, 2017 •

edited

Loading

friedbunny Mar 10, 2017 •

edited

Loading

jmkiley Mar 11, 2017 •

edited

Loading

boundsj left a comment •

edited

Loading

boundsj Mar 13, 2017 •

edited

Loading

jmkiley Mar 14, 2017 •

edited

Loading

friedbunny commented Mar 17, 2017 •

edited

Loading

jmkiley commented Mar 17, 2017 •

edited

Loading