Define Fragment Input Parameters

A fragment can define parameters that are required or optional. Callers must provide a value for each of the required input parameters, and may provide values for optional ones. Additionally, parameters that are marked for 'writeback' will cause the fragment to automatically writeback the changed/updated value in its variable to the source variable, that was set via the <oj-vb-fragment-param> tag. For details, see Write Back a Fragment Variable Value to the Parent Container.

Input parameters can be reapplied on a fragment after the fragment is loaded. When input parameter values change "mid-cycle", the fragment receives this value automatically, so the fragment can react to the change, as determined by the fragment author. This can be useful, for example, when the input parameter is an expression involving a page variable, and the variable's value changes.

Once a fragment is loaded using input parameters provided by the outer page, if the page variable's value changes, the updated value is automatically picked up by the fragment parameters. This means that the 'live' behavior of variables, where the value change of a 'live' variable triggers changes in other variables, will also automatically update the input parameters that use the same variable.

The following special properties can be applied to fragment variables to determine behavior:

Property	Description
"input": "fromCaller"	Identifies the variable or constant as a fragment input parameter, which the caller of a fragment can provide.
"required": true	Identifies that the variable must be provided by the caller.
"writeback": true	Identifies that the variable's value will be automatically written back to the input parameter variable.

Example 1-50 Fragment where the userId and fragFilterCriterion variables are set as required and fromCaller.

The incidentsSDP variable can use the input param values to initialize its state.

A page that loads a fragment can provide the parameters like this:

incidentShell-page

<oj-vb-fragment id="incLL" name="incidentsListLayout">
  
  <oj-vb-fragment-param name="userId" value="[[ $page.variables.technician.id ]]"></oj-vb-fragment-param>
  <oj-vb-fragment-param name="fragFilterCriterion" value="[[ $page.variables.filterCriterion ]]"></oj-vb-fragment-param>
 
</oj-vb-fragment>

The page JSON defines the variables above like this:

incidentsShell-page

"technician": {
  "type": "object",
  "defaultValue": {
    "id": "rosie",
    "name": "Rosie Riveter"
  }
},
"filterCriterion": {
  "type": "object",
  "defaultValue": {
    "op": "$ne",
    "attribute": "status",
    "value": "closed"
  }
}

In the 'incidentShell-page', the page variables userId and filterCriterion are passed in as parameters to the fragment ("incidentsListLayout-fragment"). In this example, when the filterCriterion page variable changes, it updates the fragment parameters, which in this example is the fragFilterCriterion fragment variable. As a local SDP variable on the fragment references fragFilterCriterion, a re-fetch is triggered by the SDP using the new criteria.

incidentsListLayout-fragment

"userId": {
    "type": "string",
    "input": "fromCaller",
    "required": true
},
"fragFilterCriterion": {
    "type": "object",
    "input": "fromCaller",
    "required": true
},
"incidentsSDP": {
    "type": "vb/ServiceDataProvider",
    "defaultValue": {
      "endpoint": "ifixitfast-service/getIncidents",
      "keyAttributes": "id",
      "uriParameters": {
        "technician": "{{ $variables.userId }}"
      },
      "filterCriterion": "{{ $variables.fragFilterCriterion }}"
    }
}

Example 1-51 Fragment where a list-view of incidents is bound to an SDP variable

In this example, the fragment defines an SDP variable as required by the caller using the (input: fromCaller) property.

Note:

Though this is unusual, the caller can pass a reference to the SDP variable defined by the outer page to a fragment. The reference the fragment variable holds can be used only for the purposes of rendering. Using an action that mutates the state of the variable (such as assignVariables or resetVariables) is not allowed, and will throw errors. Use with extreme caution.

incidentsListLayout-fragment

{
  "variables": {
    "incidentsSDP": {
      "type": "vb/ServiceDataProvider",
      "input": "fromCaller",
      "required": true
    }
  }
}

The page that loads the fragment above will provide the input parameters using the oj-vb-fragment-param sub-component:

incidentsShell-page

<oj-vb-fragment id="incLL" name="incidentsListLayout">

   <oj-vb-fragment-param name="incidentsSDP" value="[[ $page.variables.incidentsSDP ]]">
   </oj-vb-fragment-param>

 </oj-vb-fragment>