Mapbox-gl-js: Migrate examples using stop functions to expressions

[anandthakker]

[mollymerp]

I'm not sure we should migrate examples that use stop functions and don't need the added power of expressions given that the expressions syntax is much more complicated and I would guess harder for beginners to grasp. I would rather add new examples that take advantage of the added capabilities that expressions offer and keep the old examples around as an alternative. 💭

[jfirebaugh]

Here's a comparison (from this example) of what seems to me a common case:

Function	Expression
// make circles larger as the user // zooms from z12 to z22 'circle-radius': { 'base': 1.75, 'stops': [[12, 2], [22, 180]] },	// make circles larger as the user // zooms from z12 to z22 'circle-radius': [ "interpolate", ["exponential", 1.75], ["zoom"], 12, 2, 22, 180 ],
Pros: More concise Base and stops are labeled as such Grouping the stops in arrays keeps them visually paired if the JSON is pretty printed	Pros: "interpolate" gives a hint as to what the expression is doing, and can be searched for in documentation The interpolation type is explicit The base value is clearly associated with the interpolation The the domain of the curve -- zoom level -- is explicit Less bracket noise if you manually format the stops

Overall, I think expressions come out on top in terms of understandability, even in simple examples like this. Maybe we could do some informal user testing to validate this.

[anandthakker]

Overall, I think expressions come out on top in terms of understandability, even in simple examples like this. Maybe we could do some informal user testing to validate this.

Yeah - and if it turns out they are significantly less accessible / clear, I think we should find ways to make expressions more accessible, rather than sticking with stop functions, because in the long run, we'll want to end up with a single syntax rather than supporting two in parallel.

[mourner]

I like the expression curve syntax, especially if we can drop the wrapper (#5222)

[mollymerp]

👍 thanks for the analysis @jfirebaugh. @anandthakker should we see if Victoria has any bandwidth to create a user testing plan for the new syntax?

[anandthakker]

@mollymerp great idea. I think it'd be super valuable to get some systematic feedback. I wonder what the ideal time would be, given that there's still a bit of churn happening with the API... better to do it now, while things are still moving, or after we've addressed a few known issues?

[stevage]

Maybe we could do some informal user testing to validate this.

Informal user reporting for duty! This is the first time I've seen the syntax on the right, but I'm pretty familiar with the old syntax (so, maybe not the right kind of user).

The new syntax seems really surprising to me. So, it's an array of 7 items, where you just have to know which item belongs in which position?

Other thoughts:

• "zoom" is surrounded by square brackets for some reason, but all the brackets are missing from 12, 2, 22, 180?
• The formatting of those numbers, two per line, seems really novel. I guess it was a compromise between different design considerations, but it seems a bit un-Mapbox-y – a departure from standards and widely used conventions.
• The use of the word "curve" bothers me for some reason. I've made a lot of Mapbox-GL-JS maps, yet I almost never modify the exponential base. I don't really think of a "curve", I just think of a property being one value at zoom 12 and another value at zoom 15. It just feels a bit confusing, like imagining there will be a visual curve on the map (like an arc or a circle). Or maybe it's just too mathsy.
• now that I'm having a quick look at what I think is the proposed spec, I'm a bit apprehensive that there is a lot of complexity which will get in the way of the very common use cases like simple zoom functions.

Sorry if these comments aren't helpful.

[alpha-beta-soup]

Informal user here: I've been using the expressions syntax for about a year now over 3 or 4 different large projects. I'm still routinely stumped by it whenever I want to do something that is moderately complex. When another person on my team (who had no experience whatsoever with the expressions syntax) tried to develop a feature that required them, he was immensely frustrated by it, and it took him about 5 times as long to complete his task than he estimated. I get that the syntax needs to be abstract in order to be powerful, but this syntax is just so hard to grok it's unbelievable. The expressions documentation needs a complete overhaul in my opinion, starting with examples for each item in the expressions part of the spec (specifically not buried deep within separate, hard-to-find-a-second-time examples). There's a bunch of features that I haven't even touched yet (e.g. variable bindings), and I'm unsure of the utility of them. collator and format (which I also haven't yet had a reason to use) seem to use JSON objects where everything else relies on positional arguments.

I realise my comments sound negative, but as much as I love Mapbox, I find expressions to be so, so frustrating to use and I have to say so. When I get them wrong, it takes me a long time to work out why they are wrong. I get them wrong more often than I get them right. The most surprising thing for me is that my ability to get expressions right has barely improved from when I first used an expression.

[stevage]

FWIW, I notice the example here uses both old and new style.

Also, FWIW, my view is still much the same as when I posted above, and basically the same as alpha-beta-soup.

[urschrei]

Just adding to alpha-beta-soup and stevage's comments above. The expression syntax is clearly an improvement, but I find the mental overhead and more importantly, _lack of examples_ to be incredibly frustrating. Any time I want to match a nested value, or combine get, any and match in anything but the most simple way, I just give up in frustration. The fact that I know that it's just a lisp-like combination of nested expressions doesn't help much in practice.

[ChrisLoer]

@alpha-beta-soup @stevage and @urschrei thanks for chiming in. Even as a person who has worked on adding functionality to the expression language, I can echo the comment "When I get them wrong, it takes me a long time to work out why they are wrong". We're definitely aware of some of the challenges here. I don't have a grand architectural plan, but I can say the rough direction we hope to take to improve here:

• Incrementally grow our examples to show a wider set of cases. The suggestion to link examples into the spec document more directly is a good one.
• Improve expression related error messages (e.g. https://github.com/mapbox/mapbox-gl-js/issues/6345, there are many places to improve here). The goal here is to reduce that "long time to work out what's wrong" part.
• Focus on wrapping the expression language in higher level concepts (I think the most developed version of this is the "add formula" functionality in Mapbox Studio.

One thing I doubt we'll change _much_ is the underlying "lisp-iness" of the expression language.

[stevage]

Btw is there a better forum for having this kind of high level discussion about the expression syntax?

I'm slowly migrating more into it. Some parts of it I like ("match" is nice). Some parts I still don't (simple zoom-based expressions, which are super common, and were so simple and straightforward now, and now require an "interpolate" function). And yeah the gotchas, like when you need to typecast a value, and get confusing error messages.

One thing I doubt we'll change much is the underlying "lisp-iness" of the expression language.

Maybe someone can make a plugin that compiles a string to an array structure.

[ChrisLoer]

Btw is there a better forum for having this kind of high level discussion about the expression syntax?

I dunno, I think GitHub Issues are the right forum, maybe a broader "discussion" ticket but the challenge is always the broader a ticket gets the less actionable it becomes.

Maybe someone can make a plugin that compiles a string to an array structure.

Have you seen https://github.com/mapbox/expression-jamsession?

[stevage]

Sorry, yeah, Github Issues is fine. But it seems very unlikely anyone else is going to accidentally stumble on this conversation on a closed ticket :)

Have you seen https://github.com/mapbox/expression-jamsession?

Oh! Looks awesome. Vaguely rings a bell but must have forgotten to ever check it out. Should be promoted more! (At least a "You may want to consider using Jamsession" in the style spec?)