utils methods
JavaScript API methods for interacting with apps.
Use the utils
JavaScript API methods to perform actions and control behavior.
util
methods are not available within transformers.
utils.changeLocale()
Change the current user's locale.
value
requiredstring
The locale to set. Supports ISO-639 language codes.
Example
Change the current user's locale to en-US
.
utils.changeLocale('en-US');
utils.confetti()
Display confetti animation.
Example
Display the confetti animation.
utils.confetti();
utils.copyToClipboard()
Copies the given string to the user's clipboard.
value
requiredstring
The string to copy.
Example
Copy the selected cell contents of table1
to the user's clipboard.
utils.copyToClipboard(table1.selectedCell.data);
utils.downloadFile()
Generates a file containing the specified data which is then downloaded by the user's browser.
To download data from a Table component, use utils.exportData()
.
data
string | object
The data to download. To download Base64-encoded data, provide an object that contains the parameter base64Binary
and encoded value.
base64Binary
requiredstring
The Base64-encoded data to download.
fileName
string
The downloaded file name. Defaults to file
.
Examples
- Download YAML
- Download CSV
Download the results of getUsersQuery
as a YAML file named users-data
.
utils.downloadFile(getUsersQuery.data, "users-data", "yaml");
Download BASE64_STRING
as a CSV file named users-data
.
utils.downloadFile({ base64Binary: BASE64_STRING }, "users-data", "csv");
utils.downloadPage()
Generates a PDF file of the current view which is then downloaded by the user's browser. It excludes Custom, HTML, and IFrame components.
fileName
string
The downloaded file name. Defaults to file
.
options
object
An object that controls selector and component inclusion or exclusion, and PDF formatting.
componentsToExclude
array
A list of components to exclude from the PDF.
componentsToInclude
array
Any components to include in the PDF. Excludes all other components.
fullscreen
boolean
Whether to download the page in presentation mode. Defaults to false
.
scale
number
The resolution of the page to export. Defaults to window.devicePixelRatio
.
selectorsToExclude
array
A list of selectors to exclude from the PDF.
selectorsToInclude
array
Any selectors to include in the PDF. Excludes all other selectors.
Example
Download a PDF of the current view, excluding container1
and its nested components, as users_dashboard.pdf
.
utils.downloadPage("users_dashboard", { componentsToExclude: ["container1"] });
utils.exportData()
Generates a file containing data for the specified Table component which is then downloaded by the user's browser.
data
requiredobject
The table data to export. Use utils.exportData()
to reference a Table component's data
, normalizedData
, or displayedData
.
fileName
string
The file name of the downloaded file. Defaults to export
. If fileType
is xlsx
, fileName
must adhere to Excel worksheet naming guidelines.
fileType
string
The file type for the downloaded file. Defaults to csv
. If fileType
is xlsx
, fileName
must adhere to Excel worksheet naming guidelines.
Example
Download usersTable.data
as a CSV named usersData
.
utils.exportData(usersTable.data, "usersData");
utils.getCurrentPosition()
Retrieves the user's current geographical location, if allowed by the user.
options
object
The Base64-encoded JSON file to parse.
onSuccess
requiredfunction
A callback function to trigger when the method runs successfully.
Return value
Details
coords
A callback function to trigger when the method runs successfully.
Details
latitude
The position’s latitude in decimal degrees.
Details
longitude
The position’s longitude in decimal degrees.
Details
speed
The velocity in meters per second.
Details
accuracy
The position’s accuracy in meters.
Details
altitude
The position’s accuracy in meters.
Details
altitudeAccuracy
The position’s accuracy in meters.
Details
heading
The direction of travel in degrees from true north.
Details
timestamp
The date and time location information was retrieved, in UNIX time.
Example
Retrieve the coordinates of the current user and calls updateMap
upon success.
await utils.getCurrentPosition({
onSuccess: function (data) {
updateMap.trigger();
},
});
utils.getDataByObjectURL()
Convert the contents of a blob:
or file://
URL to a Base64-encoded string. Returns a Base64-encoded string.
value
requiredstring
The blob or URL to convert.
Example
Convert a captured signature image to a Base64-encoded string and pass it to a SQL query using additionalScope.
const base64Data = await utils.getDataByObjectURL(signature1.value);
sqlQuery1.trigger({ additionalScope: { base64Data } });
utils.openApp()
Opens a Retool app. The app must be in the same organization as the caller of openApp
.
appUuid
requiredstring
The unique identifier of the Retool app to open. Available in retoolContext.
options
object
Additional configuration options.
queryParams
object[]
A list of query parameters to include when opening the app.
newTab
boolean
Whether to open the app in a new tab. Defaults to true
.
Example
Open an app with the query parameters source=updateUsersApp
.
utils.openApp("371ac2f8-3aaf-11ed-8b80-836b0df4638d", {
queryParams: { source: "updateUsersApp" },
});
utils.openUrl()
Open the specified URL.
url
requiredstring
The URL to open.
options
object
Additional configuration options.
forceReload
boolean
Whether to prevent client-side routing and force a page reload. Defaults to false
.
newTab
boolean
Whether to open the URL in a new tab. Defaults to true
.
Example
Open Retool Docs in the current tab.
utils.openUrl("https://docs.retool.com", { newTab: false });
utils.playSound()
Plays the specified sound.
url
requiredstring
The URL for a sound asset to play (e.g., an .mp3 file).
Example
Plays the success.mp3
file.
utils.playSound('https://s3-us-west-2.amazonaws.com/s.cdpn.io/3/success.mp3')
utils.serializePage()
Serializes the current Retool page as a Base64-encoded PDF string. Returns the Base64-encoded string.
options
object
Additional configuration options.
selectorsToExclude
array
An array of CSS selectors to exclude from the serialized page.
componentsToExclude
array
An array of components to exclude from the serialized page.
selectorsToInclude
array
An array of CSS selectors to include in the serialized page.
componentsToInclude
array
An array of components to include in the serialized page.
scale
number
The resolution of the serialized page. Defaults to window.devicePixelRatio
.
Example
Serializes the current view, excluding container1
and its nested components.
let pdf = await utils.serializePage({ componentsToExclude: ["container1"] });
utils.showNotification()
Shows a notification message on the top right corner of the screen.
options
object
Optional configuration for the notification.
title
string
The notification title. Defaults to Notification
.
description
string
The notification text.
notificationType
'info' | 'success' | 'warning' | 'error'
The notification type. Defaults to info
.
duration
number
The length of time, in seconds, to display the message. Defaults to 4.5
.
Example
Display a success message after deleting a user.
utils.showNotification({
title: "Deleted user",
description: "Successfully deleted user.",
notificationType: "success",
duration: 3,
});