Difference between revisions of "Variables in QPR UI"

From Mea Wiki
Jump to navigation Jump to search
 
(41 intermediate revisions by 3 users not shown)
Line 1: Line 1:
−
'''Context variables''' in QPR UI is a mechanism for storing session time information and communicating between different user interface elements, such as views, panels and presentation objects. For example, the context can define the starting point for querying data from QPR ProcessAnalyzer or QPR Suite Web Service, or it can be used to define the chart type and colors.
+
'''Variables''' in QPR UI are for storing session time information and communicating between different user interface elements, such as views, panels and presentation objects. Variables can only contain textual (string) values. If other types of values are provided, they are converted into strings.
  
 
__TOC__
 
__TOC__
  
−
== Context Variable Behaviors ==
+
== Variable Behaviors ==
−
Each UI element (i.e. view, panel, presentation object) has a set of '''effective values''' for context variables (effective context), which consist of the current values of all context variables visible at that level, i.e. it's a combination of all upper level context variable values and the values defined in the level itself. Context variables can be defined in the following levels: ''Session'', ''View'', ''Panel'' and ''Presentation Object''.
+
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
  
−
The context variables in QPR UI have the following types of ''behaviors'' which determine how the context variables work:
+
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.
−
* '''Local''': Defines a ''local'' variable, which is visible in the level where the variable is defined and also in all its sub levels. When initialized, the local context variable gets a value that is set in its definition (in the Context tab). Note that when setting a local variable value, the value is changed for the nearest local variable.
 
−
* '''Optional''': Works like the local variable, except the optional variable gets its initial value from the upper level. For example, optional variables in view level get their values from the session level, and optional variables in the panel level get their values from the view level. If the same name of context variable doesn't exist in the upper level during the initialization, the optional context variable will have the value that is set in its definition (in the Context tab). After the optional variable value is initialized, the changes in the upper level variables don't affect the optional variable value.
 
−
* '''Inherited''': The inherited variable gets its value from the upper level if the same name of variable exists in the upper level. If doesn't exist in the upper level, the context variable gets a value that is set in its definition. If the upper level value will be available after the initialization, the upper level value replaces the defined value.
 
  
−
Context variables in the session scope cannot be defined, but they start to exist when they are set for the first time. That's why they don't have a behavior setting.
+
Each defined variable have a '''behavior''' which determine how the variables work when setting and getting their values. The following behaviors are available:
  
−
When setting context variable values via actions (for example in a [[Data_Grid_Properties#Data_Grid_Click_and_Popup_Menu_Events|data grid]]) or in HTML presentation object, you can either set the local variable value or set a value to the session level (called '''Global'''). When setting the local value, always the nearest defined local or optional variable value is set. For example, when setting a value from a data grid, the data grid presentation object is the nearest one, the panel is the next and the view is after the panel. If there is no local or optional variable defined at all, the value is set to the session level.
 
−
 
−
== 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:<br>
 
−
[[File:ExampleSessionContext.png|800px]]
 
−
<br>
 
−
<br>
 
−
In the '''View Properties''', the following context variable values are defined:<br>
 
−
[[File:ExampleViewContext.png|800px]]
 
−
<br>
 
−
<br>
 
−
In the '''Panel Properties''', the following context variable values are defined:<br>
 
−
[[File:ExamplePanelContext.png|800px]]
 
−
<br>
 
−
<br>
 
−
In the '''Presentation Object Properties''', the following context variable values are defined:<br>
 
−
[[File:ExamplePOContext.png|800px]]
 
−
<br>
 
−
<br>
 
−
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:
 
−
[[File:ExampleViewEffectiveContext.png|800px]]
 
−
<br>
 
−
<br>
 
−
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:
 
−
[[File:ExamplePanelEffectiveContext.png|800px]]
 
−
<br>
 
−
<br>
 
−
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:
 
−
[[File:ExamplePOEffectiveContext.png|800px]]
 
−
<br>
 
−
<br>
 
−
To put it more concisely, the context variable values (and their behaviors) are as follows:
 
 
{| class="wikitable"
 
{| class="wikitable"
−
!Context Variable||Session||View||Panel||Presentation Object
+
!'''Variable&nbsp;behavior'''
 +
! '''Description'''
 
|-
 
|-
−
|AccountManager||John Smith||William Taylor (Local)||Susan Chapman (Inherited)||
+
||Local variable
 +
||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 where the variable has been defined as Local variable.
 
|-
 
|-
−
|Country||Sweden|| ||Finland (Local) ||China (Optional)
+
||Optional&nbsp;parameter
 +
||Optional parameters work like the local variables, except that the optional parameters get their initial values from the upper scope when the variables are initialized. For example, optional parameters in view scope get their values from the session scope when a view is opened, and optional parameters 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 parameter will have the value that is set in its definition (in the Context tab). After the optional parameter value is initialized, any changes in the upper scope variables don't affect the optional parameter value.
 
|-
 
|-
−
|ProductGroup|| || || ||Umbrellas (Local)
+
||Stored variable
 +
||Stored variables work like Local variables, except that when the view is saved, the current value of the Stored variable is saved to the view at the level where the Stored variable is defined.
 
|-
 
|-
−
|CustomerGroup|| ||Kids|| ||
+
||Default value
 +
||Unlike local variables and optional parameters, Default value variables are not independent variables but they are just default values for non-existing variables. Thus, if a variable with the same name exists in the upper scope, the defined default value variable doesn't have any effect. Only if no upper scope variable exists, the value defined for the default value variable (in the Context tab) is used in the default value variables' scope when referring to a variable with that name. Default value variable values cannot be set by presentation objects, so when trying to set an default value variable value, the value is set to the session scope variable.
 
|}
 
|}
  
−
The effective context values are:
+
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.
−
<br>
+
 
 +
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_Properties#Data_Grid_Click_and_Popup_Menu_Events|data grid actions]] the setting is called '''scope''' with alternatives ''local'' and ''global'', and in [[HTML_Properties#Setting_Variables_in_JavaScript|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.
 +
 
 +
== Setting Variable Values in URL ==
 +
It's possible to set variable values in the url pointing to QPR UI. To do this, for each variable add "'''&<variable name>=<variable value>'''" in the end of the URL. For example: <nowiki>http(s)://SERVERNAME/ui/#/dashboard?sys:dashboard=24026&myvariable1=myvalue1&myvariable2=myvalue2</nowiki>
 +
 
 +
Note that when using variables a url, variable values need to be url encoded (more information: https://www.w3schools.com/tags/ref_urlencode.asp).
 +
 
 +
== System Variables ==
 +
QPR UI has the '''system variables''' defined in the table below. System variables have a special functionality in the system. All system variables start with '''sys:''' prefix, and thus it's a good practice not to name other variables to start with that to avoid accidental use of system variables.
 +
 
 +
When using variables a url pointing to QPR UI, variable values need to be url encoded (more information: https://www.w3schools.com/tags/ref_urlencode.asp).
 +
 
 
{| class="wikitable"
 
{| class="wikitable"
−
!Context Variable||Session||View||Panel||Presentation Object
+
!'''Variable name'''
 +
! '''Description'''
 +
|-
 +
||sys:dashboard
 +
||Id of the currently open view. Another view can be opened by changing this variable value.
 +
|-
 +
||sys:dashboardIdentifier
 +
||Use this variable when you want to open another view using a '''path''' the target view. The path can be defined as:
 +
* '''Absolute path''' where the path starts from the folders hierarchy root. The absolute path always points to the view defined by the path. Example: ''/Folder/Sub folder/ViewIdentifier''.
 +
* '''Relative path''' where the path starts from the folder where the currently opened view is located. Relative paths can be used to link between views within a folder branch and the links remain, even if the branch is moved to other folder. Example: ''Folder/Sub folder/viewidentifier''.
 +
 
 +
Absolute paths always starts with the slash ('''/'''), whereas relative paths don't start with slash.
 +
 
 +
sys:dashboardIdentifier variable can only be used in the session context. Setting the sys:dashboardIdentifier variable value will automatically set the corresponding value to sys:dashboard variable. sys:dashboardIdentifier will be removed automatically after.
 +
|-
 +
||sys:hideViewHeader
 +
||Defines whether the top main toolbar in the view is hidden ('''true''') or visible ('''false''').
 +
|-
 +
||sys:mobileModeThreshold
 +
||The width in pixels to use as the breakpoint for mobile mode of locked QPR UI views. When a screen width is smaller than the threshold, the view is shown in mobile mode. In the mobile mode, panels are stacked vertically and each panel's height equals the screen height. Supported values are integers. Default value is 800 pixels, which is used if this variable isn't defined or an invalid value is defined. Defining "0" as the value will disable the mobile mode. Note that sys:mobileModeThreshold has only effect in the view's effective context.
 
|-
 
|-
−
|AccountManager||John Smith||William Taylor||William Taylor||  
+
||sys:password
 +
||Use this parameter to provide password to login automatically to QPR UI without going to the login screen. You also need to provide the sys:username parameter. sys:username and sys:password parameters are removed from the URL after the login, and thus they won't be stored as QPR UI variables. Note however, that the username and password can be stored in the browser history. See url examples in the description of the sys:username parameter.
 
|-
 
|-
−
|Country||Sweden||Sweden||Finland||Finland
+
||sys:sessionId
 +
||QPR UI user session id. Can be used to pass the session id to other QPR Suite product to use it in [[Common QPR Authentication|common QPR Authentication]]. The variable value is readonly. The session id is accepted by the '''xsession''' parameter in all QPR products.
 
|-
 
|-
−
|ProductGroup|| || || ||Umbrellas
+
||sys:settingsPanel
 +
||View level variable defining whether the right side settings page is open and which tab in the pane is active. sys:settingsPanel is defined as a JSON object with following properties:
 +
* isOpen: '''true''' (settings pane is open) or '''false''' (settings pane is closed)
 +
* activePage: '''model''' or '''settings'''
 +
 
 +
Example: '''{"isOpen":true,"activePage":"settings"}'''
 
|-
 
|-
−
|CustomerGroup|| ||Kids||Kids||Kids
+
||sys:username
 +
||Use this parameter to provide username to login automatically to QPR UI without visiting the login screen. To be able to authenticate, you also need to provide the ''sys:password'' parameter. sys:username and sys:password parameters are removed from the URL after the login, and so that they won't be stored as QPR UI variables. Note however, that the username and password can be stored in the browser history. sys:username and sys:password parameters only work when authenticating using QPR Suite or QPR ProcessAnalyzer; credentials for the federated authentication identity provider cannot be used here.
 +
 
 +
Example url's:
 +
* <nowiki>https://localhost:8080/ui/#/dashboard?sys:dashboard=24026&sys:username=qpr&sys:password=demo</nowiki>
 +
* <nowiki>http://localhost:8080/ui/#/login?sys:username=qpr&sys:password=demo</nowiki>
 +
 
 +
Note that for path <nowiki>http://localhost:8080/ui/#/home/</nowiki> the login with the sys:password parameter doesn't work.
 
|}
 
|}
  
 
== Context Variables and Web Browser History ==
 
== Context Variables and Web Browser History ==
−
Any time the '''session context''' is modified (like when clicking a [[Pushbutton_Properties|Pushbutton]] or modifying [[QPR_ProcessAnalyzer_Presentation_Object_(PAPO)#QPR_ProcessAnalyzer_Presentation_Object_.28PAPO.29|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.
+
Any time the '''session context''' is modified, a new 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.
 
<br>
 
<br>
 
[[File:BrowserHistory.png]]
 
[[File:BrowserHistory.png]]
−
 
−
== 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: <nowiki>http://localhost:8080/ui/#/dashboard?sys:dashboard=24026&myvariable=myvalue</nowiki>
 
  
 
{{MDBTutorialViewPropertiesAndContext}}
 
{{MDBTutorialViewPropertiesAndContext}}
Line 83: Line 101:
 
== See Also ==
 
== See Also ==
 
* [[Variable Tag in QPR UI]]
 
* [[Variable Tag in QPR UI]]
−
* [[QPR UI System Variables]]
 
  
 
[[Category: QPR UI]]
 
[[Category: QPR UI]]

Latest revision as of 10:29, 23 December 2019

Variables in QPR UI are for storing session time information and communicating between different user interface elements, such as views, panels and presentation objects. Variables can only contain textual (string) values. If other types of values are provided, they are converted into strings.

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 variable 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 where the variable has been defined as Local variable.
Optional parameter Optional parameters work like the local variables, except that the optional parameters get their initial values from the upper scope when the variables are initialized. For example, optional parameters in view scope get their values from the session scope when a view is opened, and optional parameters 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 parameter will have the value that is set in its definition (in the Context tab). After the optional parameter value is initialized, any changes in the upper scope variables don't affect the optional parameter value.
Stored variable Stored variables work like Local variables, except that when the view is saved, the current value of the Stored variable is saved to the view at the level where the Stored variable is defined.
Default value Unlike local variables and optional parameters, Default value variables are not independent variables but they are just default values for non-existing variables. Thus, if a variable with the same name exists in the upper scope, the defined default value variable doesn't have any effect. Only if no upper scope variable exists, the value defined for the default value variable (in the Context tab) is used in the default value variables' scope when referring to a variable with that name. Default value variable values cannot be set by presentation objects, so when trying to set an default value 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.

Setting Variable Values in URL

It's possible to set variable values in the url pointing to QPR UI. To do this, for each variable add "&<variable name>=<variable value>" in the end of the URL. For example: http(s)://SERVERNAME/ui/#/dashboard?sys:dashboard=24026&myvariable1=myvalue1&myvariable2=myvalue2

Note that when using variables a url, variable values need to be url encoded (more information: https://www.w3schools.com/tags/ref_urlencode.asp).

System Variables

QPR UI has the system variables defined in the table below. System variables have a special functionality in the system. All system variables start with sys: prefix, and thus it's a good practice not to name other variables to start with that to avoid accidental use of system variables.

When using variables a url pointing to QPR UI, variable values need to be url encoded (more information: https://www.w3schools.com/tags/ref_urlencode.asp).

Variable name Description
sys:dashboard Id of the currently open view. Another view can be opened by changing this variable value.
sys:dashboardIdentifier Use this variable when you want to open another view using a path the target view. The path can be defined as:
  • Absolute path where the path starts from the folders hierarchy root. The absolute path always points to the view defined by the path. Example: /Folder/Sub folder/ViewIdentifier.
  • Relative path where the path starts from the folder where the currently opened view is located. Relative paths can be used to link between views within a folder branch and the links remain, even if the branch is moved to other folder. Example: Folder/Sub folder/viewidentifier.

Absolute paths always starts with the slash (/), whereas relative paths don't start with slash.

sys:dashboardIdentifier variable can only be used in the session context. Setting the sys:dashboardIdentifier variable value will automatically set the corresponding value to sys:dashboard variable. sys:dashboardIdentifier will be removed automatically after.

sys:hideViewHeader Defines whether the top main toolbar in the view is hidden (true) or visible (false).
sys:mobileModeThreshold The width in pixels to use as the breakpoint for mobile mode of locked QPR UI views. When a screen width is smaller than the threshold, the view is shown in mobile mode. In the mobile mode, panels are stacked vertically and each panel's height equals the screen height. Supported values are integers. Default value is 800 pixels, which is used if this variable isn't defined or an invalid value is defined. Defining "0" as the value will disable the mobile mode. Note that sys:mobileModeThreshold has only effect in the view's effective context.
sys:password Use this parameter to provide password to login automatically to QPR UI without going to the login screen. You also need to provide the sys:username parameter. sys:username and sys:password parameters are removed from the URL after the login, and thus they won't be stored as QPR UI variables. Note however, that the username and password can be stored in the browser history. See url examples in the description of the sys:username parameter.
sys:sessionId QPR UI user session id. Can be used to pass the session id to other QPR Suite product to use it in common QPR Authentication. The variable value is readonly. The session id is accepted by the xsession parameter in all QPR products.
sys:settingsPanel View level variable defining whether the right side settings page is open and which tab in the pane is active. sys:settingsPanel is defined as a JSON object with following properties:
  • isOpen: true (settings pane is open) or false (settings pane is closed)
  • activePage: model or settings

Example: {"isOpen":true,"activePage":"settings"}

sys:username Use this parameter to provide username to login automatically to QPR UI without visiting the login screen. To be able to authenticate, you also need to provide the sys:password parameter. sys:username and sys:password parameters are removed from the URL after the login, and so that they won't be stored as QPR UI variables. Note however, that the username and password can be stored in the browser history. sys:username and sys:password parameters only work when authenticating using QPR Suite or QPR ProcessAnalyzer; credentials for the federated authentication identity provider cannot be used here.

Example url's:

  • https://localhost:8080/ui/#/dashboard?sys:dashboard=24026&sys:username=qpr&sys:password=demo
  • http://localhost:8080/ui/#/login?sys:username=qpr&sys:password=demo

Note that for path http://localhost:8080/ui/#/home/ the login with the sys:password parameter doesn't work.

Context Variables and Web Browser History

Any time the session context is modified, a new 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.
BrowserHistory.png

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

See Also

Retrieved from "https://wiki.onqpr.com/mea/index.php?title=Variables_in_QPR_UI&oldid=14950"