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.
task
optional
string | AirplaneFunc | SlugQuery | FunctionQuery

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 does require parameters or special options, pass the task as an object. If you are using a slug, specify the slug prop to pass the task configuration as a SlugQuery. If you are using an AirplaneFunc, specify the fn prop to pass the task configuration as a FunctionQuery.

SlugQuery
FunctionQuery

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

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

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

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.
tsx
Copied
1
const TaskBackedWithAirplaneFunc = () => {
2
return <Table title="Cats" task={ListCatsTask} />;
3
};
4
5
export const ListCatsTask = airplane.task({ slug: "list_cats" }, async () => cats);
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!
tsx
Copied
1
const TaskBackedWithAirplaneFunc = () => {
2
return <Table title="Cats" task={{ fn: ListCatsTask, params: { animal: "cat" } }} />;
3
};
4
5
export const ListCatsTask = airplane.task(
6
{ slug: "search_animals", parameters: { animal: "shorttext" } },
7
async () => animals
8
);
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.
tsx
Copied
1
<Table title="Cats" task="list_cats" />
If a task has parameters, you can supply a full task request.
tsx
Copied
1
<Table title="Cats" task={{ slug: "search_animals", params: { animal: "cat" } }} />
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.
tsx
Copied
1
<Table
2
title="Cats"
3
task={{ slug: "search_animals", params: { animal: "cat" }, refetchInterval: 10000 }}
4
/>

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.
tsx
Copied
1
<Table
2
title="Cats"
3
task="list_cats"
4
outputTransform={(output) => output.map((cat) => ({ ...cat, name: cat.name.toUpperCase() }))}
5
/>

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.
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 Calling tasks with React hooks.