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 your mobile apps to 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 product management mobile app on Retool. You can browse through a list of products, presented in a card layout, and select one to update its details.

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.

This guide uses Retool Database as the resource. Retool Database is a fast, secure solution for saving and editing data to use in Retool apps. It combines a PostgreSQL database with a spreadsheet-like interface to manage your data.

To add test data to Retool Database, download this CSV and then follow the steps below.

1. Log in to Retool. If you don't have an account, sign up for free.
2. Click the Resources tab, then select Retool Database.
3. Click Import CSV > Into a new table.
4. Select the products.csv you downloaded.
5. Name the table products, and set the id and quantity Field type to int4.
6. Click Create table.

2. Create a new mobile app

To get started, sign in to your Retool organization 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 guide, the demo content will be removed.

When editing a Retool Mobile app, the App IDE renders your mobile app on the canvas and includes panels on the left and right. These panels contain sections for managing your app's overall layout through screens and components.

The App IDE for Retool Mobile

3. Prepare screens

You create multi-page mobile apps by organizing mobile components into separate screens. 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. The product management app uses two screens, one for displaying products and one for editing the selected product's name.

To configure the screens, rename peopleListScreen to products, and peopleDetailsScreen to editProducts. Update their titles as well, and then delete myProfileScreen.

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.

4. Get product data

Retool automatically creates a query, getRows, for you to get started. Select the query and in the query editor, write a query to retrieve product data from the products table. Then rename the query to getProducts and click Save & Run.

select
  id,
  name,
  quantity,
  unit_price_cents,
  image_url,
  updated_at
from
  products

5. Display products for selection

The Card Collection mobile component presents data using a prebuilt card layout. You can use Card Collection to display product data without needing to build any type of layout.

Make sure the products screen is selected and then click on the collectionView1 component. Retool added this automatically when you created the app.

Retool automatically maps your query's data to present as cards, and populates values based on common usage (e.g., using item.name for the card's title). You can change these values as needed in the Mapped options section of the Inspector. Set the value for Body to Quantity: {{ item.quantity }} and the value for Source (under the Media section) to {{ item.image_url }} to display the product's image.

You can also adjust the style and layout of cards using the Appearance section of the Inspector.

6. Add a product search field

You can add a search box to quickly filter the list of products, making it easier to find what you're looking for. Add a Text Input mobile component to the Products screen, then change its Label to Search.

Retool Mobile organizes mobile components vertically in a column layout by default, with additions displayed at the bottom of the Component section. You can reorder mobile components in the mobile panel using drag-and-drop, which allows you to position the Text Input at the top of the screen.

You can reference values and write JavaScript almost anywhere in your Retool apps. Update getProducts to include the input value when retrieving products:

select
  id,
  name,
  quantity,
  unit_price_cents,
  image_url,
  updated_at
from
  products
where
  name ilike {{'%' + textInput1.value + '%'}}

7. Select a product

This mobile app enables users to edit a product's name. When a user selects a product, the app opens the Edit products screen as a modal so the user can update the product's information.

First, configure the app to show Edit products on product selection. Retool uses event handlers to trigger queries or other actions in response to user events, such as selecting a product.

Select collectionView1 within the products screen and open the existing event handler in the Interaction settings of the Inspector. Then make sure the event handler is configured with the following settings.

Setting	Value	Description
Event	Press	Trigger the specified action when the user selects a product.
Action	Navigation	Perform the specified navigation.
Method	Open modal	Display the Edit products screen as a modal.
Screen	editProducts	The screen that appears when the user selects a product.

Now, select a product in the collection to navigate to Edit products, which is currently empty. Delete any existing components on this screen using the Components section in the left panel.

Next, add a Text Input mobile component to Edit products and update the following settings using the Inspector. If needed, remove any existing components on this screen.

Setting	Value
Label	Product name
Default value	{{ collectionView1.selectedItem.name }}

The selectedItem property contains data about the currently selected product in collectionView1. Now when you select a product from the list, the text field displays the name of the selected product.

8. Edit the selected product

Updating a product's name requires a second query to write those changes back to the database. Open the code list and click + to create a new resource query, select the Retool Database as your resource, then select GUI mode to construct a query that can write data.

Setting	Value	Description
Table	products	Interact with the products table.
Action type	Update an existing record	Update an existing product record.
Filter by	id = {{ collectionView1.selectedItem.id }}	Use the id of the selected product to determine which record to update.
Changeset	name : {{ textInput2.value }}	Update the name with the current value of textInput2.

Queries can trigger event handlers on success or failure. Add a Success event handler to refresh the product list to reflect the changes:

Setting	Value	Description
Action	Control query	Trigger the specified query.
Query	getProducts	Reload the query that retrieves the list of products.

Add a second Success event handler to take the user back to Products screen. Make sure to save the query again.

Setting	Value	Description
Action	Navigation	Perform the specified navigation.
Method	Back	Navigate back to the first (root) screen.

9. Confirm changes

To update the product name, add a Button mobile component to the Edit Products screen and update its Text setting to Save.

Rather than update the name immediately when a user presses the button, your app can display an action sheet to present a set of options that trigger actions, such as triggering the query to update the product name. Add an event handler to the button and set the Action to Action sheet.

Action sheet to confirm changes

Set the action sheet's Title to Update product name? and Description to Change "{{ collectionView1.selectedItem.name }}" to "{{ textInput2.value}}"?. This displays the current name and the updated name entered into the text field.

Click + New to add a menu item that confirms changes.

Setting	Value	Description
Title	Confirm changes	The text to display.
Action	Control query	Trigger the specified query.
Query	updateProduct	The query that updates the product name.

Add another action to revert the changes entered into the text field.

Setting	Value	Description
Text	Reset	The text to display.
Action	Control component	Control the specified component.
Component	textInput2	The component to control.
Method	Reset value	Reset the value of the component.

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.

Open mobile apps using the QR code

Wrap up

You've now successfully built a mobile app that retrieves product data and presents it in a card layout, and enables you to select a product and update its name.