Commands

{formmenu}

Sample Usage
Help us get the right shirt for you:

Color: {formmenu: Red; Blue; Green; Black}
Shirt Size: {formmenu: XS; S; default=M; L; XL}
_

Quick Overview Video

Settings


Setting NameTypeDescription
PositionaltextThe ordered list of menu items.
colsnumberThe width of the form menu in columns of characters.
multipleyes/noAllow selecting multiple items (default is no).
itemformatterfunctionFormats individual menu items. Takes two arguments, the text of the menu item and the index of the menu item.
General Form Settings
nametextName used for labels and data bindings.
default–The default value for the form field.
formatterfunctionFormats the value of the field before snippet insertion.
General Command Settings
trimyes/no/left/rightIf yes whitespace is removed before and after the command. If left, only whitespace to the left is removed. If right, only whitespace to the right is removed.

To learn more about form commands and their capabilities, see the forms guide.

The {formmenu} command is a unique command in that it takes multiple positional settings. Each positional setting that you include is an item that you will be able to select in the menu.

Selecting multiple items

The {formmenu} command also allows you to define a multiple setting. By default it's set to no, but if you explicitly set it to yes, you can now select multiple items.

If you also specifiy a name setting, then the results will be returned as a list if you use it in a {=} (Formula Command) command.

Selecting multiple items
{formmenu: Red; Blue; Green; Black; name=colors; multiple=yes; default=Red} {=colors}
_

Custom Formatting

There are two settings that customize the formatting of the menu items:

  • itemformatter: Formats each individual menu item.
  • formatter: Formats the entire list of selected items. This is primarily useful when you have the multiple setting set to yes and are selecting multiple items from the list.

Using itemformatter

The itemformatter setting is a function that takes the text of each individual menu items and transforms it.

For example, if you wanted to uppercase each menu item, you could do something like the following.

Using itemformatter
Select: {formmenu: Item A; Item B; Item C; Item D; itemformatter=(item) -> upper(item)}
_

The itemformatter function takes an optional second parameter which is the index of the menu item. This is the position of the item in the list.

For example, we can use that to number our items:

Using the Item Index
Select: {formmenu: Item A; Item B; Item C; Item D; itemformatter=(item, index) -> index & ". " & item}
_

If the syntax of the function above looks unfamiliar, learn more about functions in the Text Blaze Formula Reference.

Using formatter

The formatter setting is a function that allows you to format all of the items in your {formmenu}.

If multiple is yes, it will be passed a list of values (which may be empty if no items have been selected).

Using formatter with multiple items
Select: {formmenu: Item A; Item B; Item C; Item D; formatter=(items) -> join(items, ", "); multiple=yes}

(when inserted, the selected items will be separated with a comma.)
_

If multiple is no, the first parameter of the formatter setting is a single string value.

Combining Both Formatters

The following example illustrates the use of the itemformatter and formatter functions together.

Both formatter and itemformatter
Select: {formmenu: Item A; Item B; Item C; Item D; multiple=yes; itemformatter=item -> upper(item); formatter=items -> join(items, "; ") if count(items) > 0 else "No Items Selected"}
_

See the Blaze Formula Reference for more information on defining formatting functions.