Style URLs in Android SDK

[cammace]

With Android, we have a two ways to set the style you'd like, either in XML or java. We prefer users setting in XML to prevent loading in the default street style before changing to the one they prefer. In the past we've used constants that users can call instead of manually plugging in the default style url themselves. These constants had the style version hardcoded in them so using the constant resulted in always automatically updating the map to the latest style when the SDK was updated. Previous chats with @tobrun and @bleege, we've discussed various ways to handle removing the version number from the constants, or removing the constants all together. This resulted in deprecating all the style strings and creating java methods with the version number as the parameter. This works great for the java side of things but xml doesn't use methods and doesn't even show the style constants as deprecated. After our weekly strategy call today, we've come up with this solution:

For java we will keep the current methods for setting the map style i.e. Style.getOutdoorsStyleUrl(9) which gives devs flexibility when choosing which version they'd like to use. Style wont be changed without the developer updating the version parameter.

XML will remain using the string constants i.e. mapbox:style_url="@string/style_mapbox_streets". When we update the style version in the SDK, the users map style will be updated as well. This has the benefit of handling style updates on behalf of the dev.

in both cases, the developer always has the option to pass in the full style URL themselves. The main concern here is that by keeping the constants we still keep the ease of quickly adding correct style urls quickly. If this sounds 👍 I'll self-assign and clean up the constant files.

cc: @zugaldia @jfirebaugh

[1ec5]

This has the benefit of handling style updates on behalf of the dev.

The consensus in an internal discussion was that we don’t want style updates to happen transparently, because the style’s sources and paint properties will increasingly be tied to proper functioning the application as we add support for feature querying (#352) and dynamic restyling (#837) to the SDKs.

The situation with the XML manifest is reminiscent of the situation with storyboards the iOS and OS X SDKs. Interface Builder supports only string literals in the style URL setting, not symbolic constants or methods. It’s a pain point for an otherwise click-and-drag experience (and a parity issue with respect to MapKit and Google Maps), but I think we’re at the point where treating style URLs as freeform URLs is starting to make more and more sense because a style is no longer a black box.

[cammace]

The reason we wanted to keep the constant around was for developers who aren't particularly concerned with the style of the map and don't follow along to hear about when a new style is released. In this case, we'd be able to ensure that they are always using the updated style version. Having these users use the freeform URLs means they'd most likely never update the style.

[bleege]

As we discussed on our call earlier this week I really oscillate on this issue. @1ec5 is absolutely correct when he says "I think we’re at the point where treating style URLs as freeform URLs is starting to make more and more sense because a style is no longer a black box." However, IMHO there are also a lot of people who simply want to drop a default style into their app as quickly as possible and go with the expectation that they're map may change over time (aka how Google Maps works).

How about we do something similar to what @cammace proposes with one slight tweak? Specifically:

1. All examples on mapbox.com and in the TestApp should use explicit Style URLs
   • This is to help educate people and make them aware of how things should work.
2. Create / Keep existing Java and XML constants that always point to the latest version of styles
   • Both will be explicitly documented to say that these styles WILL change over time as new versions come along and their maps will look different as a result.
   • This is workable as unlike Web apps that automatically load things from the Web and immediately impact end users, the mobile developer is going to be the first person to see the change in map style locally. In order for this update in style version to impact their end users the developer is going to have to publish their app... ie make the conscious decision that this is what they want their app to use. If they don't want this new version of the default style they can switch to an explicit Style URL to keep their original one.
   • This allows new developers to Mapbox to quickly get a map setup and running before they have to know more about the details of how Mapbox works.
3. Remove the Style.getStyleXUrl(int version) methods
   • Anyone interested in a particular version of a style is going to understand the system and will be comfortable using full Style URLs.
   • This keeps the API options limited and simple. Either use Style URLs or Latest Style Constants.

We prefer users setting in XML to prevent loading in the default street style before changing to the one they prefer.

This is something that we should reconsider, specifically loading a default style instead of leaving the screen black as originally designed. I've come around on this especially as the Mapbox GL ecosystem has continued to evolve and mature over the past few months. Removing the default style would also eliminate the issue of a doubly loaded style.

[bleege]

Discussed with @cammace internally and we're both on board with the proposed compromise. He's going to pick this up tomorrow and run with it.

[bleege]

This got merged into release-android-v4.1.0.