What are Variables?

Variables are named pieces of information that hold business state and are bound (via expressions) to components on your App UI's pages. A variable, when bound to a component, can provide data values retrieved from a REST endpoint and display them to your users. It can also hold other state that is required by the component.

If users were to enter or change the component's value, the change is also written to the variable. How the variable behaves in this case is largely governed by actions, which may call underlying REST endpoints to apply the change. Components, variables, and actions together form the basic building blocks of an App UI.

So what do you define as a variable? Any piece of information really. It can be a simple variable, for example, a number-type variable to hold an employee's ID or a string-type variable for a name. It can also be a complex data structure, for example, an Employee structure with lastName, firstName, phoneNumber, address, and email elements. Here are the different types of variables available in VB Studio:

Primitive variables such as String, Number, Boolean, even a wildcard-type Any.
Structured variables such as Object or Array, used to store data structures.
Built-in variables used to get metadata, for example, to access the current page's ID and title or to access information about the current user.

Complex variables that define the type and structure of a variable's data are known as types. Every variable is assigned a type, either built-in or custom. A developer can create a type that, for instance, matches the REST payload and pass data using a variable assigned that type.

A variable's value can vary, as the name suggests. So if want to store values that don't change over time, such as your company name or "foot-to-meter" conversion rates, use constants. Constants are typed like other variables, but unlike variables, you can't change their values after they've been initialized—except when the constant's default value is an expression that refers to other variables; in this case, the constant's value changes when the other variable's value changes.

Variables, constants, and types are all defined within a scope and are automatically created and destroyed when the framework enters and exits a particular scope. They can be used in different places in your App UI based on the scope it is defined in:

App UI: Variables defined at the App UI level are available anywhere in the App UI. They are useful for storing login names and other data that you want accessible both within and across an App UI's flows and pages.
Flow: Variables defined at the flow level can be used within the flow and pages within that flow.
Page: Variables defined at the page level can only be used within that page.
Fragment: Variables defined at the fragment level can only be used within that fragment. Additionally a fragment, though referenced by an outer page, cannot reference variables defined in the page.
Layout: Variables defined at the layout level can only be used within that layout container.
Action chain: Variables defined at the action chain level can only be used within that action chain.

Variables as Input Parameters

You can use a variable to pass a parameter between pages by marking it as input. When you mark a page variable as an input parameter, you specify how it becomes part of the contract to navigate to that page. You can further mark it as required, implying that it must be set in order to navigate to that page.

Parameters can also be passed on the URL of the pages or flows that you're invoking. This approach makes it possible to bookmark pages that show specific data based on the parameter.

Default Value and Expressions

The initial value of a variable is determined by its default value. If a default value isn't provided, the value is "not set" or undefined and its initial value is determined based on its type. If provided, the default value can be a static value or an expression, which in turn can refer to other variables including constants, system properties, static values, and the like via implicit objects (such as $variables and $page, used to extract the value of a variable).

When defining the default value as an expression, the variable updates when any reference in the expression changes value. For example, a fullName variable might have the default value set as {{ $variables.firstName + ' ' + $variables.lastName }}. Any time firstName or lastName is updated, the fullName variable will be updated.

Here's a list of implicit objects you can use in expressions:

Name	Description	Where Available
`$application`	Used to retrieve the value of variables defined at the current App UI level. For example, if a variable called `empName` was defined at the App UI level, the `$application.variables.empName` expression is used to get its value.	Current App UI
`$global`	Used to retrieve the value of variables defined at the Unified Application level (for use by every App UI in your Oracle Cloud Application instance).	Across App UIs
`$flow`	Used to retrieve the value of variables defined at the current flow level. If `empName` was defined at the flow level, the `$flow.variables.empName` expression is used to get its value.	Current flow
`$page`	Used to retrieve the value of variables defined at the current page level. If you defined `empName` at the current page level, the `$page.variables.empName` expression is used to get its value.	Current page
`$variables`	A shortcut to retrieve the value of variables defined in the current scope. For example, if `empName` was defined at the current page level, `$variables.empName` can be used the same way you'd use `$page.variables.empName`.	Every scope that has a `variables` property
`$fragment`	Used to retrieve the value of variables defined within a fragment. If you defined `empName` at the fragment level, the `$fragment.variables.empName` expression is used to get its value, particularly in action chains. You can also use `$variables.empName` to get the value local to the fragment. Note: Every fragment has a unique ID, which is accessible within a fragment using `$fragment.info.id`. You can use `$fragment.info.id` used within expressions set on a component's ID property, or even the ID of a nested fragment.	Current fragment
`$layout`	Used to retrieve the value of variables defined in the current layout level. If you defined `empName` at the layout level, the `$layout.variables.empName` expression is used to get its value.	Current layout
`$chain`	Used to refer to variables in actions executing in an action chain.	The chain in which an action is executing
`$parameters`	Used to refer to a page's input parameters only in the `beforeEnter` event, because page variables do not exist until the `vbEnter` event.	In the `beforeEnter` event
`$listeners`	Used to refer to event listeners of an App UI, flow, or page in a component, for example, `$listeners.onSelectionChange`.	In a flow or page
`$event`	Used to retrieve the content of an event's payload in an event listener. For an event listener on a custom event, `$event` contains the payload for that event. For a event listener that listens for a variable's `onValueChanged` event, `$event` is a structure with the properties `name`, `oldValue`, `value`, and `diff`.	Event listeners and variable `onValueChange` listeners
`$initParams`	Used to refer to initialization parameters defined at the Unified Application level.	Everywhere
`$modules`	A shortcut to call methods exposed by an imported global functions module in the current extension. To access global functions in action chains, use the `<artifact-scope>.modules.<module-id>.<function-name>(...)` syntax, for example, `$page.modules.commonUtils.titleCase()` or `$page.modules.dateLocalUtils.dateToIsoString()`, where `titleCase` and `dateToIsoString` are names of functions defined in the `functions.json` file for that extension. Any container that imports modules can expect `$modules` to be available, for example, `$page.modules`, `$fragment.modules`, and so on.	Advanced expression builder for Business Rules, Validation Rules, and Default Values, and JavaScript action chains

These variable definitions can be used much the same as any other variable in VB Studio, meaning, you can use them in component attributes, as parameters for JS functions, in actions (such as if), and so on.

Variable Events

When its value changes, a variable emits an onValueChanged event. (You can also add an onValueChanged event to constants if its default value is an expression containing a variable.) For example, if you changed the name property of an Employee and then reset the Employee, the framework would send an event that the Employee changed, and as part of the payload indicate that the name has changed.

You can get the old and new variable values using the $event implicit object.

$event.oldValue provides the variable’s old value.
$event.value provides the variable’s new value.
$event.diff can be used for complex types and provides the diff between the old and new values.

Note that the onValueChanged event is triggered only when the value is actually changed; setting a variable value to the same value does not trigger this event.

It's possible to trigger an action chain whenever a variable raises this event. For example, when a user clicks a row on a employee's table, you can set up an action chain to retrieve employee information whenever the employee's ID changes.

Data Binding

Variables are principally bound to components to display data, but these variables don't know where the data is derived from or what it is used for. To populate a variable from a REST call, you assemble an action chain using an action making that REST call and an action assigning the result to that variable. For common cases, VB Studio provides quick starts to automate the creation of that variable to match the payload of the REST call, enabling you to quickly bind the REST call's payload in your pages. Typically, the variable's type matches the structure of the REST payload, though you have the option of defining your own type that matches your use case more closely, and then mapping the REST payload to a variable that uses that type.

Built-in Variables

VB Studio provides several built-in variables that allow you to access application metadata.

currentAppUi

Use the currentAppUi variable on the global object to access some of the current App UI's metadata. The global object represents the Unified Application, available to every App UI in your Oracle Cloud Application instance.

Name	Description
`$global.currentAppUi.id`	ID of the App UI (string).
`$global.currentAppUi.urlId`	ID of the App UI as shown in the URL (string).
`$global.currentAppUi.displayName`	Display name for the App UI (string).
`$global.currentAppUi.description`	Description of the App UI (string).
`$global.currentAppUi.defaultPage`	Default page of the App UI, if it exists (string).
`$global.currentAppUi.defaultFlow`	Default flow of the App UI, if it exists (string).
`$global.currentAppUi.applicationStripe`	Stripe used by the App UI (string).
`$global.currentAppUi.pillarTheme`	Pillar used by the App UI (string).
`$global.currentAppUi.pillarThemeMode`	Pillar theme mode used by the App UI (string).
`$global.currentAppUi.icon`	Icon used by the Ask Oracle Navigator menu for the App UI (string).
`$global.currentAppUi.usage`	Reserved for internal use.
`$global.currentAppUi.menuDisplayName`	Name of the App UI as displayed in the Ask Oracle Navigator menu (string).
`$global.currentAppUi.extensible`	Whether the App UI can be extended (Boolean).

currentPage

Use the currentPage variable on the application object to access some of the current page's metadata, such as ID and title. This variable automatically updates as the current page changes during navigation and can be used to update a navigation component with the currently selected page.

Name	Description
`$application.currentPage.id`	Path of the current page. The path describes the location of the page in the flow hierarchy.
`$application.currentPage.path`	Path of the current page for the App UI. The path describes the location of the page in the flow hierarchy.
`$application.currentPage.title`	Title of the current page.
`$flow.currentPage`	ID of the current page for this flow.

currentFlow

If there is a routerFlow in the page, use the $page.currentFlow variable to retrieve the ID of the current flow.

info

Use the info variable to retrieve some information about the application and page descriptor.

Name	Description
`$application.info.id`	Application ID as defined in `app.json`.
`$application.info.description`	Application description as defined in `app.json`.
`$flow.info.id`	Flow ID as defined in `flow-id-flow.json`.
`$flow.info.description`	Flow description as defined in `flow-id-flow.json`.
`$page.info.title`	Page title as defined in `page-id-page.json`.
`$page.info.description`	Page description as defined in `page-id-page.json`.

path

Use the path variable to build the path to a resource, such as an image located in a folder.

Name	Description
`$extension.path`	Path to retrieve a resource located in the extension-level `resources` folder, which can be used by all App UIs in the extension.
`$application.path`	Path to retrieve a resource located in a particular App UI's `resources` folder.
`$flow.path`	Path to retrieve a resource in a particular App UI's flow folder.

user

Use the user variable to access information about the current user, based on the information returned by the security provider.

Name	Description
`$application.user.userId`	User ID, if it exists (string).
`$application.user.fullName`	Display name of the user (string).
`$application.user.roles`	List of user roles (array of strings).
`$application.user.permissions`	List of user permissions (array of strings).
`$application.user.isAuthenticated`	Whether user is authenticated (boolean).
`$application.user.guId`	User GUID (string).
`$application.user.userName`	Name of the logged-in user (string).