The Property Expression and Evaluation Modes in this article apply to Settings vs 1.52
You can set up when a Gizmo expression will be run and how it will work. This article will help you become familiar with Expression and Property Evaluation Modes. Expression and Evaluation Modes give you a great deal of flexibility but can be confusing. If you are unsure, we recommend sticking with the defaults that orgvue suggests.
Expression Mode
The expression mode determines when a Gizmo expression will be run for a Property Cell. Note: A Cell is an individual Property value of a Node. If you think of a Property as a column, and a Node as a row, then the Cell carries the value.
| Expression Mode | Behaviour |
| Empty Cells | If the cell has no value, populate the data with the value returned from the expression. |
| New Nodes | When a new node is created, populate the cell with the value returned by the expression. The expression will only run on the creation of a node and otherwise triggered via On Demand. |
| All Nodes | Evaluate the expression for all nodes, and do not persist the value unless run as On Demand. Fixed expression properties cannot be edited. |
Settings 1.52 Example
Select how you want your expression to populate the property values
Property Evaluation Modes
The evaluation mode determines How an expression will work. Note: Pre-Filter and Post-Filter is referring to the Filters in Workspace on data that is being viewed and analyzed.
| Settings Evaluation Mode | Pack Property Evaluation Mode | Behaviour |
| None | N/A | This will not run as an expression and just return the value as a literal. |
| Pre-Filter | Pre-Filter |
The expression will run before data is filtered and not after. |
| Post-Filter | Post-Filter | The expression will run after the data is filtered and not before. A property which is set to evaluate Post-filter cannot itself be used within a filter since it has a dependency on the filter. |
| On Demand | On Demand | The expression will only run when triggered manually. The return value of the expression is persisted. |
Example for Pre/Post Filter
The expression:
node.rollUp("sum", "currentSalary")
will calculate the total salary of the data when run Pre-Filter, but only for the filtered nodes when run Post-Filter.
The expression:
node.allRollup("sum", "currentSalary")
will calculate the total salary of the entire dataset, regardless of whether it is run Pre-filter or Post-Filter.
The expression:
node.rollUp("sum", "currentSalary")/node.allRollup("sum", "currentSalary")
will calculate the ratio of the total salary for the filtered nodes vs all the nodes.
If your organisation’s total salary is £5m with the R&D team’s salary £1m of this.
If you filter to the R&D team then:
- Pre-filter
node.rollUp("sum", "currentSalary") = £5m - Post-filter
node.rollUp("sum", "currentSalary") = £1m - Pre-filter
node.allRollup("sum", "currentSalary") = £5m - Post-filter
node.allRollup("sum", "currentSalary") = £5m
Relationship
| Empty Cells (only when cell empty) |
New Nodes (only on create) |
All Nodes (always) |
|
| None | Literal value | Literal value, persisted | Literal value |
| Pre-Filter | Evaluated value, Pre-Filter | Evaluated Value, Pre-Filter, persisted | Evaluated Value, Pre-Filter |
| Post-Filter | Evaluated value, Post-Filter | Evaluated value, Post-Filter, persisted | Evaluated Value, Post-Filter |
| On Demand | Evaluated value, Post-Filter, persisted Applied only to empty cells |
Evaluated value, Post-Filter, persisted Applied to all cells |
Evaluated value, Post-Filter, persisted Applied to all cells |
UI Descriptions
Literal value: The expression will be printed and not run
Evaluated value: The expression will be run to generate a value
Persisted: The output will be saved to the properties values after the expression is run
Pre-filter: Calculated before the data is filtered
Post-filter: Calculated after the data is filtered
Applied only to empty cells: Will only be applied to property values that are not already populated
Applied to all cells: Will be applied to all property values regardless of whether they are already populated or not
|
Empty Cells |
New Nodes (only on create) |
All Nodes (always) |
|
| None | The value will be interpreted as a literal, printed to populate the property's cell if that cell does not otherwise carry a value. The default value is not persisted on save. | The value will be interpreted as a literal, populating the property's cell if no other value was presented at creation time. The value is persisted on save. | The expression will be printed to populate the property's cells, regardless of whether the cell carries a persisted value or not. |
| Pre-Filter | The expression will be run before the data is filtered or a visualisation and this will populate the property's cells. | The expression will be run on node creation, independently of filtering, and the return value will populate the property's cell; the output will be saved after you run the expression in the dataset. | The expression will be run before the data is filtered or a visualisation and this will populate the property's cells. |
| Post-Filter | The expression will be run after the data is filtered for a visualisation and this will populate the property's cells. | NA (evaluation of Initial value is always pre-filter) | The expression will be run after the data is filtered for a visualisation and this will populate the property's cells. |
| On Demand | The expression will be run after the data is filtered for a visualisation and this will populate the property's cells. The values will be saved to the dataset after the expression is run. Will only populate blank values in the property. |
NA (evaluation of Initial value is always pre-filter) | The expression will be run after the data is filtered for a visualisation and this will populate the property's cells. The values will be saved to the dataset after the expression is run. Will be applied to all property values regardless of whether they are already populated or not. |
Initial Value Mode
An initial value may be a literal or an expression. The rules defining the behaviour of a literal vs an expression differ and are explained below.
An initial value logic should be executed on node creation via the UI new node dialog, on node cloning, on paste merge or via Gizmo (all within Workspace only).
Exactly when in the node creation process should the initial value be executed?
This question is critical to:
1. The expression having in scope the values necessary for expression execution.
2. The expression execution being secure.
The steps are:
- The node is seeded with values (onBeforeCreate), the source of which are:
a. values entered via the new node form
b. values provided through paste-merge in Workspace
c. values provided through inheritance on node cloning
d. values provided through Gizmo API for node creation (a future requirement) - If a property which has an initial value is found to be empty, then the initial value logic is executed.
a. If the initial value has an evaluation mode of none, then this is injected as a literal
b. Else, the expression is executed with the ‘node’ object in scope
i. having been populated with values from 1 and
ii. having been inserted in the tree, such that the node has a parent, depth etc.
1. Questions:
a. buckets not updated?
b. levels not updated?
c. label not created?
c. The expression must only be evaluated if it is exactly the expression as held as the initial value expression in property metadata. It must not be evaluated if populated via user entry, via the paste-merge data, via inheritance during cloning or via the Gizmo api, but treated as a literal only. - What must be resolved is the order of execution and state in scope when cloning a full branch of nodes. Bottom up, and the node parent is not yet created, Top down, and the node children are not yet created.
Comments
0 comments
Please sign in to leave a comment.