Describe difference between ValueChangeListener and datasource ItemPropertyChangeListener

[alexbudarov]

Description of the bug or enhancement

I often meet defects in CUBA code which are related to Component ValueChangeListener misusage. Newbie developers like to listen for Component value changes when they should listen to datasource changes.

We should somehow describe difference between listening to Component value changes and listening to Datasource item property changes.

• Component ValueChangeEvent event gets fired every time when component's value changes. Not only when it was changed by user.
• Datasource ItemPropertyChangeEvent gets fired when either user or java code has modified property of item which belongs to datasource.

You can ask - what's the difference? The difference is when datasources's item gets changed. For example any screen with "Save without close" button has this situation. After commit of dsContext main datasource receives new item, with possibly changed properties (by entity listener, trigger etc.).

• Datasource will NOT fire any ItemPropertyChangeEvent after item replacement
• Component will fire ValueChangeEvent if new item has another value of bound property.

So if developer reacts on Component ValueChangeListener like it was user's change and changes other data on the screen after the event - this screen will have various cosmetic problems like "Do you want to discard unsaved changes?" without any reason.

Conclusion is: if component is bound to datasource - then using datasource listeners is always preferred to using component listener. Because datasource listeners give finer control over screen lifecycle.

[knstvk]

👍

[ZuperKeurZ]

I would expect this to be documented in the developer manual as well? I spend quite some time searching for the differences between those listeners without succes, only to find this ticket.

In fact, it would be a good idea to have a specific page in the documentation on listeners (including entitylistener, transactionlistener) and describe where they apply.

This javadoc change is too minimal, i don't expect many people to spot this.

[knstvk]

One more significant difference in new API: component's ValueChangeEvent is sent when the editor screen opens with data, container's ItemPropertyChangeEvent is not, which is usually makes more sense.