Improved usability for array and vararg parameters

Making Packs
1

In addition to improving the SDK itself, the Packs team has been working hard to make existing SDK features work better in Coda. We’re happy to announce two significant usability improvements to how parameters work in our structured builders (button action configuration and sync table settings),

Auto-complete for array parameters

Adding auto-complete to parameters can help ensure your users select valid options for your Pack, but previously this feature didn’t work correctly for array parameters. We’ve completely redone how auto-complete works for array parameters, and now users will get a nice UX similar to how select lists work in Coda.

pack.addFormula({
  name: "CreateFarm",
  description: "Makes a new farm.",
  parameters: [
    coda.makeParameter({
      type: coda.ParameterType.StringArray,
      name: "animals",
      description: "The animals to include on the farm.",
      autocomplete: ["cow", "pig", "sheep", "goat", "duck", "horse"],
    }),
  ],
  resultType: coda.ValueType.String,
  isAction: true,
  execute: async function ([animals], context) {
    // ...
  },
});

image
image390×546 19.9 KB

Varargs in structured builders

Variable argument parameters (varargs) are a more advanced feature of the SDK, but one that is often used when you are connecting to a API that supports a dynamic set of options (for example, custom fields). Historically vararg parameters didn’t display at all in our structured builders, but we’ve made some improvements that should make them a more viable option.

If you have only a single vararg parameter, it will be shown in the structured builders as if it was an array parameter.

pack.addFormula({
  name: "AddLabels",
  description: "Adds some labels",
  parameters: [
    coda.makeParameter({
      type: coda.ParameterType.String,
      name: "itemId",
      description: "The ID of the item",
    }),
  ],
  varargParameters: [
    coda.makeParameter({
      type: coda.ParameterType.String,
      name: "label",
      description: "A label to add.",
    }),
  ],
  resultType: coda.ValueType.String,
  isAction: true,
  // ...
});

image

And if you have a pair of vararg parameters (the most common case) it will be shown with a new UX similar to what you see for some built-in Coda actions.

pack.addFormula({
  name: "UpdateItem",
  description: "Updates an item",
  parameters: [
    coda.makeParameter({
      type: coda.ParameterType.String,
      name: "itemId",
      description: "The ID of the item",
    }),
  ],
  varargParameters: [
    coda.makeParameter({
      type: coda.ParameterType.String,
      name: "field",
      description: "Which field to set.",
    }),
    coda.makeParameter({
      type: coda.ParameterType.String,
      name: "value",
      description: "The value of that field.",
    }),
  ],
  resultType: coda.ValueType.String,
  isAction: true,
  execute: async function ([itemId, ...args], context) {
   // ...
  },
});

image

Note that if you have a set of three or more vararg parameters it still won’t show up in the structured builders, and the user will need to visit the formula editor to set their values.

Let us know what you think of these improvements, and if there are other areas of the structured builder experience that you’d like to see us focus on.

6 Likes
2

Both great improvements in the UX realm, the visibility of varargs has been a problem and this in my opinion fixes it pretty well, well done team! :raised_hands:

FYI, there are currently some issues when using multiple StringArray parameters in the same sync table configuration, @Eric_Koleda is already aware.

1 Like