Parameter formulas

Making Packs
1

I’m developing a pack that works with Mapbox APIs and a number of formulas require entailed parameters. In some cases this is just a lengthy static list (i.e. countries | types filter) and in others a call to the API is necessary (i.e. fetch styles from a user account).

While autocomplete within the formula parameters is nifty, there are some weird type related bugs and I often prefer controls within my doc such as a single/multi select. I find myself frequently writing formulas that only return optional parameters so that I can create controls in docs, as well as separate code better in the pack. Here’s an example:

export const PlaceTypes = coda.makeFormula({
  name: 'PlaceTypeEnum',
  description: 'Returns possible type values for queries to the geocoder api',
  resultType: coda.ValueType.Array,
  items: {type: coda.ValueType.String},
  parameters: [],
  execute: async () => MapboxPlaceTypes,
});

Has anyone encountered or made use of a similar pattern?

The only real downside I can see is that the number of formulas becomes unwieldy and it’s difficult to differentiate between primary formulas and these formulas that just return acceptable parameters. I at first wanted to append special character to differentiate { $PlaceType } but this is not allowed by the SDK, so I am currently returning { PlaceTypeEnum }. If this is a useful pattern for more entailed packs, a suggestion would be to separate controls/parameters similar to how action formulas are differentiated.

P.S. The autocomplete bug I’ve noticed is that it only works with string input and doesn’t handle numbers. I have autocomplete search functionality built into several formulas to return autocomplete geocode search data (instead of copy + pasting coordinates a user can just search place names from within the formula) but this won’t work with address inputs that start with a number so the features is kinda useless.

2

Hey there! Welcome to the community.

Another downside you will want to think of is user behavior and ensuring your pack is accessible.

I’ve built many packs now and continually find that the way I intend the pack to be used (in terms of parameters, etc) and which also feels natural to me - feels so foreign to others.

I think if you create separate formulas to use inside of controls in your docs (while a genius idea), it will create a user experience for new pack users that is just (for the most part) too difficult to overcome.

Some individuals will pick it up and be thankful for it, but most users will try out your pack, get confused why it’s not working the way they expect, and then stop using it.

If the pack you are making is for private use then that’s another story! I do all sorts of wacky stuff in private packs because I only have to think of the exact way I myself want to use a pack.

Just saying all this from personal experience! You may find something else if you move forward with this - but my personal opinion would be to not pursue this route for packs you intend to publish.

1 Like
3

Not sure I understand the concern… Is it to expose the list of options for some formula parameters so that it can be used independently? (I talk about a similar use case here: Pack-namespaced constants)

Also, what are the there “weird type related bugs”?

4

Hi @Micah_Cotton - Thanks for raising this topic, it does seem to be a pattern that is arising for some Packs, as @louca.developer attested to. I built something similar for my own ASCIIfy Pack, where I added a Fonts() formula and table that listed out the supported fonts.

I think we’d want to see this pattern a bit more established before we built a solution into the platform as @louca.developer suggested, but in the mean time I think helper formulas would work just fine. To minimize the Pack congestion and possible user confusion that @Scott_Collier-Weir pointed to, you could create a single formula that provided the options for a bunch of different constants:

getOptions("Direction") => ["North", "South", "East", "West"]
getOptions("Orientation") => ["Top-to-bottom", "Left-to-right"]

You can then provide autocomplete on that formula for the different constants available.

2 Likes
5

And thanks for reporting this bug! I was able to replicate it and I’m going to file it with the engineering team. I’m not sure how quickly we’ll be able to fix it, but the team is working on fixing bugs across the platform.

2 Likes
6

Yes exactly, though constants is a more expressive term. Another example from the Mapbox pack would be a parameter that accepts any number of ISO 3166 alpha 2 country codes. While this could be represented in an autocomplete that solution does not allow for multiple selections. +1 for your suggestion RE constants/namespaces

7

This is a great suggestion I’ll likely end up employing. As nice as the autocomplete is for formulas there are definitely times when a control leads to a better user experience (multi-select or number inputs come to mind immediately), the question becomes when to use this pattern and how to communicate that rationale downstream. Autocomplete is certainly not mutually exclusive with formulas that return constants and in many cases one can allow both, but it would be weird to have some parameters returned by formulas and not others.

The ASCIIfy pack is an awesome example of many functions exposed over a small surface area. I’ve thought about doing something similar with Turf.js If I can find a way to handle variable params.

8

Indeed! Luckily we have a great community of folks (yourself included) helping to blaze these trails. Do report back your learnings as you go down this road.

If I can find a way to handle variable params

The common way to handle this is varargParameters, of key-value pairs.

DoThing(account, thingId, "param1", "value1", "param2", "value2")

You can provide auto-complete for the keys, making it easy for the user to select from the available options.

2 Likes