Task backed components

Task backed components are the easiest way to fetch data or make backend mutations in a view.
Task backed components automatically execute a task or runbook, populate the component with data, and handle loading and error states.

Using task backed components

Task backed components have a unique prop called task.
NameDescription
task
string | { slug: string; params?: Record<string, any>; refetchInterval?: number; onSuccess?: (output?: TOutput) => void; onFailure?: (output?: TOutput, error?: TError) => void; executeOnMount?: boolean; executeOnWindowFocus?: boolean; executeOnReconnect?: boolean; } | AirplaneFunc | { fn: AirplaneFunc; params?: Record<string, any>; refetchInterval?: number; onSuccess?: (output?: TOutput) => void; onFailure?: (output?: TOutput, error?: TError) => void; executeOnMount?: boolean; executeOnWindowFocus?: {boolean; executeOnReconnect?: boolean; }

The task query to execute when this component loads. The component's data will be populated by the task's output and loading and error states will be handled automatically.

If the task doesn't require any parameters or special options, you can just pass the task slug (task="my_task") or an AirplaneFunc—the return value of airplane.task() (task={myTask}).

If the task requires parameters, these can be passed in via params.

The refetchInterval param represents how often (in milliseconds) the task query should be rerun to refetch data automatically.

The onSuccess and onFailure callbacks will run on task success or failure.

The executeOnMount, executeOnWindowFocus, and executeOnReconnect params control when the task is (re)run - on component mount, when the window is (re)focused, and if the network reconnects. All of these options are true by default.

By task function

The recommended way to use a task backed component is to supply an AirplaneFunc which is the value returned by the airplane.task function. This is only feasible if your task is in the file as your view or is in the same project and is imported.
If the task has parameters, you can supply a full task request. The types of the parameters in your task request will automatically be inferred from the task if you are using TypeScript!
Using a full task request also allows you to add additional options to the request like adding a refetchInterval that refetches the task every 10s.

By slug

You can also supply the slug of an Airplane task to the component.
If a task has parameters, you can supply a full task request.
Using a full task request also allows you to add additional options to the request like adding a refetchInterval that refetches the task every 10s.

Transforming data

Sometimes you may want to transform the task output before it is displayed in a task backed component. Each task backed component has an outputTransform prop that allows you to transform the data before it is displayed by the component.

Which components can be task backed?

The following components can be task backed via the task prop:

Form

Form can also be task backed, but a task-backed form automatically infers its fields from the task parameters, and the parameter values can be set using the form values. The task prop on Form follows a modified API that allows the inputs for each parameter to be customized.
NameDescription
task
string | { slug: string; shownFields?: string[]; hiddenFields?: string[]; fieldOptions?: { slug: string; value?: string | number | boolean | Date; allowedValues?: string[] | number[] | Date; }[]; }
The task associated with the form. This can either be a string, corresponding to the task slug, or an options struct, for which the task slug must be passed in the slug field.
If shownFields is set, only fields in shownFields are shown.
If hiddenFields is set, fields in hiddenFields are hidden.
fieldOptions can be used to restrict the values for a field. Each option in fieldOptions has a slug field, corresponding to the parameter slug.
If you want to fetch data from another component, see Manual task execution.