Preferred Property

Description

AbstractEntity has a hint preferred property, which can be set by calling setPreferredProperty(propertyName) (refs #985). This hint is used to focus and select contents of "preferred" property editor based on some business logic.

How it can be defined?

Regardless of the number of different choices, it is always best to follow the model.

New instances

There are several ways to define a preferred property at the time of entity instantiation. The first two ways that comes to mind, are to either use companion's method new_ or a context-dependent logic of an entity master producer. Another way is to use an ACE handler (aka definer) for some property(es). The first two approaches are a natural choice if properties can remain unassigned and no definers would get executed.

All interactive changes from Web UI to an entity instance should trigger either clearing of the preferred property (setPreferredProperty(null)) or changing its value. This should be done in definers for specific properties, which is dictated by the business logic.

Note that even if the property has been returned to its original value by setting that value in the Web UI, the definer will still get invoked (i.e. the property is considered "touched"). In that case, it is necessary for the definer to have the same logic of choosing a preferred property as implemented in the companion's new_ / producer / definer for handling of initial values.

Retrieved instances

For retrieved instances, the most convenient way is to set a preferred property in property definers (isInitialising case).

As an alternative, method provideDefaultValuesForStandardEdit could be a convenient place (if used in the standard Edit action; or other producer methods if it is in a context of compound master).