Multiple Dimensions Support
| This document is referring to a past Scout release. Please click here for the recent version. |
Several components support multidimensional properties.
A multidimensional property is a property that will be computed based on its dimensions.
For example the enabled property of a Widget is multidimensional.
This means, the widget will only be enabled if all dimensions are set to true.
This gives developers the flexibility to e.g. use a dimension for authorization (granted) and one for the business logic and to be sure that if the widget was disabled using widget.setEnabledGranted(false) that it won’t accidentally get enabled when using widget.setEnabled(true).
Scout JS
As long as only one dimension is used, multidimensional properties behave like normal properties.
Let’s have a look at the visible property of the Widget.
The property can be set using widget.setVisible(false).
This will set the default dimension and computes the new value for widget.visible.
Because we didn’t set any other dimension, widget.visible will return false.
It will also trigger a propertyChange event for the visible property with the computed value.
Compared to regular properties, it also triggers a propertyChange event for the dimension visible-default.
We can now set another dimension, for example the pre-defined visible-granted dimension by using widget.setVisibleGranted(true).
We could also set any custom dimension as follows:
widget.setPropertyDimension('visible', 'example', true);Calling this method will recompute the widget.visible state.
But since the default dimension is still set to false, the widget.visible state won’t change.
Because every dimension needs to be true, we have to call widget.setVisible(true) (or widget.setPropertyDimension('visible', 'default', true)) to make the property widget.visible true again.
Default Value
Every multidimensional property has a default value.
This value is used if a dimension is not set.
And it is used for the computation to compute the value.
This means, if the default value is true, every dimension needs to be true to make the computation return true.
If the default value is false, every dimension needs to be false to make the computation return false.
The defaultValue false may be used to add dimensions to the property FormField.mandatory, which is false by default compared to Widget.enabled, which is true by default.
To mark a property as multidimensional with the defaultValue true, use the following code in your widget:
this._addMultiDimensionalProperty('visible', true);Alias
A property dimension can have an alias that is used to simulate a regular property.
For example if an alias is registered for enabled with the name accepted, it is possible to call setProperty('accepted', true) resp. getProperty('accepted'). It looks like a regular property and also triggers a propertyChange event for the name accepted, but actually it is a dimension, so it will influence the computation of the enabled property.
To add an alias for a dimension, use the following code in your widget:
this._addPropertyDimensionAlias('enabled', 'accepted');Sometimes an alias does not reflect the state of the multidimensional property.
For example if the alias is called locked, the widget should be enabled if locked is true instead of false.
In that case, you can set the alias to inverted as follows:
this._addPropertyDimensionAlias('enabled', 'locked', {inverted: true});Scout Classic
A total of 8 dimensions are available for a certain widget type and property. This means you e.g. have a total of 8 dimensions for Form Field visibility in your application. And 8 dimensions for enabled-states of Actions. So the dimensions are not consumed by widget instance but by widget type. This means you have to be careful in defining new dimensions as all widgets of the same type share these dimensions.
| Some of these dimensions are already used internally. Refer to the implementation and JavaDoc of the component for details about how many dimensions are available for custom use. |
menu.setEnabled(false); (1)
menu.setEnabledGranted(false); (2)
menu.setVisible(false, IDimensions.VISIBLE_CUSTOM); (3)
formField.setVisible(true, false, true, "MyCustomDimension"); (4)
formField2.setVisible(true, true, true); (5)
formField3.isEnabled(IDimensions.ENABLED_CUSTOM); (6)
formField3.isEnabled(IDimensions.ENABLED); (7)
formField3.isEnabled(); (8)
formField3.isEnabledIncludingParents(); (9)| 1 | Disables the menu using the internal default dimension |
| 2 | Disables the menu using the internal granted dimension |
| 3 | Hides the menu with a third custom dimension |
| 4 | Form Fields also support the propagation of new values to children and parents. This sets the custom dimension of this field and all of its children to true. |
| 5 | This sets the internal default enabled dimension of this field and all of its parents and children to true. |
| 6 | Checks if the custom dimension is set to true |
| 7 | Checks if the internal default dimension is set to true |
| 8 | Checks if all dimensions of formField2 are true |
| 9 | Checks if all dimensions of formField2 and all dimensions of all parent Form Fields are enabled. |
| In the example above the instance 'formField3' uses 4 dimensions for the enabled attribute: ENABLED_CUSTOM because it is explicitly used and the 3 dimensions that are used internally (ENABLED, ENABLED_GRANTED, ENABLED_SLAVE). Even though the instance 'formField2' makes no use of the custom dimension it is consumed for this instance as well because the dimensions do not exist by instance but by attribute (as explained above). |