1. Developing Applications with Oracle Visual Builder
  2. Get Started
  3. Anatomy of Visual Applications
  4. Understand Variables

Understand Variables

A variable is the basic building block for managing client state. It is of a specific type and exists in a specific scope.

Variables store intermediate state on the client between the Visual Builder user interface and REST services. Components are principally bound to these variables, and the behavior of the variables is governed by actions.

A variable's type can be a primitive, a structured type (which can consist of other types), a dynamic type, or a builtin type.

A scope defines the lifecycle of a variable, and the framework automatically creates and destroys the variables depending on the semantics of the scope. The following scopes are supported:

  • Page scope: State is accessible only within the context of the specified page. All state is initialized with default values when the page is entered, and destroyed when the page is exited.

  • Application scope: State is accessible in all parts of the application and in all pages.

  • Flow scope: State is accessible in all pages contained in the current flow.

  • Action chain scope: State is accessible in the current action chain.

The initial value of a variable is determined using the defaultValue property set on the variable, along with its type.

Constants are a type of variable of the Constants namespace and are used to store values that do not need to change over time such as company name or measurement conversion values. Constants are typed like other variables and are supported in the same scopes. But they differ from other variables in that you can't change their values after they are initialized. For more information, see Constants in the Oracle Visual Builder Page Model Reference.

A variable value that has not yet been instantiated is undefined. A variable is guaranteed to be instantiated and its initial value set just before the vbEnter event is raised (see The Lifecycle of a Page).

When its value changes, a variable emits an event. This event may trigger an action chain. You can define variables as input parameters, with their value determined by the inputs to the page or module. These inputs can be URL parameters for bookmarking, for example.

For more information, see Variables in the Oracle Visual Builder Page Model Reference.

Variables and Parameter Passing

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

The following table lists the available properties for variables.

Property Required? Description
type Yes A specific primitive type (string, boolean, number,and so on); a structured type such as an array or object, for which each field can either be a primitive or a structure; a dynamic type (any); or a built-in type, such as ServiceDataProvider or ArrayDataProvider (see Built-in Extended Types).
input No; applicable only if the property is within the page scope How the variable becomes part of the page contract for incoming navigation. The value is either none (the default), fromCaller (indicating that it will be passed internally), or fromURL (indicating that it will be passed via the URL).
required No Whether or not the variable must be set
defaultValue No The default value for the variable to be initialized. If no default value is provided, the value is "not set" or undefined. The defaultValue can be bound to an expression, or it can be a structure that uses expressions that reference other variables.
persisted No Use persisted variables to extend a variable's lifespan beyond its defined scope. For example, when you want to keep an authorization token for the duration of a session, set this property to make sure the token is available throughout the session, even if the page is refreshed. Can be set to:
  • device: Stores the variable in the browser's local storage and persists it on the device where the application is running, even if the browser is closed. If you want to store a variable across sessions, use this setting.
  • session: Stores the variable but only during the current browser session.
  • history: Stores the variable on the browser history. When navigating back to a page in the browser history using the browser back button, the value of the variable is restored to its value at the time the application navigated away from this page.
  • none: Variable is not stored (default).

Expressions

An expression may refer to other variables including constants, system properties, statics, and the like. For example:

$variables.total = $variables.sum * (1 + $variables.taxRate)

The Visual Builder user interface performs dependency analysis of the expressions to correctly order expression evaluation and detect cycles.

If the value of any variable referenced in an expression changes, the expression is immediately reevaluated.

An expression can be used in the default value of a variable or constant.

You can use the following implicit objects in expressions (all are prefixed by a dollar sign ($):
Name Where Available Description
$application Everywhere Application object
$page In the current page Current page instance
$flow In the current flow Current flow instance
$variables Every scope that has a variables property A shortcut for $most_specific_scope.variables in the current scope. In a page, $variables is a shortcut for $page.variables.
$chains Every scope that has a chains property A shortcut for $most_specific_scope.chains
$chain Actions executing in an action chain Chain in which the action is executing
$parameters In the beforeEnter event Input parameters for the page. This object is needed because page variables do not exist yet in the vbBeforeEnter event.
$listeners In a flow or page Event listeners of a flow or page
$event Event listeners and variable onValueChange listeners For an event listener on a component, $event contains the Event JavaScript object that the component passes to the listener. For an event listener on a custom event, $event contains the payload for that event. For an onValueChange listener on a variable,$event is a structure with the properties name, oldValue, value, and diff (itself a structure).
$initParams Everywhere 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 }}"
  }
}

Variables and Lifecycles

Application and page variables are constructed automatically in a specific application or page lifecycle stage.

Input parameters that are passed by means of navigation rules, or bookmarkable variables that are provided on the URL, are automatically assigned to their corresponding variables. When you modify the value of a bookmarkable variable, the URL is automatically adjusted to match that new value (that is, a new history state is pushed). In this way the page is always bookmarkable and does not require any specific user action in order to be bookmarked.

Variables and Events

A variable triggers an onValueChanged event when it is modified. This event is triggered only when the value is actually changed; setting a variable value to the same value does not trigger an event. The variable must be explicitly changed to send the event. For example, if a variable is a complex type, modifying an inner property does not fire this event; the entire variable must be set by means of an API call. In this case, the framework can add to the payload those parts of the structure that have changed. 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.

An onValueChanged event can trigger a user-defined action chain. The trigger has the payload of the former and new values of the variable.

For more information, see Understanding Actions and Action Chains.