1. Building Responsive Applications with Visual Builder Studio
  2. Develop Applications
  3. Work with Fragments
  4. Pass Data Between a Fragment and Its Parent Container
  5. Sample Scenario: Create a Fragment and Pass Values

Sample Scenario: Create a Fragment and Pass Values

Here's a sample scenario that walks you through how to enable input parameters and pass values between a fragment and the pages that use that fragment.

Say you have a page with employee data in a table. Clicking a row in the page's table brings up the employee's contact information. You have another page that lets users edit an employee's information, including their contact details. To save time and effort, you can define the contact information part of your UI in a fragment and pull it into both pages.
Description of fragment-scenario.png follows
Description of the illustration fragment-scenario.png

In both cases, the page containing the fragment passes the selected employee's ID as an input parameter to the fragment; the fragment receives the ID, retrieves the contact information, and renders it. If a user updates the selected employee (in other words, when the input variable's value changes), the fragment raises an onValueChanged event to refresh the contact details on the page.

  1. First off, set up a fragment to display an employee's contact information. For demonstration purposes, let's assume your fragment looks something like this, with a Heading, an Avatar, and Input Text components:

    Description of fragment-data-designerview.png follows
    Description of the illustration fragment-data-designerview.png

    To provides values to these components, we'll create a type and a variable that holds this information, retrieved from the Employee business object's get_employee endpoint (our data source).

    1. In the fragment where you want to define the contact details, click the Types tab, then click + Type and select From Endpoint.
    2. In the Create Type From Endpoint dialog box, expand Business Objects, select the Get/Employee/{Employee_Id} endpoint under Employee, and click Next.
    3. Select the fields you want to display in the fragment, for example, Picture, Name, Country, Email, and Phone. Click Finish.
    4. Right-click the newly created get_Employee type and select Create Variable. A new get_EmployeeVar (with get_Employee as the type) is created on the fragment's Variables tab.
    5. Switch to the Fragment Designer and bind each component to the get_EmployeeVar variable's corresponding value. For example, to bind the Avatar to the employee's picture, click the Avatar component, then in the component's Data tab, hover over the Src field and click the down arrow to open the variable picker. Select picture under the get_EmployeeVar fragment variable.
  2. Now that we have what we want to display, let's set up how we want employee information to show in the pages that use this fragment. Some pages (like an Employees List page) might simply display the information as read-only data while others (like the Edit Employee page) might need a way to edit it.
    1. On the fragment's Variables tab, define a Boolean-type variable (for example, allowEditing).
    2. Select the allowEditing variable, then under Input Parameters in the Properties pane, select Enabled to pass the variable's value as an input parameter to the pages that use the fragment.
    3. Switch to the Fragment Designer and bind each Input Text component's Readonly property to the allowEditing variable. For example:
      1. Click the Name Input Text component, then in the component's Readonly field in the General tab, use the variable picker and select allowEditing under fragment variables.
      2. Add an exclamation mark (!) before the dollar sign ($) to indicate that the field is read-only when the fragment is not in edit mode.

      Description of fragment-data-readonly-bind.png follows
      Description of the illustration fragment-data-readonly-bind.png

  3. Because we want the selected employee's contact details to be displayed when the fragment is loaded on a page, we'll add a "vbEnter" lifecycle event that triggers an action chain to retrieve the correct employee information. This way, when the fragment is loaded, it takes the employee ID selected on the page, retrieves that employee's contact details from the data source, and passes it to a page-level variable.
    1. Click the fragment's Events Listeners tab, click + Event Listener, and select vbEnter under Lifecycle Events. Click Next .
    2. Select Create Fragment Action Chain and click Finish to create an action chain called vbEnterChangeListener.
    3. Hover next to vbEnterChangeListener (under Lifecycle Event Listeners and vbEnter) and click the Go to Action Chain link.
    4. When the vbEnterChangeListener action chain opens in the editor, drag and drop a Call REST action onto the canvas. In the action's Properties pane, click Select next to Endpoint and choose the Get/Employee/{Employee_Id} endpoint under Business Objects and Employee. Click Select.
    5. Under Input Parameters in the action's Properties pane, click Employee_Id to open the Assign Input Parameters dialog. On the Sources pane, click + next to Fragment and create an empId variable of type number (you can choose to enable empId as an input parameter even now, but for demo purposes, we'll do this in a later step). Click Create. Now drag empId from the Sources pane to Employee_Id on the Target pane. Click Save.
    6. Now double click the Assign Variable action in the palette to add it to the end of the action chain. In the action's Properties pane, select get_EmployeeVar under Fragment in the Variable drop-down list. Hover over the Value property and open the variable picker, then select body under callRestBusinessObjectsGetEmployeeResult under Local.
      Description of fragment-data-loademployee-actionchain-assignvar.png follows
      Description of the illustration fragment-data-loademployee-actionchain-assignvar.png

    7. Switch to the Variables tab and look for the empId variable you created. Select it, then under Input Parameters in the Properties pane, select Enabled to pass the variable's value as an input parameter to the page consuming the fragment. Enter 1 as the Default Value for the input parameter.
    8. With the variable enabled as an input parameter, select Create this variable in a container. This option automatically creates this variable on the page that uses this fragment and wires its value back to the value of the fragment input parameter.
    9. Click the variable's Events tab, then click + Event Listener and select the vbEnterChangeListener action chain that was previously created for you. Click Select.

      Description of fragment-data-inputparameter-empid-onvaluechangedevent.png follows
      Description of the illustration fragment-data-inputparameter-empid-onvaluechangedevent.png

      This way, when the input variable's value (which is the selected employee ID) changes, an "onValueChanged" event triggers the vbEnterChangeListener action chain, telling the fragment to update its content on the page.

  4. Now add the employee contact information fragment to a page.
    1. Open the page with employee data that you want to add the fragment to.
    2. In the Components palette on the Page Designer tab, search for the employee contact information fragment, then drag and drop it where you want it to display.

      Description of fragment-data-container.png follows
      Description of the illustration fragment-data-container.png

      Take note of the fragment's Properties pane on the page. Because we marked the empId fragment input parameter to be autowired on the fragment container, the empId variable is automatically created on the page (look in the Variables tab) and wired back to the fragment input parameter's value (1 by default).

    3. Now let's wrap the Fragment in an If, so that it shows only when a row is selected in the employee table. To do this, select the fragment, right-click, then select Surround and If. If necessary, select the Bind If component in the Structure view; then in the Properties pane's Test condition, use the variable picker to select the empId variable.
  5. Set up the employee table to retrieve information based on the employee ID in the selected row.
    1. Click the table component on the page, select the Events tab, then click + Event Listener and select On 'First Selected Row' to retrieve information about the selected row.
    2. When the TableFirstSelectedRowChangeChain action chain is created, drag and drop an Assign Variable action.
    3. In the action's Properties pane, select the empId variable under Page in the Variable drop-down list. Now use the variable picker on the Value property and select rowkey under Input Parameters.
    4. Return to the page designer and click Live, then select a row in the table to see employee contact information reflected in the fragment based on the ID.
    5. Return to Design view.
  6. Add the same contacts fragments to another page.
    1. In the Page Designer, select the table and add an edit page using the Add Edit Page quick start.
    2. Click Live, select an employee in the table, and click Edit Employee to open the newly created edit page.
    3. Add the contacts fragment to a page, similar to how you added it to the other page previously.
    4. To make sure the selected employee ID is passed between the page and the fragment, select the Fragment and on the empId input parameter in the Properties pane, select the employeeId variable.
    5. Because we want the fragment's contact information to be editable on this page, select the allowEditing input parameter in the Properties pane.
  7. As a final step, click the Preview icon in the header.
    1. Select a row in the table to see the employee's contact details display on the right. Notice how contact details from the fragment show as read-only values.
    2. Click Edit Employee for the selected row to view and edit the employee's information, including contact details, on the Edit Employee page. Notice how contact details from the fragment show as editable values.