Sfairadora

  • Reference Guide

Handlers

A handler is a function that is invoked whenever designated data is changed. Some other applications call the same feature a trigger. In contrast to the other subsections of the Definitions section, here you do not define an object that is later used elsewhere. Handlers perform their tasks as soon as they are created in this section. Handlers are usually intended to preserve data consistence – if particular data in the document is modified, some other data may require an update. However, in most situations you can achieve the same more easily by using a computed item.
A table is displayed for this subsection in the right pane of the document main window, where every row corresponds to one defined handler. The following values are specified for every handler:
Item
Description
Object name
Name of the object into which the handler should be inserted. In most cases it is either document for data in the current document or system for data in the system document.
Reference to data
Reference to a data item within the above specified object. You will need to understand the structure of the document data type in order to specify a reference to the required document data.
The reference can contain asterisks standing in for any name or index. This is especially useful when you need to assign the handler to table columns or to any element in a list.
Example: Suppose you have a people table in the Data section containing an age column. The object name should be set to document and the reference can be set to the following values with the respective meanings:
data
handler is invoked whenever any item in the Data section (not only in the people table) is modified.
data.people
handler is invoked whenever any modification in the people table occurs.
data.people.0
handler is invoked whenever any value of the first element of the people table is modified.
data.people.*.age
handler is invoked whenever the age of any person is modified
data.*.0.age
handler is invoked whenever the age element in the first row of any table in the Data section is modified.
data.*.*.age
handler is invoked whenever the age element in any row of any table in the Data section is modified.
Transitive
Significant only when the data reference refers to a table or sequence. If the transitive option is not selected, the handler is invoked only when a sequence element is added or removed. If the handler is defined as transitive, it is invoked also whenever the value of any element of the sequences is changed.
If the data reference does not refer to a sequence, this setting is insignificant.
Expression
Expression evaluated when the handler is invoked. The expression is entered through the function editor. The value of reason is passed as parameter:
DATA_ATTACHED (0)
handler is new – the first call of the handler enabling initialization if applicable.
DATA_CHANGED (1)
monitored data has been modified.
DATA_DETACHED (2)
handler will be removed – the last call of the handler enabling the termination of data monitoring.
You should use the symbolic names as specified here. Their actual values are enclosed in parentheses and serve only as information for debugging.
(The reason parameter is used here for compatibility with handlers in the data provider, where its use is more important.)