Variables in QPR UI
Context variables in QPR UI are for storing session time information and communicating between different user interface elements, such as views, panels and presentation objects.
Context Variable Behaviors
Variables can be defined for views, panels and presentation objects (called UI elements) which form a scope for the defined variables. Variables are visible and accessible in the scope where they have been defined and also in all sub scopes in the hierarchy of UI elements. For example, a variable defined in a view scope is visible in all panels and presentation objects in the view. Also a variable defined in a panel is visible in all presentation objects in the panel, but not in presentation objects in other panels. In addition to UI elements (view, panel and presentation object), variables can exist in session scope. The session scope is visible in all views, i.e. session variables are preserved when opening another view. Thus the visibility hierarchy for variables is (starting from the top):
- Session
- View
- Panel
- Presentation object
When setting or getting variable values and two variables with same names exist in different scopes, the variable in the lower scope takes priority over the variable in the upper scope, i.e. the lower scope variable hides the upper scope variable within the scope of the lower scope variable.
Each defined variable have a behavior which determine how the variables work when setting and getting their values. The following behaviors are available:
| Variable behavior | Description |
|---|---|
| Local | Local variables are visible in the scope where the variable is defined and also in all its sub scopes. When initialized, the local variable gets a value that is set in its definition (in the Context tab). When a local variable value is changed by logic in a presentation object (e.g. data grid action), the change is made to the variable in the nearest scope of the presentation object in the UI element hierarchy. |
| Optional | Optional variables work like the local variables, except the optional variables gets their initial values from the upper scope when the variables are initialized. For example, optional variables in view scope get their values from the session scope when a view is opened, and optional variables in the panel scope get their values from the view scope when the panel is initialized. If a variable having the same name doesn't exist in any of the upper scope, the optional variable will have the value that is set in its definition (in the Context tab). After the optional variable value is initialized, any changes in the upper scope variables don't affect the optional variable value. |
| Inherited | Unlike local and optional variables, inherited variables are not independent variables but they are just default values for non-existing variables. Thus, if a variable with the same name exist in the upper scope, the defined inherited variable doesn't have any effect. Only if no upper scope variable exist, the value defined for the inherited variable (in the Context tab) is used in the inherited variables' scope when referring to a variable with that name. Inherited variable values cannot be set by presentation objects, so when trying to set an inherited variable value, the value is set to the session scope variable. |
Note that variables in the session scope cannot be defined like the UI element variables, but session scope variables are created when they are set for the first time during a user session.
When presentation objects set variable values, either the nearest UI element scope variable or the session scope variable can be set. In a data grid actions the setting is called scope with alternatives local and global, and in HTML presentation object functions, it's done using a parameter named presentation object runtime id. When setting a UI element variable, always the nearest variable value in the hierarchy is set. For example, when setting a value from a data grid, the data grid presentation object is the nearest scope, the panel is the next and the view scope is after the panel. If there is no variable in any UI element scope defined, the value is set to the session scope.
When creating bookmarks, currently only the session scope variables are stored to the bookmark.
Context Variables Usage Example
There is a view with one panel, in which there is one presentation object. The Session context variable values are defined as follows:
800px
In the View Properties, the following context variable values are defined:
800px
In the Panel Properties, the following context variable values are defined:
800px
In the Presentation Object Properties, the following context variable values are defined:
800px
In the Effective View Context, these result into the values shown below. Note the Source column displaying the information where the effective context comes from:
800px
In the Effective Panel Context, these result into the values shown below. Note the Source column displaying the information where the effective context comes from:
800px
In the Effective Presentation Object Context, these result into the values shown below. Note the Source column displaying the information where the effective context comes from:
800px
To put it more concisely, the context variable values (and their behaviors) are as follows:
| Context Variable | Session | View | Panel | Presentation Object |
|---|---|---|---|---|
| AccountManager | John Smith | William Taylor (Local) | Susan Chapman (Inherited) | |
| Country | Sweden | Finland (Local) | China (Optional) | |
| ProductGroup | Umbrellas (Local) | |||
| CustomerGroup | Kids |
The effective context values are:
| Context Variable | Session | View | Panel | Presentation Object |
|---|---|---|---|---|
| AccountManager | John Smith | William Taylor | William Taylor | |
| Country | Sweden | Sweden | Finland | Finland |
| ProductGroup | Umbrellas | |||
| CustomerGroup | Kids | Kids | Kids |
Context Variables and Web Browser History
Any time the session context is modified (like when clicking a Pushbutton or modifying ProcessAnalyzer Presentation Object settings that cause session variables to be modified), a browser history entry is created. The preceding values in the session context can be restored via the browser's Back button. Left-clicking the Back button will restore the previous session context values, whereas right-clicking the Back button will show a list of session context changes to select from. Selecting an entry on the list will restore the session context from that entry.
Setting Context Variable Values in URL
It's possible to set context variable values in the URL of the QPR UI view. To do this, append "&<variable name>=<variable value>" to the end of the URL. For example: http://localhost:8080/ui/#/dashboard?sys:dashboard=24026&myvariable=myvalue
Defining View Properties and Variables
To define context variables, type in the name of the variable to the text field and click the check mark. After that, you can click the value field and type in the value for your context variable. Context variables starting with "sys:" are system variables which have special purpose in QPR UI - use them only for their intended purpose. The Behavior selection affects the context variable used explained in Context Variable Behaviors. To see what context variable values are used in the view, panel, or presentation object, select the Show effective context check box in the Context tab of the view, panel, or presentation object properties pages.
Variables Usage Example
There is a view with one panel, in which there is one presentation object. The Session variable values are defined as follows:
| Variable name | Value |
|---|---|
| AccountManager | John Smith |
| Country | Sweden |
In the View Properties, the following variable values are defined:
| Variable name | Value | Behavior |
|---|---|---|
| AccountManager | William Taylor | Stored variable |
| CustomerGroup | Kids | Local variable |
In the Panel Properties, the following variable values are defined:
| Variable name | Value | Behavior |
|---|---|---|
| AccountManager | Susan Chapman | Local variable |
| Country | Finland | Local variable |
In the Presentation Object Properties, the following variable values are defined:
| Variable name | Value | Behavior |
|---|---|---|
| ProductGroup | Umbrellas | Stored variable |
In the Effective View Context, these result into the values shown below. Note the Source column displaying the information where the effective context comes from:
| Variable name | Value | Source | Scope |
|---|---|---|---|
| AccountManager | William Taylor | Scope of the view | View |
| Country | Sweden | Inherited from session context | Session |
| CustomerGroup | Kids | Scope of the view | View |
In the Effective Panel Context, these result into the values shown below. Note the Source column displaying the information where the effective context comes from:
| Variable name | Value | Source | Scope |
|---|---|---|---|
| AccountManager | Susan Chapman | Initialized from the panel's context | Panel |
| Country | Finland | Initialized from the panel's context | Panel |
| CustomerGroup | Kids | Inherited from the effective context of the view | View |
In the Effective Presentation Object Context, these result into the values shown below. Note the Source column displaying the information where the effective context comes from:
| Variable name | Value | Source | Scope |
|---|---|---|---|
| AccountManager | Susan Chapman | Inherited from the effective context of the panel | Panel |
| Country | Finland | Inherited from the effective context of the panel | Panel |
| ProductGroup | Umbrellas | Scope of the presentation object | Presentation object |
| CustomerGroup | Kids | Inherited from the effective context of the view | View |
To put it more concisely, the context variable values (and their behaviors) are as follows:
| Context Variable | Session | View | Panel | Presentation Object |
|---|---|---|---|---|
| AccountManager | John Smith | William Taylor (Stored variable) | Susan Chapman (Local variable) | |
| Country | Sweden | Finland (Local variable) | ||
| ProductGroup | Umbrellas (Stored variable) | |||
| CustomerGroup | Kids (Local variable) |
The effective context values are:
| Context Variable | Session | View | Panel | Presentation Object |
|---|---|---|---|---|
| AccountManager | John Smith | William Taylor | Susan Chapman | Susan Chapman |
| Country | Sweden | Sweden | Finland | Finland |
| ProductGroup | Umbrellas | |||
| CustomerGroup | Kids | Kids | Kids |