Make Variables and Types Available to Extensions

If you want a variable, constant, or type that you've defined in your App UI to be available to App UIs in another extension, you can mark them accessible to extensions. This way, your artifacts become available to App UIs in another extension when someone adds your App UI as a dependency.

Note:

Marking your variable or constant accessible to extensions means letting other extension developers change its value. Before doing this, carefully consider the consequences of allowing others to overwrite your values.

To mark your variable or constant available to App UIs in another extension, go to the Variables editor and select the variable or the constant.
- In the variable's Properties pane, select Read Only to allow other App UIs to read the variable's value; select Read/Write to allow other App UIs to read and modify the variable's value.
- In the constant's Properties pane, select Read/Override to allow other App UIs to read or override the constant.
Variables that are accessible to extensions have a check mark () against them in the Extension Read and/or Extension Write columns under Variables in the Variables editor. Constants have a check mark in the Extension Read/Override column under Constants.

Description of the illustration variable-available-extn.png

When you expose a variable or constant to extensions, make sure you enter a description so developers who extend its functionality know what it's meant for.
To make your type available to App UIs in another extension, go to the Types editor and select the type, then in its Properties pane, select Read/Override.

Types that are accessible to extensions have a check mark () against them in the Extension Read column on the Types editor, indicating that they can be read by other App UIs.

Description of the illustration type-available-extn.png

Note:

After you've made a variable or constant accessible to extensions, you should avoid renaming its ID. Renaming an ID might break the extensions that use it.

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:

Open the Variables editor.
Select the variable or constant you want to customize.
Select the Design Time tab in the Properties pane.
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 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: 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 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:

Open the JSON editor.
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 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 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 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", "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 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 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.

Organize How Constants Are Listed in the Properties Pane

To help users who will be extending pages, you can customize how constants and components are organized and displayed in the Page Designer's Properties pane.

Typically, when extending a page in the Page Designer, the Properties pane contains two tabs—the Constants tab and the Components tab—where the page's extendable items are listed. Extendable items, which includes constants, dynamic components, and extendable items in embedded fragments, are listed under the appropriate tab. To provide a better design experience for users extending the page, you can organize how items are listed in the Properties pane by organizing items into folders, and by setting the order that they are listed.

You can also choose to hide any items you don't want listed in the Properties pane (they'll still be listed in the Variables and Rule Sets editors). This is particularly helpful when there are many extendable components and constants. If you decide not to organize any of the items, the items are listed in the Constants and Components tabs.

Here's an example of the Properties pane for a page with an extendable dynamic form and constants. The Properties pane is optimized so that the constants that are typically configured are visible directly in the pane. The page constants for configuring the header, which are used less frequently, are grouped under the Header section to be less distracting:

Description of page-customized-pi.png follows

Description of the illustration page-customized-pi.png

To customize how items are displayed in the Properties pane:

Open the page's Design Time editor.
The page's extendable items are listed alphabetically in the Components pane. Use the General pane to organize how items are grouped and listed in the Properties pane. By default, the items in the General pane are listed in the order they appear in the page, but you can change the order.
In the General pane, change the order items and sections are listed by grabbing the handle to the left of the item and moving it into the position you want:

Description of the illustration page-designtime-itemhandle.png
Create a section and add items to it:
1. Click + Section, enter a section label in the pop-up (for example, Header), and click Create.
2. Optionally, in the newly created section's Properties pane, change the default icon to more easily identify the section: click the Default Icon, select an icon from the Icon Gallery, and click Select.
  You can also associate the section with a page component. When the user selects the component in the Page Designer, the Properties pane displays the items in the associated section.
  To associate a component with a section:
  1. Open the Page Designer and select the component on the page.
  2. In the Properties pane, select the section in the Design Time Section dropdown list:
    
    Description of the illustration page-customize-selectdesignsection.png
3. Now drag the items you want to add to the section and drop them onto the section header (for example, drag the Title constant and drop it onto the Header section).
Description of the illustration page-designtime-pi.png

To remove an item from a section, right-click the item and select Remove from Section, or deselect the item in the Components palette.

To delete a section, right-click the section and click Delete Section.
Under General, select each item to edit its properties in the Properties pane.

Modify the Label and Description properties to customize the label and descrption the user will see in the Properties pane when configuring the page.

Now when the user configures the page in an extension, they'll see the items in the Properties pane displayed in the order you want them to appear, and grouped how you would like.

You can also customize how fields for editing constants are rendered in the Properties pane. See Configure How Variables are Customized in the Properties Pane.