1. Developing Applications with Oracle Visual Builder in Oracle Integration 3
  2. Develop Applications
  3. Work with Variables and Types
  4. What are Variables and Types?

What are Variables and Types?

Variables are named pieces of information that hold business state and are bound (via expressions) to components on your application'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 application.

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 Visual Builder:
  • 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.

It's also possible to define an enumeration as a type, so you can refer to the enumerated list of values in a constant or variable. Enumerations are useful for constants and variables that have a small set of possible values and are usually used to declare different options (say, a list of cities) or actions (like up, down, left, and right).

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 application based on the scope it is defined in:
  • application: Variables defined at the application level are available anywhere in the application. They are useful for storing login names and other data that you want accessible both within and across an application'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 Retrieve the value of variables defined at the current application level. For example, if a variable called empName was defined at the application level, the $application.variables.empName expression is used to get its value. Current application
$flow 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 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 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 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 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 Refer to event listeners of an application, flow, or page in a component, for example, $listeners.onSelectionChange. In a flow or page
$event 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. See Start an Action Chain When a Variable Changes. Event listeners and variable onValueChange listeners
$initParams Declarative initialization parameters which can be used in expressions. Initialization parameters—or initParams—are evaluated early and can be used in expressions that are evaluated before variables exist (for example, in service declarations or translation bundle paths). The initParams are defined within a configuration block in app-flow.json, for example:
"configuration": {
  "initParams": {
    "myServicePath": "some/path/",
    "anotherPath": "http://somehost/foo"
  }
},
"services": {
  "myservice": "{{ $application.initParams.myServicePath + 'myservice.json' }}"
},
"requirejs": {
  "paths": {
    "myPrefix": "{{ $initParams.anotherPath }}"
  }
}
 Everywhere

These variable definitions can be used much the same as any other variable in Visual Builder, 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, Visual Builder 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

Visual Builder provides several built-in variables that allow you to access application metadata.

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

path
Use the path variable to build the path to a resource, such as an image located in a folder.
Name Description
$application.path Path needed to retrieve a resource located in the application folder.
$flow.path Path needed to retrieve a resource in the 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 (string).
$application.user.fullName Full name of the user (string).
$application.user.email User email (string).
$application.user.username User name (string).
$application.user.roles One or more user roles (array of strings)
$application.user.roles.roleName Returns true if roleName is a role of this user.
$application.user.permissions One or more user permissions (array of strings).
$application.user.permissions.permName Returns true if permName is a permission of this user.
$application.user.isAuthenticated Returns true if the user is authenticated.
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-flow.json.
$application.info.description Application description as defined in app-flow.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

See also Built-in Variables in the Oracle Visual Builder Page Model Reference.