App functions

Learn how to write reusable logic with app functions.

Sync functions Availability
Cloud-hosted	Private beta	Available on all plans
Self-hosted (3.259 Edge)	Private beta	Available on all plans
Self-hosted (3.148 Stable and later)	Private beta	Available on all plans

App functions enable you to write reusable logic with dynamic parameters. Use functions when you want to perform the same actions on different pages, with different parameters, and return different data.

Functions run only when they are called, and they are stateless—you can't reference a .data or .value property as the source for component data or another value. Functions also replace most usages of app-level preloaded custom JavaScript and the Additional Scope setting in resource queries.

This page covers only app functions, which differ in some ways from workflow functions.

Types of app functions

App functions are one of the many tools that you can use to accomplish your goal. Use this section to identify which use case they are best- suited for.

There are two types of app functions. They work similarly, but are used for different purposes.

Sync functions

Sync functions are a mechanism that enables you to reuse JavaScript code. They run synchronously and are helpful tools for formatting or processing different sets of data in the same way.

They can be called from any JavaScript in your app, including in embedded expressions {{ }}.

For example, you could have a table showing the inventory of all your products. The manufacturer uses one part number, but your business uses a custom part number that combines the manufacturer number and the color, and you want to display your custom part number in a table.

You would create a sync function with two parameters, manufacturer and color. In the JavaScript code input, write return manufacturer + "-" + color. Test out your function with example parameters.

Next, you would create a new column in your Table for your custom part number. Set the value of the column to {{ function1({manufacturer: currentSourceRow.partNumber, color: currentSourceRow.color}) }}, which dynamically provides parameters to the function using the current source row.

Sync functions vs other JavaScript logic

Retool provides a variety of options for writing functional code, each with a distinct purpose:

• Use a sync function if you want to reuse/parameterize simple JavaScript code that has no side effects. You can think of a function as a parameterized, anonymous version of a transformer, whose result is returned directly to the caller rather than being stored in the app state. You can also think of a function as a “pure function” in JS.
• Use a JavaScript query to write JavaScript code that handles app orchestratation (such as control a component or trigger another query), or whose return value should be persisted in app state and be referenceable by other parts of your app.
• Use a transformer to transform data and store the transformed result in app state so it can be referenced by other parts of your app. You can think of a transformer like a selector in React.
• Use a variable to store some state and explicitly update its value from other parts of your app (such as from an event handler).

Resource functions

Resource functions are a mechanism that enables you to reuse resource queries. Resource functions are helpful tools for performing tasks that don't require a persistent state, such as updating or deleting an entry. Resource functions eliminate the need for the Additional Scope setting in resource queries.

Resource functions run asynchronously.

They can be called from a JavaScript query or a Function Call query, but they cannot be called from embedded expressions.

For example, you could use a resource function that utilizes a REST API to delete a set of customers. Using a function in this scenario would be ideal if you might need to delete customers from various different pages.

Create a resource function that accesses an your REST API of customers with one parameter, customer. Update the request URL to include your parameter.

To connect this function to a Button, you first need to create a Function Call query. Then, use the Button's event handler to trigger the Function Call. You can also select a Run Script event handler and call the function from the script.

Calling functions

There are several ways to trigger app functions.

Function Call query

You can use the Function Call query type to trigger your function. Function Call has a state, which means that you can use the output of this query as a static and referenceable value. You must use a Function Call to trigger a Resource Function run from an event handler.

Add a Function Call query in the Code menu. Select the function you want to call, and define the parameters.

Similar to other types of queries, you can also configure event handlers and run behavior for a Function Call.

Inline functions

You can also call functions directly from JavaScript code. Use the following guidelines when calling functions:

• Sync functions can be called anywhere that you can use embedded expressions, or from JavaScript queries.
• Resource functions can only be called from Javascript queries.
• When calling functions from JavaScript queries, you do not need to surround them with brackets.
• Call functions with either positional parameters or named parameters:
  • Named parameters: functionName({param1: value, param2: value}). Use named parameters when your function takes a large number of parameters or has optional parameters.
  • Positional parameters: functionName(value, value). Use positional parameters when your function only has a few parameters.