Customize How a Fragment Variable is Displayed in the Properties Pane

Customize the UI component displayed for fragment input parameters in the Properties pane, which can make the task of editing those parameters in the Page Designer easier.

When working with a fragment in the Page Designer, the fragment's Properties pane by default displays text field components for editing the values of fragment variables enabled as input parameters. For some input parameters, a different UI component can make editing the parameter easier or more intuitive. For example, if a parameter is used to specify a date, a Date Picker component might be easier to use than a text field. To do this, you customize the fragment variable, so that a date picker shows instead of a text field when the fragment's input parameters are edited in the Page Designer:

Description of the illustration fragment-variable-pi.png

To customize the UI component displayed for a fragment variable in the Properties pane, you use the Design Time tab in the Variables editor. You can also edit the fragment's JSON directly in the JSON editor.

Note:

Some UI customization options are not available in the Design Time tab. You'll need to edit the JSON directly to configure these advanced options. See Customize Fragment JSON with Metadata for a list of options.

Customize a Variable in the Variables Editor

To configure the UI used to edit a fragment's input parameters in the Page Designer:

1. Open the fragment's Variables editor.
2. Select the variable or constant you want to customize.
3. Open the variable or constant's Design Time tab in the Properties pane.
4. Select properties to customize how the component for editing the variable will look in the Page Designer.

   The properties you see in the Design Time tab will depend upon the variable's type, and the Subtype property you select in the tab. For example, if Date is selected as the Subtype for a string-type variable, you'll see fields for setting the date's Minimum and Maximum limits:
   
   Description of the illustration fragment-variable-custompi.png
   

   Here are steps for some common customization options for string-, object-, and number-type variables and constants:

   Note:

   When working with string variables and constants, you have the option of adding translation metadata if you want a particular variable (or constant) to display the translation icon on the Page Designer's Properties pane to support translation.

   Customization Option	Steps in Design Time Tab	Result in Page Designer
   To display a color picker:	For a string-type variable or constant: In the Design Time tab, select the Subtype as Color. Optional: In the Placeholder field, specify a hint text for the variable; for example, Choose a color. Optional: Switch to the General tab and set these additional properties: In the Label field, enter a user-friendly name for the variable. In the Default Value property, use the color picker to set a default color.	Description of the illustration fragment-variable-custompropertiespane.png
   To display a date or date-and-time picker:	For a string-type variable or constant: In the Design Time tab, select the Subtype as Date or Date Time. Optional: In the Placeholder field, specify a hint text for the variable; for example, Select a date. Optional: In the Minimum field, set the bottom (inclusive) limit of a date or date-and-time range for the value in the Properties pane. Optional: In the Maximum field, set the top (inclusive) limit of a date or date-and-time range for the value in the Properties pane. Optional: Switch to the General tab, then in the Label field, enter a user-friendly name for the variable.	Description of the illustration fragment-variable-date.png
   To display an endpoint picker:	For an object-type variable or constant: In the Design Time tab, select the Subtype as Endpoint. Optional: To filter endpoints available in the endpoint picker by REST action type, for example, to only list Get One REST calls, select one or more of the predefined filters in Endpoint Action Hint. Optional: To filter endpoints available in the endpoint picker by service connection type, for example, to only list service connections using an ADF Describe, select one or more of the predefined filters in Service Type. Optional: Switch to the General tab, then in the Label field, enter a user-friendly name for the variable. Note: The Placeholder field does not take effect in the Properties pane when you use the Endpoint subtype.	Description of the illustration fragment-variable-endpoint.png Clicking Select launches a Configure Endpoint wizard in which fragment users can select a suitable endpoint and choose its URI parameters. Tip: If you cannot find the endpoint you want or prefer to manually set up your endpoint, click the Manual Setup of Endpoint icon () in the wizard, then select from the available endpoints and confgure its URI parameters.
   To display a drop-down menu containing an array of possible values:	For a string-type variable or constant: In the Design Time tab, select the Subtype as Enum Values. Optional: In the Placeholder field, specify a hint text for the variable; for example, Select the default browser. Click next to Enum Values, enter the Label, Value, and Description for your first value. For example, you might enter Chrome as the label, ch as the value, and Google Browser as the description. Click Create. If you want to make changes, click , update the values, and click Save. Click to delete a value. To reorder your list, drag the next to the value and drop it where you want it. Repeat step c to create your entire list of values. Optional: Switch to the General tab, then in the Label field, enter a user-friendly name for the variable.	Description of the illustration fragment-variable-enumvaluepng.png
   To display a time picker:	For a string-type variable or constant: In the Design Time tab, select the Subtype as Time. Optional: In the Placeholder field, specify a hint text for the variable; for example, Select a time. Optional: In the Minimum property, set the bottom (inclusive) limit of a time range for the value in the Properties pane. Optional: In the Maximum property, set the top (inclusive) limit of a time range for the value in the Properties pane. Optional: Switch to the General tab, then in the Label field, enter a user-friendly name for the variable.	Description of the illustration fragment-variable-time.png
   To display a drop-down menu with a list of time zones:	For a string-type variable or constant: In the Design Time tab, select the Subtype as Time Zone. Optional: In the Placeholder field, specify a hint text for the variable; for example, Select a time zone. Optional: Switch to the General tab, then in the Label field, enter a user-friendly name for the variable.	Description of the illustration fragment-variable-timezone.png
   To limit the input values to a number in a range:	For a number-type variable or constant: In the Design Time tab, specify a hint text for the variable, for example, Enter Quantity, in the Placeholder field. Optional: In the Minimum and Maximum properties, set the inclusive bottom and top limits of a range for the value in the Properties pane; for example, to limit the input value to a number in the range 0 - 99. Optional: Switch to the General tab, then in the Label field, enter a user-friendly name for the variable.	Description of the illustration fragment-variable-number.png

When you set properties in the Design Time tab, the metadata in the fragment's JSON is automatically updated. You can open the JSON editor to view the metadata. For example, here's what you might see for a variable that is customized to use the Date Picker component:

"variables": {
    "hireDate": {
      "type": "string",
      "input": "fromCaller",
   "@dt": {
        "label": "Date of Hire"
        "subtype": "date",
        "valueOptions": {
          "placeholder": "Select a date"
     }
   }   
},

Customize Fragment JSON with Metadata

While you can use a fragment variable's Design Time tab for some simple UI customization, you'll need to edit the JSON directly for advanced options. To do this:

1. Open the fragment's JSON editor.
2. Update the variable or constant's definition by setting the @dt element, then use the subtype property to specify the component you want displayed in the Page Designer. The JSON editor displays a hint to help you select the value for the subtype property:
   
   
   Description of the illustration fragment-variable-json.png
   
   
   For example, here's how you can show a component for selecting a business object by setting the subtype property to businessObject:

   "myObject": {
      "type": "string",
      "input": "fromCaller",   
      "@dt": {
            "subtype": "businessObject",
            "label": "Related Object"
       }
    },

   You can also use the label property to change the variable's display name in the Properties pane.

   The Properties pane in the Page Designer will now show a component for selecting a business object and the new display name for the variable wherever the fragment is used.
   
   Description of the illustration fragment-variable-bo.png
   

For more details about the JET components and properties, see JET metadata in Oracle JavaScript Extension Toolkit documentation.

Property Options for Variable Metadata

The following table describes the metadata properties that you can use in JSON to customize how fragment variables are displayed in the Properties pane:

Property	Type	Description
label	string	Use this property to specify a user-friendly name for the variable.
subtype	Available subtypes: businessObject color date date-time endpoint enum lov time timezone Note: The following subtypes are also available, but they are used to set the binding type, and do not affect how the variables are displayed in the Properties pane: dynamicContainer dynamicField dynamicField[] dynamicLayoutContext For details, see Set the Binding Type for Variables in Dynamic Components.	Use this property to create a more specific type of customizer for simple types. For example, you can choose date to use a date picker component for a string type: Description of the illustration constants-rich-picker.png Most simple customizations can be configured from the Design Time tab (see Customize a Variable in the Variables Editor).
valueOptions	object	The valueOptions available to you depend on the selected subtype. When no subtype is selected, the only valueOptions is placeholder. See the tables below for a list of valueOptions properties.

Property Options for Fragment Metadata

The valid subtype and valueOptions properties you can use depend on the variable's type. For example, the color subtype can only be applied to variables that are strings. This section describes the subtype and valueOptions properties that are valid for each type.

Subtypes and valueOptions for objects

When the variable type is object, the following table describes the subtype and valueOptions that can be used:

Subtype	valueOptions	Usage
dynamicContainer	section	The only valueOption for the dynamicContainer subtype is section: "@dt": { "subtype": "dynamicContainer", "valueOptions": { "section": { "preferredContent":["SpFoldoutPanelElement","SpFoldoutPanelSummarizingElement"] } } } You create the metadata for dynamic container sections in the parent container. Use preferredContent to list the interfaces that components in the root of the section templates must implement.
empty	fields	When no subtype is selected, you can use the fields valueOption to customize the display/editing of object values. Instead of displaying a simple single text area for the whole value, the Properties pane will display individual customizers for the various fields of the object. Note: This property is only supported for displaying the first level of object fields. You can specify an array of fields of the associated variable or constant that you want displayed in-line in the Properties pane when editing the object's values. You can customize how each field is displayed by using label, description, subtype, and valueOptions. When using the fields property, each field must have the ID of the object field it maps to. The order of fields in the array is the order they will be displayed in the Properties pane. You can use the following field properties: id (Required). A string to match the DT field definition to the ID of the object type. label (Optional). A string for the user displayable value for the field. description (Optional). A string to appear in the '?' help pop-up for the field. subtype (Optional). Use to further define the type of the field value. See the table above. valueOptions (Optional). Use these values to further customize the editing experience. A variable described with the following metadata: "variables": { "employee": { "type": "person", "input": "fromCaller", "defaultValue": { "active": false, "date-of-birth": "2001-01-01", "name": "Norman" } } } would look similar to this in the Properties pane when displayed with the default text area: Description of the illustration designer-constants-pi-object.png The fields property can be used to customize how the object is displayed: "variables": { "employee": { "type": "person", "input": "fromCaller", "defaultValue": { "active": false, "date-of-birth": "2001-01-01", "name": "Norman" }, "@dt": { "valueOptions": { "fields": [ { "id": "name", "description": "The first (given) name" "label": "First Name" }, { "id": "date-of-birth", "label": "Date of Birth" "subType": "date" }, { "id": "active", "description": "Is the employee active?" "label": "Active" } ] } } } } The customized object would look similar to this in the Properties pane: Description of the illustration designer-constants-pi-fields.png

Subtypes and valueOptions for arrays

When the variable type is array, the following table describes the subtype and valueOptions that can be used:

Subtype	valueOptions	Usage
enum	values placeholder	Use enum to display a drop-down menu showing all values for each item in the array. The only valueOptions property for the enum subtype is values. In addition to a value, each item in the array can have an optional label and description. "selectBrowser": { "type": "object[]", "input": "fromCaller", "@dt": { "subtype": "enum", "valueOptions": { "values": [ { "value": "ch", "label": "Chrome", "description": "Google browser" }, { "value": "fx", "label": "Firefox", "description": "Mozilla browser" }, { "value": "sf", "label": "Safari", "description": "iOS browser" } ], "placeholder": "Select the default browser" }, "label": "Choose a browser" } }, The Properties pane will show a drop-down menu that can have items with descriptions: Description of the illustration fragment-variable-enumvaluepng.png If you are using an array of primitives (say, string[])), you can use enum to display a drop-down menu showing all values for each item in the array: "selectBrowser": { "type": "string[]", "input": "fromCaller", "@dt": { "subtype": "enum", "valueOptions": { "values": [ { "value": "ch", "label": "Chrome", "description": "Google Browser" }, { "value": "fx", "label": "Firefox", "description": "Mozilla Browser" }, { "value": "sf", "label": "Safari", "description": "Apple Browser" } ], "placeholder": "Select the default browser" }, "label": "Choose a browser" } }, The Properties pane will show a drop-down menu with the three values for each item in the array: Description of the illustration fragment-variable-enumvalue-array.png
empty	placeholder	When no subtype is selected, the only valueOptions is placeholder.

Subtypes and valueOptions for booleans

When the variable type is boolean, there are no subtype or valueOptions. Variables with a boolean type are displayed as switch components in the Properties pane.

Subtypes and valueOptions for numbers

When the variable type is number, you can use the Design Time tab to configure the subtype and valueOptions. See Customize a Variable in the Variables Editor.

Subtypes and valueOptions for strings

When the variable type is string, you can use the Design Time tab to configure the subtype and valueOptions for simple customization options. See Customize a Variable in the Variables Editor.

The following table describes the subtype and valueOptions that can be used in JSON to configure advanced options for string-type variables:

Subtype	valueOptions	Usage
empty	placeholder translatable	Use the placeholder to specify a hint text for the variable. This can be used for all variables when there is no subtype. If a default value is supplied by the fragment variable, then that default value is used as the default placeholder. If both a placeholder value is used and the default value is specified, then the placeholder will be used. An example of values for the placeholder and translatable properties: } "placeholder": "Search", "translatable": true }
businessObject	placeholder	Use the businessObject subtype to display a business object picker in the Properties pane. "type": "string", "input": "fromCaller", "@dt": { "subtype": "businessObject", "label": "Related Object" } The Properties pane displays a component for selecting a business object: Description of the illustration fragment-variable-bo-cropped.png Note: The placeholder valueOption is not displayed in the Properties pane when you use the businessObject subtype.
lov	service placeholder	Use to create a drop-down of values retrieved from a service, such as a REST endpoint. The service endpoint must be already set up in VB Studio, and must be available to the application. You can then use @dt metadata to call the service and fetch items to populate the drop-down list. The service response must be in JSON format, and the response items in an array. In the example of the lov subtype below, the now constant will be offered a choice of values to pick from, which are determined by the response from a REST endpoint: "now": { "type": "string", "description": "wow", "defaultValue": "505642", "input": "none", "@dt": { "label": "Films Now Playing", "subtype": "lov", "service": { "request": { "endpoint": "my-app:Petstore/getNowPlaying", "uriParameters": { "api_key": "4174b7d9a7b4bf87342c98e2289c6ee6" } }, "response": { "itemsPath": "results", "mapping": { "value": "id", "label": "title", "description": "overview" } } } } } } Here's how the example above displays in the Properties pane: Description of the illustration constants-lov-picker.png For details about the lov metadata property values, see LOV Metadata Property Values.

LOV Metadata Property Values

You can assign the lov subtype to a variable if you want to display a drop-down list of values (LOV) for the variable in the Properties pane. To use the lov subtype, you'll need to set valueOptions property values to specify where the LOV data is retrieved from, and to configure how the drop-down list will look in the Properties pane:

Name	Description	Example
service	Type: Object Describes the service to retrieve the LOV data from, and how to use it.	See the lov subtype example above.
request	Type: Object Describes what service to call, and how to call it.	See the lov subtype example above.
request.endpoint	Type: string The fully-qualified name of a VB Studio service that you are able to access.	"my-app:Petstore/getNowPlaying"
request.pathParameters	Type: Object Maps endpoint path parameter names, and the values to replace them with. The values can also be VB Studio constants (see below).	"pathParameters": { "name": "honeybadger" "department": "accounts" }
request.uriParameters	Type: Object Maps URI path parameters to the values they should be replaced with. The values can also be VB Studio constants (see below).	"uriParameters": { "api_key": "4174b7d9a7b4bf87342c98e2289c6ee6" "session_name": "cabbage" }
response	Type: Object Describes how to unpack the payload returned by a successful response.	See the lov subtype example above.
response.itemsPath	Type: string A dot-separated path from the root of the response object to the array containing the LOV values.	results
response.mapping	Type: Object Describes how to populate the LOV from the response object. The mapping should indicate which response fields are to be used for the label, value, and description in the LOV.	See the lov subtype example above.
response.mapping.description	Type: string (optional) Describes the field from the response object that is used in the drop-down item description. It appears below label and value.	overview
response.mapping.label	Type: string (optional) Describes the field from the response object that is used as the primary display name of the item in the drop-down menu and in the input.	title
response.mapping.value	Type: string Describes the field from the response object that is used as the actual value of the variable/constant. It is visible to the right in the drop-down menu.	id

Using dependent parameters for lov metadata property values

The path and URI parameters might depend on other constants. For example, a REST service can use the result of an earlier selection as part of its own request. To do this, use expression notation in the parameter values to indicate which constant values to use:

"pathParameters": {
  "department": "[[ $constants.dept ]]"
}

The expression instructs this service request to use the current value of the "dept" constant as the value to use for the path parameter "department".

When writing the expression:

• Only simple direct references may be used. Calculated expressions such as "[[ $constants.dept + "_" ]]" will not work as expected.
• Only constants can be used. Variables cannot be used.
• The referenced constants must be accessible to the extension performing the LOV service call.