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:

• Freecodecamp: How to use REST APIs
• Khan Academy: Introduction to SQL
• Codecademy: JavaScript

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.

1. Select the Customers sample data set.
2. Specify the number of Items that the data set should include.
3. Click Generate API to generate the API with sample data.

Mock API generator

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:

1. Click Create new > Resource and then select REST API.
2. Enter a name for the resource (e.g., Mock Customer API) and enter the API's URL into the Base URL field.
3. 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:

1. Navigate to the Screens tab and click .
2. Right-click the screen and select Rename, then set its name to customers.
3. 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:

1. Navigate to the Code tab.
2. In the customers section, below the Global section, click and select Resource query.
3. 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

With client-side filtering, all necessary data is retrieved first and then filtering occurs within the app. You should use client-side filtering if:

• There is only a limited amount of data.
• The resource does support server-side filtering of data.

With server-side filtering, the query uses the filter value when making the request. The resource then returns only matching data. You should use server-side filtering if:

• There is a large amount of data.
• The resource supports server-side filtering of data.

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:

1. Navigate to the Code tab.
2. 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.

filterCustomers

// 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.

1. Navigate to the Code tab.
2. In the Global section, click and select Variable.
3. 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:

1. Add a Key Value mobile component to the customerDetails screen.
2. 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.

1. Add a Text Input component to the customerDetails screen.
2. 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.

1. Add a Resource query to the customerDetails screen. This must be screen-scoped as globally scoped queries cannot reference any data from a page.
2. Select the mock API resource.
3. 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.

1. Add a Button component to the customerDetails page.
2. 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:

1. The updateCustomer query runs and updates the email address with textInput1.value.
2. After the query successfully runs, it triggers an event handler to navigate back to the customers screen.
3. Navigating back to the customers screen automatically triggers the getCustomers 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.