Work with Flow Artifacts

You use flows to group the pages of your application together.

Work with Page Flows

Each page in your application is contained within a flow. You create a flow to group one or more pages that you might want to treat as an independent unit that performs some function in your application, for example, a flow that contains the pages and artifacts used to register a new user.

Your application can have multiple flows. When you open your web or mobile application in the Navigator, you can expand the flows node to see each of the flows in the application. You can create new flows in your application by clicking the Create Flow icon ( Create Flow icon ) next to the flows node. When you create a flow, a page within the flow is automatically created and set as the flow's default page.

A flow named main is created by default when you create an application. By default, the main-start page in the main flow is set as the default page in the flow, and the main flow is set as the default flow in your application.



When you expand the flows node of a web or mobile application in the Navigator, you can see that a flow consists of the following artifacts and resources.

Artifact Description
Flow artifact

Open the flow artifact in the designer to edit the flow’s metadata, such as the variables, types, chains and functions that can be used in pages in the flow. In the Settings editor for the flow you can set the default page in the flow.

You can expand the flow artifact in the Navigator to see the pages contained in the flow.

Click the Create Page icon ( Create Page icon ) next to the flow artifact to create a new page in the flow.

Page artifact

Open each page artifact in the designer to edit the page’s layout and other page metadata.

Resources

Each flow might contain a resources folder that contains images and translation resources that can be used in pages in the flow. See Work with Application Resources.

Set the Default Page for a Flow

When you create a flow, a start page is automatically created and set as the entry page for the flow. You can change the flow’s default entry page in the Settings editor of the flow artifact.

To set the default page for a flow:
  1. Open the flow artifact in the Settings editor of the application designer.
  2. In the General Settings tab, use the Default Page dropdown list to select the page in the flow that you want to be the default page.

Embed a Flow Within a Page

Each flow in your app can contain multiple sub-flows, enabling you to embed pages within other pages. You use the Flow Container component to create a container in the page where you can then embed sub-flows. After adding the container, you set the default sub-flow displayed in the container in the General Settings tab of the page's Settings editor.

In the page containing the embedded flow, you can only edit the page content outside the Flow Container component, and the embedded pages are not visible on the canvas. After setting the default sub-flow for the page, you can run the app to see the embedded content in the page.

To edit a page in a sub-flow, you need to open it in the Page Designer. To help you visualize the page, the canvas displays the content embedded in the Flow Container component and the content of the parent page, but you can only edit the content in the Flow Container. You set the default page for the sub-flow in the General Settings tab of the sub-flow's Settings editor.

You can use an embedded flow to isolate content from the page containing the flow, and to allow navigation between pages in the sub-flow without leaving the page containing the sub-flow.

To embed a flow in a page:

  1. In the Navigator, locate the flow containing the page where you want to embed the flow.
  2. Under the flow containing the page, click Create Flow ( Create Flow ) and enter a name for the new sub-flow in the Create Flow dialog box. Click Create.
  3. Open the page where you want to embed the new flow.
  4. In the Page Designer, drag the Flow Container component from the Layout category in the Components palette and place it on the canvas.
  5. In the page's Settings editor, select the default sub-flow in the General Settings tab.
    The Default Flow dropdown list displays all flows within the current flow.

Navigate Between Flows in the Root Page

You can use the navigateToItem event in an action chain to open the start page of a flow in your app's root page. You typically invoke the action chain from the drawer or tab elements used to navigate the app.

To use the navigateToItem event in an action chain, you add the Fire Custom Event action to the chain and then select the event and assign the name of the target flow to the event's payload. To use the navigateToItem event, the current page needs to have a flow container that is configured to hold the target flow. Firing the event loads the start page of the target flow into the flow container of the root page.

For example, when you create an app from a template that uses navigation elements such as a tabs or a drawer, the app will contain separate flows that can be loaded into the app's root page. If you create a web app with two flows (for example, "item-1" and "item-2"), and you want to use tabs in your root page to select the flow that is displayed in the flow container, you can create an action chain that fires the navigateToItem custom event. You would create an action chain for each of the flows, and add a click event listener to each tab to trigger the action chain.

To create a new action chain that navigates to the start page in a flow:

  1. In the Designer, open the root page containing the flow container and select the component on the canvas that will open the flow.

    For example, to navigate between flows displayed in the main flow container of a web app you will need to open the root page and select one of the navigation tabs.



  2. In the Events tab of the Property Inspector, click New Event and select the Quick Start option.

    A new action chain opens in the Action Chain editor when you select the Quick Start option.

  3. Type a name for the action chain in the Id field of the Property Inspector.
  4. In the Action Chain editor, drag the Fire Custom Event action into your chain.
  5. In the Fire Custom Event pane, select application:navigateToItem in the Event Name drop-down list.

    The drop-down list contains a list of custom events that can be invoked by the action. The navigateToItem event is prepended with "application:" in the drop-down list and can be used in any page in your app because it is application-scoped.



  6. Click Assign to open the Fire Custom Event window for mapping the navigateToItem payload to the name of the target flow.
  7. Select item in the Target column and select Static content in the editor pane.
  8. Type the name of the target flow (for example, "item-1") in the editor pane of the window. Click Save.