Introduction

EnableRules and VisibilityRules allow you to control the enabled state of toolbar buttons and the enabled and visible state of controls rendered in dynamic viewers declaratively – without writing event handler code. A rule is an ABL logical expression that references property and field values through tokens. The framework resolves the tokens to the current runtime values, evaluates the expression and applies the result to the button or control. The rules are re-evaluated automatically whenever one of the referenced values may have changed, e.g. when the user navigates to another record, edits a referenced field or when the viewer switches between display and update mode.

The feature is available in two places:

EnableRule for custom toolbar buttons – the enableRule attribute of a custom toolbar button definition (JSON) controls whether the button tool is enabled (SCL-4112)
EnableRules and VisibilityRules for viewer controls – repository attributes on the fields, buttons and group boxes of a dynamic viewer control whether the control is enabled (EnableRules) and/or visible (VisibilityRules) (SCL-4111)

Rule expression syntax

A rule is a logical ABL expression. Anything that is valid in an ABL logical expression can be used: the comparison operators (=, <>, >, <, >=, <=), the logical operators and, or, not, parentheses and ABL built-in functions. Property and field references are written as tokens in the form ${name}:

${OrderStatus} = "Ordered" and (${SmartTableIOState} = "FieldsEnabled" or ${SmartTableIOState} = "ModifyingData")

Before evaluation, each token is replaced by the current value, converted into an ABL literal:

Source value	Resulting literal

Source value	Resulting literal
CHARACTER / string values	Quoted, e.g. `"Ordered"`
LOGICAL / Boolean values	`yes` / `no`
Numeric values (INTEGER, INT64, DECIMAL, .NET numeric types)	Unquoted, invariant culture, e.g. `42` or `1.5`
Unknown value	`?`

The resolved expression is then evaluated into a logical result. When the result is true the button or control is enabled (EnableRule) or visible (VisibilityRule); any other result (false or the unknown value) disables or hides it.

Comparisons against a field that resolves to the unknown value follow the usual ABL semantics – design rules so that they behave sensibly when no record is available, for example by combining them with a state condition such as ${SmartDataSourceState} = "Navigatable".

EnableRule for custom toolbar buttons

Custom toolbar buttons are defined in the buttons JSON file of the application. The optional enableRule attribute of a button definition assigns the rule:

"order-sseh-test": {
    "buttonType":    "command",
    "buttonAction":  "server:Consultingwerk.SmartComponentsDemo.PresentationService.OrderPresentationService:HandleToolButtonClick",
    "dataSource":    "OrderPresentationServiceViewer",
    "buttonName":    "order-sseh-test",
    "buttonLabel":   "SSEH Test",
    "enableRule":    "${OrderCustomerDataSource.SmartDataSourceState} = \"Navigatable\"",
    "group":         "order"
}

Token resolution

Two token forms are supported for toolbar buttons:

Token form	Resolved against

Token form	Resolved against
`${forminstance.member}`	The named object instance of the dynamic form (e.g. a data source adapter, viewer or browser instance, referenced by its instance name)
`${member}`	The Toolbar link target of the toolbar (the viewer, browser or data source adapter the toolbar is linked to)

The member name is resolved depending on the type of the referenced instance:

Instance type	Supported properties	All other member names

Instance type	Supported properties	All other member names
SmartBusinessEntityAdapter, SmartDatasetAdapter, SmartDatasetChildAdapter	`Available`, `SmartDataSourceState`	Resolved as field values of the current record (optionally buffer-qualified, e.g. `${Adapter.eOrder.OrderStatus}`)
SmartViewerControl	`SmartTableIOState`, `AddingRecord`, `CopyingRecord`	Resolved from the editor control bound to the field – so the rule reacts to unsaved screen values – falling back to the data source of the viewer
SmartDataBrowser, SmartUpdatableBrowser	`SmartTableIOState`, `AddingRecord`, `CopyingRecord` (SmartUpdatableBrowser only)	Resolved from the active grid row, falling back to the data source of the browser

Change notification

The rule is initialized when the form is shown and re-evaluated automatically when one of the following events of the referenced instances fires:

Data source adapters: AfterQueryPositionChanged, CurrentChanged, BeginUpdateState, EndUpdateState
Viewers and updatable browsers: SmartTableIOStateChanged, AddingRecordChanged, CopyingRecordChanged
Editor controls bound to referenced viewer fields: TextChanged / CheckStateChanged
Updatable browsers: CellChange

EnableRules and VisibilityRules for viewer controls

For dynamic viewers rendered from the SmartFramework repository, every field, button and group box may carry the repository attributes EnableRules and VisibilityRules. The attributes are set on the object instances of the viewer (e.g. in the SmartFramework repository maintenance). When the viewer is rendered, the framework creates a rule for each non-empty attribute value:

EnableRules controls whether the control is enabled
VisibilityRules controls whether the control is visible

Both attributes can be combined on the same control. Example – a field that is only editable while the order is not yet shipped and the viewer is in update mode:

${OrderStatus} <> "Shipped" and (${SmartTableIOState} = "FieldsEnabled" or ${SmartTableIOState} = "ModifyingData")

Token resolution

Tokens of viewer control rules resolve against the viewer that contains the control, or – when qualified with an instance name – against any named object instance of the dynamic form hosting the viewer:

Token	Resolved as

Token	Resolved as
`${SmartTableIOState}`, `${AddingRecord}`, `${CopyingRecord}`	The corresponding property of the viewer containing the control
`${fieldname}`	The current value of the editor control bound to the field in the viewer – including unsaved screen values. When no bound control exists, the value is read from the data source (binding source) of the viewer using the `GetFieldValues` method of the adapter (buffer-qualified names such as `${eOrder.OrderStatus}` are supported)
`${forminstance.member}`	The named object instance of the dynamic form hosting the viewer – e.g. another viewer (`${anotherviewer.fieldname}`), a data source adapter (`${adapter.SmartDataSourceState}`) or a browser. Adapters, viewers and browsers resolve members as described in the toolbar button table above; properties of other instance types (e.g. other controls) are resolved through reflection (`${anothercontrol.propertyname}`)

How the result is applied

EnableRules – the result is applied through the SetControlEnabled method of the viewer using ControlEnabledEnum:Update (rule satisfied) or ControlEnabledEnum:Never (rule not satisfied). The enable mode is registered with the viewer, so it is retained across the EnableFields/DisableFields cycles of the viewer and cooperates with the standard field enabling (including EnabledForAdd / EnabledForUpdate attribute handling and read-only treatment of multi-line editors).
VisibilityRules – the result is assigned to the Visible property of the control.

Change notification

The rules are initialized during the OnLoad processing of the viewer, when all controls of the viewer and the object instances of the hosting form have been created. They are re-evaluated automatically when:

the viewer (or a referenced viewer/updatable browser instance) changes its table I/O state (SmartTableIOStateChanged) or starts/ends adding or copying a record (AddingRecordChanged, CopyingRecordChanged)
a referenced data source adapter repositions or changes its update state (AfterQueryPositionChanged, CurrentChanged, BeginUpdateState, EndUpdateState)
the user edits an editor control bound to a field referenced by the rule (TextChanged / CheckStateChanged / CheckedChanged) or a cell of a referenced updatable browser (CellChange)
a data source is linked to the viewer after loading (SmartDataSourceChanged)

Web rendering

The web rendering services for dynamic viewers pass the two repository attributes through to the web client as properties of the rendered control JSON – for all control types (fields, buttons, group boxes, ...) in both the responsive and the pixel-based (absolute) layout rendering:

Repository attribute	JSON property on the rendered control

Repository attribute	JSON property on the rendered control
`EnableRules`	`enableRules`
`VisibilityRules`	`visibilityRules`

The properties contain the unresolved rule expression. Evaluating the rules (token resolution against the client-side view model and state) is the responsibility of the web frontend.

Error handling and troubleshooting

A token of a viewer control rule that references a field for which neither an editor control nor a field of the data source can be resolved raises a ViewerControlRuleException (reporting the token name, the control name and the rule expression). The exception is logged, the rule is marked invalid and is not evaluated again.
When a rule expression cannot be evaluated (e.g. due to a syntax error), the rule is likewise marked invalid, the failure is logged once and the rule is not evaluated again. The button or control then simply keeps its current state.
When a rule references an unknown field of a referenced data source adapter, the token resolves to the unknown value and a message is logged.
Diagnostic messages are written using the custom log entry type ENABLERULES. Activate this custom log entry type in the client logging configuration to trace rule resolution and evaluation issues.

Rule expressions are evaluated using the Consultingwerk.Framework.ExpressionParser.AblExpressionEvaluator. The token names used in a rule can be inspected programmatically using Consultingwerk.Framework.ExpressionParser.RuleExpressionHelper:GetTokenNames.