Working with Data Zones

Any time you wish to work with dynamic data, such as from a third-party API or user-submitted form data, you'll need to use the Data Zone component. Within this component you can specify what data to use and from where it should be retrieved. Any component placed within the Data Zone can access its data.

Specifying the Data

There are three different ways to attach data to a Data Zone:

• Providing the data directly
• Selecting a Flow to provide data
• Selecting user input from a form on the page

Providing Data Directly

1. Select a Data Zone component on the canvas
2. Open the Settings Panel in the Right Sidebar

The "Data" field allows you to specify data for the Data Zone. You can provide a text value here, but chances are that won't be particularly useful. Instead, you can also use the Data Picker and FQL to select any data that's available in the current context. To open the Data Picker, either hover over the "Data" label and click the plus (+) icon, or right click on the "Data" field and click "Attach Data."

For example, you could select the value of an Environment Variable or an item that exists in Global State. In the following example, the user's operating system is selected using the DeviceInfo data source.

Using Flows

A common use case for sites and apps is to use data from APIs. For this case, you will need to either use a Flow that is provided by a Shipcode Library or create your own custom Flow.

Making a Custom Flow

In order to use a Flow to provide data to a Data Zone, the Flow needs to use the Update Props node. This instructs the Flow to attach the data to your Data Zone.

The following example shows a basic Flow that requests data from a GraphQL API and then sets the data:

You do not need to specify the "Layout ID" field in the "Update Props" node when running a Flow from a Data Zone. The data will be provided to the Data Zone automatically!

Selecting a Flow

You can select which Interaction(s) will run a given flow. Typically, you will want the Flow to run when the screen is displayed to the user, so you will use the "On Initialize" interaction. However, you can also run Flows when the user navigates away from the screen or upon user interactions such as press and hover.

1. Select a Data Zone on the canvas
2. Open the Interactions Panel from the Right Sidebar
3. Click the dropdown under the appropriate interaction type
4. Select the desired Flow
5. If the Flow requires any inputs, it will prompt you for these values

Using Form Data

You can build interactive forms by defining a form-type Data Zone and placing inputs inside of it.

1. Drag a Data Zone component onto the canvas
2. Open the Settings Panel from the Right Sidebar
3. In the "Source" dropdown, select "Form"
4. Drag components such as "Text Input" and "Selection Group" into the Data Zone
5. Assign each component a distinct ID

The data from the form elements will be available in the Data Zone's data in the "controls" property, keyed by the element ID. For example, an input given the ID "email" can be accessed from $(DataZone).controls.email.value

Using the Data

Any component that is placed within the Data Zone on the canvas will have access to its data. You can use the "attach data" functionality to use the data for virtually any property: a Text component's text, an Image component's source, a View's background color, and so on.

In the following example, a Data Zone will be used to power a Text Component:

1. Add a Data Zone component to the canvas
2. For this example, simply provide a text value for its data, such as "Testing 123"
3. Add a Text component inside of the Data Zone component
4. With the Text component selected, open the Settings Panel on the Right Sidebar
5. Right-click on the "Text" property and click "Attach Data"
6. From the Data Picker, select the arrow to the right of the Data Zone
7. Select the "data" attribute
8. Note that the Text component now displays "Testing 123"