Passing Data

As you build your app, you'll often encounter the need to pass through or transfer data from one page to another. For instance, when a user taps on a ListView item, you may want to send a todo item to the next page to display its details.

This process of passing data between pages is accomplished using parameters.

Passing data can only be tested in Run and Test Mode (it can not be tested in Preview Mode).

How to pass data

To enable data passing between pages, start by defining the parameter(s) on the destination page. Next, on the first page, add the navigate action and pass the desired parameter value. On the subsequent page, you can utilize the parameter value just as you would with any other variable.

The figure below illustrates the data passing flow:

What you can pass

You can pass any supported data from one page to another via page parameter(s). You can think of a page parameter as a variable that holds the value being passed from one page to another.

If you are using Firestore Database, most of the time, you would pass the Document (an actual record inside the Firestore collection) and Document Reference (points to actual document) between the pages.

When to use which data type

Let's see what all types of data you can pass and when to use them:

Integer: To pass numbers such as 100, 4302, 50000, etc.
Double: To pass a decimal number such as 12.43, 3233.50, 65.5666, etc.
String: To pass plain text such as title, description, etc.
Image Path: To pass the URL of the uploaded image.
Video Path: To pass the URL of the uploaded video.
Audio Path: To pass the URL of the uploaded audio.
Boolean: To pass either a True or False value.
Color: To pass color value.
Document Reference: To pass a reference of a document. Passing a document reference helps you fetch the document data. For example, fetching user's details based on the user reference.
Document: To pass the actual document (i.e., a Firestore document). For example, passing the whole todo item to the next page.
DateTime: To pass the date and time value.
JSON: To pass the JSON value such as {"firstName":"John", "lastName":"Doe"}.
TimestampRange: To pass the start date-time and end date-time values.
Lat Lng: To pass the latitude and longitude of a particular place.
GooglePlace: To pass the GooglePlace data.
Uploaded File (Bytes): To pass the uploaded file in Bytes.

Common use cases for passing data

This section provides instructions on how to build some everyday use cases in your app.

Here are they:

1. Passing data to the next page

Let's see how to send the typed message to the next page.

The steps to pass data from one page to another are as follows:

If you have already created your pages, you can skip to Step 3.

1.1 Building the first page

Before you pass any data to the next page, you must capture the data on the first page. To do so, you can add a TextField and Button. Here's how it looks:

1.2 Building the second page

Now, create a second page to receive the data. To show a message on the second page, simply add a Text widget to a page.

1.3 Add a parameter on the second page

The parameter on the second page will be used to hold the data from the first page.

To add a parameter:

Select the second page.
On the right side, find the Page Parameters section and click on the + button.
Click on + Add Parameter and enter the Parameter Name (e.g., message).
Set the Type to String and check the Required option because this parameter is mandatory(must contain a value) for this page to work. This allows you to accept a plain text value from the previous page.
Optionally you can also add a default value to this parameter which will be displayed if the incoming value is null or empty.
Click Confirm.

1.4 Pass data from the first page

To pass data from the first page:

Select the first page. On the Button widget, add the Navigate To action.
Select the page you want to navigate to (e.g., PageB).
Click on the Pass button below. Now the parameter (created on the second page) will be displayed. Tip: You can also define a new parameter for the second page from here itself by clicking on the + Define button.
Click on the parameter name. This will open the set from variable menu.
Now select Widget State -> TextFieldName (that accepts the message).

1.5 Showing parameter value in UI element

To show data from parameters in the Text widget:

Select the second page.
Select the Text widget, move to the properties panel, and click Set from Variable.
Select the Page Parameters > parameter name (defined on this page).
Click Confirm.

2. Passing ListView item

Let's see how to pass the ListView items (from Firestore Database or API call) to the next page (e.g., a details page).

Passing a record from a ListView to a details page includes the following steps:

If you already have a list of items displayed on a screen, you can skip to Step 3.

2.1 Show list of items

Add the first page with ListView and display some items using the Firestore Database or API call.

2.2 Building a details page

Add a page with some Text widgets that look like the below:

2.3 Adding parameter on the details page

To add a parameter:

Select the details page and then select the first widget with the page name.
On the right side, find the Page Parameters section and click on the + button.
Click on + Add Parameter and enter the parameter name (e.g., todoItem).
Set the Type of item you will receive on this page.
1. To receive the Firestore document, set it to Document and choose the Collection Type. This allows you to carry a single document/record from the previous page.
2. To receive the item of API response, set it to JSON.
Click Confirm.

2.4 Passing item

An item inside the ListView can be passed to the next page by adding a navigate action.

To do so:

On ListTile, add the navigate action.
While adding this action, click on the Pass button below. Now the parameter (created on the second page) will be displayed. Tip: You can also define a new parameter for the next page from here itself by clicking on the + Define button.
Click on the UNSET and select the source of the item:
1. To pass the Firestore Document, select the [collection_name] Document and then select Document (collection_name).
2. To pass the item of API response, select the [dynamic_children_variable_name] item.
Click Confirm.

2.5 Show item details from the parameter

Once the item is passed to the next page, you can display it using the parameter.

To display item information from parameter:

Select the Details page.
Select the Text widget, move to the properties panel, and click on the Set from Variable. This will open a popup on the left side.
Select the Page Parameters > parameter name (defined on this page).
1. If it's a Firestore Document, set the Document Properties to the Field that you want to display.
2. If it's a JSON, set the Available Options to JSON Path and JSON Path to the custom JSON path. See how to create a JSON path.
Click Confirm.

3. Passing a document reference

A Document Reference points to the location where the record (actual data) resides in the Firestore collection. You can use the document reference to retrieve the additional data associated with that record. For example, you could use the user document reference inside the Todo document to identify the user and its details (e.g., name, location, etc.).

In Firestore Data Manager, the document reference looks like this:

When you should pass document reference

Sometimes, when you pass data to another page, it might not contain all the data to be displayed on the another page. In that case, you can pass a document reference and add a query to pull the required information.

Here's an example of this situation:

The Todo detail page shows the profile picture of the user who created it.
When a user clicks on the profile photo on the Todo Details Page, you want to open the next page (i.e., UserDetails) that shows the user's additional information, such as user name and email.
But the Todo Details page only contains the user photo and does not have the additional information you want to display.

For this situation, you'll build an example that passes the document reference of the user to the next page and then query additional user details.

Passing a document reference to another page includes the following steps:

If you have already created your pages, you can skip to Step 3.

3.1 Building Todo details page (first page)

To show a list of documents (query collection), find the instructions here.

To show a single document data, follow the instruction here.

The Todo details page looks like this:

3.2 Building a user details page (second page)

The user details page consists of CircleImage widget and two Text widgets:

3.3 Adding a parameter on the user details page

To add a parameter:

Select the User Details page and then select the first widget with the page name.
On the right side, find the Page Parameters section and click on the + button.
Click on + Add Parameter and enter the parameter name (e.g., userReference).
Set the Type to DocumentReference. This allows you to carry a single document/record reference from the previous page.
Set the Collection Type to the Firestore collection that holds the data.
Click Confirm.

3.4 Passing item reference

A document reference can be passed to another page by adding a navigate action and passing a reference in a parameter on the tap of any widget.

To add an action:

Select the first page (page with ListView).
Select ListTile, head over to Properties Panel > Actions and click + Add Action.
Search and select the Navigate To action.
Select the page you want to navigate to.
Click on the Pass button below. Now the parameter (created on the second page) will be displayed. Tip: You can also define a new parameter for the second page from here itself by clicking on the + Define button.
Set the Source to a document and then set the Document Properties to the Field that holds the document reference (e.g., created_by field).
Click Confirm.

3.5 Query a document based on document reference

Once you have access to the document reference, you can use it to query the additional information on a page or a widget. The ideal place to query a document is at the page level so that you can access the document data from anywhere within a page.

Select the next page (User details).
Click on the Backend Query tab (on the right side of your screen).
Set the Query Type to Document from Reference.
Scroll down to find the Collection dropdown and change it to your collection.
Click on the UNSET and select the parameter name that holds the document reference.
Click Confirm.

3.6 Showing data in UI elements

To show data on the user details page:

Select the Image widget, move to the property panel, and scroll down to the path property.
Click on the Set from Variable text. This will open a popup on the left side.
1. Select the document (retrieved in the previous step) as a source (e.g., [collection_name] Document).
2. Now select the field that holds the image URL path.
Similarly, show the data for other UI elements.