Retool Mobile tutorial
A hands-on introduction to Retool Mobile.
Retool Mobile enables you to quickly build mobile apps using a drag-and-drop interface and mobile component library. You can connect almost any database and API to Retool, allowing your workforce to interact with your data using native apps for iOS and Android.
This tutorial explains how to build a basic customer management mobile app on Retool. You can browse through a list of customers, select one to view details, and update their email address.
Prerequisites
Familiarity with common technologies like APIs, SQL, and JavaScript is expected to complete this tutorial. If you need to learn more about these technologies, try the following online learning resources:
What you'll learn
After completing this tutorial, you'll gain the necessary knowledge to:
- Connect your data sources as resources.
- Assemble user interfaces using drag-and-drop components.
- Query resources to interact with data.
- Connect queries and components to manipulate data.
- Extend your app's functionality with JavaScript queries and transformers.
These terms and concepts may not be familiar but you'll learn about them as you work through the tutorial.
1. Create a resource
Retool can interact with almost any API or database, and includes native integrations for many different data sources. After you configure a resource, you can build apps using your data.
Use the mock API generator below to generate a fully functional temporary REST API with sample data that you can use.
- Select the Customers sample data set.
- Specify the number of Items that the data set should include.
- Click Generate API to generate the API with sample data.
The mock API is for testing purposes only and does not require authentication. Do not attempt to use it for production purposes or with any type of sensitive information.
Next, sign in to your Retool organization and navigate to the Resources page. To add the mock API as a resource:
- Click Create new > Resource and then select REST API.
- Enter a name for the resource (e.g.,
Mock Customer API
) and enter the API's URL into the Base URL field. - Click Create resource.
After creating the resource, you are prompted to create a new app or return to the Resources page.
Return to the Resources page and then navigate to the Apps page.
2. Create a new mobile app
Navigate to the Apps page and click Create new > Mobile app. Every new mobile app is initially configured with a demo that uses a preconfigured interface and sample data for you to try out. For the purposes of this tutorial, remove the demo content when you open the app.
When you develop a Retool Mobile app, the Mobile IDE renders your mobile app on the canvas. On the left are tabs that contain sections to manage different aspects of the app, such as Screens and Components. When you select a screen or component, the Inspector on the right provides you with configurable settings.
3. Prepare screens
You create multi-screen mobile apps where each screen functions as a separate page with its own code and components. You can navigate between each screen using the tab bar or by interactions that trigger event handlers, such as pressing a button or selecting an item from a list. Retool only evaluates the code and components of the screen currently in view, ensuring that complex mobile apps are performant.
Add new screens
This app uses two screens, one for displaying a list of customers and another for editing the selected customer's details. To add these screens:
- Navigate to the Screens tab and click .
- Right-click the screen and select Rename, then set its name to
customers
. - Repeat the process to add a screen named
customerDetails
.
Once done, right-click the customers screen and select Set as default screen.
After adding the new screens, right-click on each existing screen and select Delete.
Each screen has a title to identify which screen a user is currently viewing. This is displayed at the top of the app and in the navigation bar. Set the title for the customers and customerDetails screens by selecting one and updating the Title in the Inspector to Customers
and Customer details
, respectively.
4. Get customer data
You write resource queries to interact with resources, such as SQL statements or API requests. Queries can be either screen-scoped or globally scoped. For the purposes of this tutorial, add a page-scoped query:
- Navigate to the Code tab.
- In the customers section, below the Global section, click and select Resource query.
- Select the resource you created for the mock API.
When you select an API resource, the code editor contains a set of inputs for you to write an API request. APIs commonly use different endpoints based on the type of data used. You don't need to specify an endpoint to get customer data from the mock API. Since API queries default to using a GET request, no further configuration is needed. Click Save & Run to save the query and perform the API request.
The query results appear below the code editor. The mock API returns a list of customer data that you will use to populate the mobile app's UI in the next step.
Before continuing, delete the demo queries that were included when you created the app. Right-click on each query and then select Delete.
5. Display a list of customers
The List Collection mobile component presents data using a list layout. You can use List Collection to display customer data without needing to build any type of repeatable layout.
Switch to the customers screen and then navigate to the Component tree tab. Click and then select the List Collection component.
Retool automatically maps the most recently run query's data to the component and populates values based on common usage (e.g., using item.email
for the an email address). Update the List Collection component's settings in the Inspector to the following:
Setting | Value | Description |
---|---|---|
Title | {{ item.first }} {{ item.last }} | Use the customer's name for the list item title. |
Body | {{ item.email }} | Use the customer's email address for the list item body. |
Media type | None | Since the customer data has no images, disable the list item image. |
Action type | Label and icon | Display an optional label and icon on the right-side of the list item. |
Label | Empty | Clear the label text to remove it. |
6. Add a customer search field
You can add a text input field that dynamically filters the list of customers, making it easier to find what you're looking for. The Search Bar mobile component is a preset of the Text Input mobile component, which is preconfigured with a search icon already.
Add a Search Bar mobile component to the customers screen, then change its Label to Search
from the Inspector.
Mobile components are arranged vertically by default. When you add the Search Bar component, it appears below the List Collection component. In the Component tree tab, click and drag the Search Bar component to position it above List Collection.
7. Filter the list of customers
To use the input value of Search Bar to search customers, you can use either client-side or server-side filtering. For the purposes of this tutorial, the app uses client-side filtering.
Client-side vs. server-side filtering
You can use {{ }}
embedded expressions to write JavaScript almost anywhere in Retool. The mock API supports filtering with the filter
URL query string, and you can reference the value of Search Bar directly in the query.
Filter with a transformer
You can use a JavaScript transformer to perform client-side filtering of query results. Transformers dynamically update whenever there is a change to reference values.
To create a transformer:
- Navigate to the Code tab.
- Click and select Transformer.
Next, write a JavaScript statement that filters the results based on the value of Search Bar using the filter()
JavaScript method.
// Reference the customer data from the query
const data = {{ getCustomers.data }}
function filterCustomers(searchString) {
// Search customers based on first + last names
const filteredData = data.filter(customer => {
// Combine the first and last names into a single, lowercase string
const fullName = `${customer.first} ${customer.last}`.toLowerCase();
return fullName.includes(searchString.toLowerCase());
});
// Return the results
return filteredData;
}
// use the filterCustomers function with the value of the Search Bar component
return filterCustomers({{ searchBar1.value }});
To use the transformer results, update the Data source of the List Collection component to use filterCustomers
.
7. Select a customer and view details
This mobile app will allow users to view customer details. When a user selects a customer, the app navigates to the Customer details screen which will display customer information.
Navigate to another screen
First, configure the app to show the customerDetails screen when selecting a customer. Retool uses event handlers to trigger queries or other actions in response to user events, such as selecting a product.
Select collectionView1
within the customers screen and add an event handler from the Interaction settings of the Inspector. Configure the event handler with the following settings:
Setting | Value | Description |
---|---|---|
Event | Press | Trigger the specified action when the user selects a customer. |
Action | Navigation | Perform the specified navigation. |
Method | Navigate to screen | Navigate to the customerDetails screen. |
Screen | customerDetails | The screen that appears when the user selects a customer. |
Click on a customer to test the event handler. The customerDetails screen doesn't contain any components and is currently empty.
Store the selected customer data
Code and components are screen-scoped or globally scoped. Since the getCustomers
query is scoped to the customerDetails
screen, its cannot be referenced elsewhere. You use variables that are globally scoped to tempoarily store data and make it available in other screens.
- Navigate to the Code tab.
- In the Global section, click and select Variable.
- Rename the variable to
selectedCustomer
.
The List Collection component's selectedItem
contains the data of a selected item, which is available at {{ item }}
when configuring an event handler. Create another event handler to store this data in a variable.
Setting | Value | Description |
---|---|---|
Event | Press | Trigger the specified action when the user selects a customer. |
Action | Set variable | Perform the specified navigation. |
State | selectedCustomer | The variable in which to store data. |
Method | Set value | Set a variable value when the event handler runs. |
Value | {{ item }} | The selected item. |
When you select a customer, the app loads the customerDetails
screen.
View selected customer data
selectedCustomer.value
is an object with the selected customer data. To view this data:
- Add a Key Value mobile component to the
customerDetails
screen. - In the Inspector, set Data to
{{ selectedCustomer.value }}
and Header to{{ selectedCustomer.value.first }} {{ selectedCustomer.value.last }}
.
The selected customer data appears in the Key Value component automatically. Its header also displays the customer's name.
8. Update the customer's email address
Now that the app displays selected customer information, the next step is to make changes and save them back to the resource. For the purposes of this tutorial, the app enables you to modify the customer's email address.
- Add a Text Input component to the
customerDetails
screen. - Set the Default value of the component to
{{ selectedCustomer.email }}
from the Inspector.
Add a query to update the email address
The Text Input component automatically displays the email address of the selected customer. You add another resource query to save changes, similar to the query that retrieves customer data.
- Add a Resource query to the
customerDetails
screen. This must be screen-scoped as globally scoped queries cannot reference any data from a page. - Select the mock API resource.
- Rename the query to
updateCustomer
.
APIs commonly use PATCH
or PUT
methods to modify existing data. These request methods require the object's identifier (ID). This is also stored in selectedCustomer
. Update the query with the following configuration:
Setting | Value | Description |
---|---|---|
Action | PATCH | Use the PATCH method to modify an existing object. |
URL | {{ selectedCustomer.value.id }} . | This updates the API endpoint to use the customer ID (e.g., https://example.com/customers/1 ) that determines which object to update. |
Body (key) | email | The property to update. |
Body (value) | {{ textInput1.value }} | The value with which to update. |
Queries also support event handlers. Once a customer email address is updated, the app should return to the customers
screen. Add an event handler with the following configuration:
Setting | Value | Description |
---|---|---|
Event | Success | Trigger the specified action when the query successfully runs. |
Action | Navigation | Perform the specified navigation. |
Method | Back | Navigate back to the previous screen. |
When the event handler runs, the app returns to the customers
screen. The getCustomers
query automatically refreshes so the customer list reflects the changes.
Add a button to save changes
The final step is to add a button that saves the changes.
- Add a Button component to the
customerDetails
page. - Configure it with an event handler that uses the Control query action and select the
updateCustomer
query.
After you update email address and press the button to save changes, the following sequence occurs:
- The
updateCustomer
query runs and updates the email address withtextInput1.value
. - After the query successfully runs, it triggers an event handler to navigate back to the
customers
screen. - Navigating back to the
customers
screen automatically triggers thegetCustomers
query, updating the customer data in the app.
Test your mobile app
Now that your app is complete, it's time to test it on your mobile device. Click Go to app in the top right to open the mobile app as a progressive web app (PWA). Scan the QR code with your iOS or Android device to launch it in the Retool Mobile app. You use this app to browse and launch any of the mobile apps you build.
If you don't have the app installed already, your device is automatically routed to the iOS App Store or Google Play.
Wrap up
You've now successfully built a mobile app that retrieves customer data and presents it in a list layout, and enables you to select a product and update its name.