Actions

Actions are the building blocks of Forge. An action runs your code each time the user submits a form or schedules the action to be ran. Actions can range from CRUD operations to workflow tasks.

JavaScript/TypeScript

export default new Action(async () => {
  const name = await io.input.text("Your name");

  // run your code

  return `Invited ${name}!`;
});

Python

@forge.action(name="Customer Invitation Form")
async def customer_invitation(io: IO):
    name = await io.input.text("Your name")
    return f"Invited {name}"

Transactions

A transaction represents a single run for an Action. A transaction has the following states:

• Success - occurs when a transaction has completed
• Error - occurs when the transaction has an error
• Canceled - occurs when the user leaves the page or when the user explicitly cancels the transaction

Rendering UIs

Requesting an optional value

By default, when you request input with an I/O method, the person running your action must supply a valid value before continuing. In some cases, you may want to allow the person running you action to skip a field.

This can be done simply by chaining your I/O method call with .optional().

For example:

JavaScript/TypeScript

// maybeEmail is a string containing an email address *or* undefined
const maybeEmail = await io.input.email("Enter an email").optional();

// or to conditionally mark as optional
const maybeEmail = await io.input
  .email("Enter an email")
  .optional(user.email !== null);

Grouping inputs together

When writing actions, you'll often want to call multiple I/O methods at the same time. For example, for a tool to create a user account, you may want to collect an email, name, and age. To do this in Forge, you can use the io.group method. If you've used Promise.all before, Forge's group method works effectively identically:

JavaScript/TypeScript

const [name, email, age] = await io.group([
  io.input.text("Name"),
  io.input.email("Email"),
  io.input.number("Age"),
]);

Customizing the submit button

By default, each "step" within your action that requests user input renders a single submit button allowing the person running the action to move on when they've filled out the form.

To change the button label or add additional buttons, chain any I/O method or group with withChoices(), and pass an array of options defining the available paths forward. Each provided option will render a button in the action UI, and change the I/O method or group return value to contain a choice identifying the chosen button in addition to the usual return value(s) from the I/O methods.

JavaScript/TypeScript

const {
  choice,
  returnValue: { num1, num2 },
} = await io
  .group({
    num1: io.input.number("First number"),
    num2: io.input.number("Second number"),
  })
  .withChoices(["Add", "Subtract", "Multiply"]);