Understanding the DataChange event in Container Components 

Introduction

In this article, we will discuss what the DataChange event is and how to leverage it in your container components. The DataChange event is one of several events that can be leveraged to execute actions for a given landmark within your component. The DataChange event is used to react to property changes and to field changes within the context of the container.

There are some constraints that should be pointed out when utilizing the DataChange event type. The behavior for publishand receiveactions is a little bit different than it is for custom actions. Since the DataChange event is invoked via a property change OR a field change, any publish actions which are listed under the event will only be executed if the event was invoked via a field change. For property changes, it does not make sense to invoke the publish action since the component will simply be re-publishing the same property but replacing the value with the contents of the fieldassociated with the action. This behavior would create some ambiguity with regards to how the DataChange event should behave when a publish action is used. If you wish to publish a property when a DataChange event occurs, the publish will only be executed if the field that is associated with the publish action changes. The property will then be published with the value of that field. The figure below shows a data change event created for a browser component. There is a single property named searchProperty along with a field, name:q (the search input field for Google.com) associated with the action. This publish action will only be executed if the data change is a field change event. If the searchProperty property were changed by some other component and the data change event was triggered via this property change from the property broker, the publish action would NOT execute.

Behavior for publish action within data change

Figure 1

If you wish to receive a property value when a DataChange event occurs, the receive will only be executed if the property that is associated with the receive action changes. It does not make sense to execute the receive action when the field changes because it will simply overwrite the field with the value of the property.

Behavior for receive action within data change

Figure 2

Any custom actions that are implemented will always execute when associated with data change events. It depends on the implementation of the action on whether or not it will work with field change events, property change events or both. Starting with Expeditor 6.2.2 and Lotus Notes 8.5.2, custom action code can call a method to get the value for the event that the action needs in order to execute (if it requires a property or field value). This method allows for the action to not have to know anything about whether or not the event was a field change or property change DataChange event type. The value returned will be the field value if it was a field change event or a property value if it was a property change event.

Sample custom action showing getParameterValue method on the event class

This action calls the new getParameterValue() method on the LandmarkEvent object in order to get the proper input value. This is used if your action supports both field change AND property change dataChange event types. There is also a method on the LandmarkEvent object called isFieldChange() which can be used to determine if the event is a field change data change event type.