Configure How Variables are Customized in the Properties Pane

You can customize variables and constants when developing an App UI, so that users extending the page have a more intuitive experience when configuring values in the Page Designer's Properties pane.

When a page is open in the Page Designer, the page's extendable variables and constants are listed in the Constants tab in the Properties pane. Users extending the page can set the values of those variables and constants, usually displayed as text fields in the Page Designer's Properties pane. For example, here's how a constant used to store a date displays by default in the Properties pane:
Description of constant-text-picker.png follows
Description of the illustration constant-text-picker.png

In some cases, a different UI component can make editing the variable or constant more intuitive. In the case of the constant that stores a date, displaying a date picker instead of a text field can improve the experience when a user edits its value in the Page Designer:
Description of constants-rich-picker.png follows
Description of the illustration constants-rich-picker.png

To customize the UI component displayed for a variable or constant in the Properties pane, you use the Design Time tab in the Variables editor. You can also edit the 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 the Customizing the JSON section below for a full list of customization options.

Customize Variables and Constants in the Variables Editor

To customize the UI component displayed in the Page Designer:
  1. Open the Variables editor.
  2. Select the variable or constant you want to customize.
  3. Select the 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, you'll see fields for setting Minimum and Maximum limits for the date:
    Description of constant-designtime-tab.png follows
    Description of the illustration constant-designtime-tab.png

Here are steps for some common customization options for string-, object-, and number-type variables and constants:
Customization Option Steps in Design Time Tab Result in Page Designer
To display a color picker:
For a string-type variable or constant:

  1. In the Design Time tab, select the Subtype as Color.

  2. Optional: In the Placeholder field, specify a hint text for the variable; for example, Choose a color.

  3. 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 fragment-variable-custompropertiespane.png follows
Description of the illustration fragment-variable-custompropertiespane.png
To display a date or date-and-time picker:
For a string-type variable or constant:

  1. In the Design Time tab, select the Subtype as Date or Date Time.

  2. Optional: In the Placeholder field, specify a hint text for the variable; for example, Select a date.

  3. 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.

  4. 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.

  5. Optional: Switch to the General tab, then in the Label field, enter a user-friendly name for the variable.


Description of fragment-variable-date.png follows
Description of the illustration fragment-variable-date.png
To display an endpoint picker:
For an object-type variable or constant:

  1. In the Design Time tab, select the Subtype as Endpoint.

  2. 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.

  3. 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.

  4. 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 fragment-variable-endpoint.png follows
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 (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:

  1. In the Design Time tab, select the Subtype as Enum Values.

  2. Optional: In the Placeholder field, specify a hint text for the variable; for example, Select the default browser.

  3. Click Add icon 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 Edit icon, update the values, and click Save. Click Delete iconto delete a value.

    To reorder your list, drag the Reorder icon next to the value and drop it where you want it.

  4. Repeat step c to create your entire list of values.

  5. Optional: Switch to the General tab, then in the Label field, enter a user-friendly name for the variable.

Description of fragment-variable-enumvaluepng.png follows
Description of the illustration fragment-variable-enumvaluepng.png
To display a time picker:
For a string-type variable or constant:

  1. In the Design Time tab, select the Subtype as Time.

  2. Optional: In the Placeholder field, specify a hint text for the variable; for example, Select a time.

  3. Optional: In the Minimum property, set the bottom (inclusive) limit of a time range for the value in the Properties pane.

  4. Optional: In the Maximum property, set the top (inclusive) limit of a time range for the value in the Properties pane.

  5. Optional: Switch to the General tab, then in the Label field, enter a user-friendly name for the variable.


Description of fragment-variable-time.png follows
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:

  1. In the Design Time tab, select the Subtype as Time Zone.

  2. Optional: In the Placeholder field, specify a hint text for the variable; for example, Select a time zone.

  3. Optional: Switch to the General tab, then in the Label field, enter a user-friendly name for the variable.


Description of fragment-variable-timezone.png follows
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:

  1. In the Design Time tab, specify a hint text for the variable, for example, Enter Quantity, in the Placeholder field.

  2. 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.

  3. Optional: Switch to the General tab, then in the Label field, enter a user-friendly name for the variable.


Description of fragment-variable-number.png follows
Description of the illustration fragment-variable-number.png
When you set properties in the Design Time tab, the metadata in the JSON file is automatically updated. You can open the JSON editor to view the metadata. For example, here's what you might see for a constant that is customized to use a date picker:
"constants": {
    "hireDate": {
      "type": "string",
   "@dt": {
        "subtype": "date",
        "label": "Date of Hire",
        "valueOptions": {
          "placeholder": "Select a date"
        }
      }   
   }
},

Customize the JSON with Metadata

While you can use a constant's Design Time tab for some customization options, you'll need to edit the JSON directly for advanced options. To do this:
  1. Open the 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.
For example, here's how you can show a component for selecting a business object by setting the subtype property to businessObject:
"constants": {
   "relatedObject": {
      "type": "string",
      "@dt": {
         "subtype": "businessObject",
         "label": "Related Object"
       },       
       "description": "Description of related object"
   }   
},

Use the label property to change the constant's display name in the Properties pane.

Property Options for Variable Metadata

The following table describes the metadata properties that can be used to customize how 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"

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 constants-rich-picker.png follows
Description of the illustration constants-rich-picker.png
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.

Properties for valueOptions

Depending on the subtype you select for the variable, you can use the following properties to further customize the components used for editing fields in the Page Designer.

Property Description Usage
fields

Use this 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.

Property type: array

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.

Note:

This property is only supported for displaying the first level of object fields.
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:
Description of designer-constants-pi-object.png follows
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 employeed active?",
                "label": "Active"
              }
            ]
          }
        }
      }
    }

The customized object would look similar to this in the Properties pane:
Description of designer-constants-pi-fields.png follows
Description of the illustration designer-constants-pi-fields.png
maximum Use this property to specify the inclusive top limit of a range when specifying a value in the Properties pane.

Property type: number | string

This property is suitable for numbers and date/time formats.

An example of values for the maximum property:
{
    "maximum": "10",
    "minimum": "0"
}

For further details about the JET 'maximum' metadata property, see JET component metadata properties in the Oracle JET JavaScript Extension Toolkit documentation.

minimum Use this property to specify the inclusive bottom limit of a range when specifying a value in the Properties pane.

Property type: number | string

This property is suitable for numbers and date/time formats.

An example of values for the minimum property:
{
    "maximum": "10",
    "minimum": "0"
}

For further details about the JET 'minimum' metadata property, see JET component metadata properties in the Oracle JET JavaScript Extension Toolkit documentation.

placeholder Use this property to specify a user-friendly hint text.

Property type: string

This property can be used in Properties pane customizers that have placeholder support, for example, JET Input type customizers.

An example of configuring a value for the placeholder property:
}
   "placeholder": "Search"
}

If a default value is supplied by the constant, 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.
service Use this property to fetch possible values from a service for an List of Values (LOV) picker.

Property type: object

When using the lov subtype to display a drop-down list of values, you use service to retrieve the values from a service, such as a REST endpoint. The service endpoint must already be set up in VB Studio, and must be available to the App UI. 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 lov subtype example 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",
      "valueOptions": {
        "service": {
          "request": {
            "endpoint": "my-app-ui:Petstore/getNowPlaying",
            "uriParameters": {
              "api_key": "4174b7d9a7b4bf87342c98e2289c6ee6"
            }
          },
          "response": {
            "itemsPath": "results",
            "mapping": {
              "value": "id",
              "label": "title",
              "description": "overview"
            }
          }
        }
      }
    }
  },

The example above displayed in the Properties pane:
Description of constants-lov-picker.png follows
Description of the illustration constants-lov-picker.png

See the LOV Metadata Property Values table below for details about the property values.
translatable Use this to specify if translation helpers should be present for the property.

Property type: boolean

Translation is only available for string types.

An example of configuring a value for the translatable property:
}
   "translatable": true
}
values Use this property to specify an array of possible values for the field.

Property type: object

This property can be used with the enum subtype.

Values must include value, and can optionally include label and description.

An example of using the values property:
"subtype": "enum",
"valueOptions": {
  "values": [
    {
    "value": "ch",
    "label": "Chrome",
    "description": "Google Browser"
  },{
     "value": "fx",
     "label": "Firefox",
     "description": "Mozilla Browser"
  },{
     "id": "sf",
     "label": "Safari",
     "description": "Apple Browser"
  }]
}

The example above displays in the Properties pane as shown here:Description of fragment-variable-enumvaluepng.png follows
Description of the illustration fragment-variable-enumvaluepng.png

For further details about the JET 'enumValues' metadata property, see JET component metadata properties in the Oracle JET JavaScript Extension Toolkit documentation.

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

This describes the service to retrieve the LOV data from, and how to use it.

 See service example above.
request

Type: object

This describes what service to call, and how to call it.

 See service example above.
request.endpoint

Type: string

This is the fully-qualified name of a VB Studio service that you are able to access.

"my-app-ui:Petstore/getNowPlaying"
request.pathParameters

Type: Object

This 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

This 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

This describes how to unpack the payload returned by a successful response.

 See service example above.
response.itemsPath

Type: string

This is a dot-separated path from the root of the response object to the array containing the LOV values.

 "results"
response.mapping

Type: object

This 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 service example above.
response.mapping.description

Type: string (optional)

This describes the field from the response object that is used in the drop-down item description. It appears below the label and value.

"overview"
response.mapping.label

Type: string (optional)

This 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

This 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.