«OnExitSet()» permits the template author to specify that, when a control on the interview (the trigger) loses focus, the value of another or the same data element (the target, caption, footing or heading can be set. If the data element does not exist before the interview is run, then it is created at the point that the OnExitSet executes.
- The full syntax of the command is, by way of example:
«OnExitSet(IDNumber,Gender,Value,(Substring(IDNumber,7,1) > '4'),'Male','Female',OnlyWhenEmpty)»
- When the focus leaves the IDNumber control on the interview, then the Gender data element (2nd parameter) will have its value set (3rd parameter – it could also be Caption, Footing or Heading, the functioning of which is self-explanatory).
- The value will be set to either ‘Male’ or ‘Female’ (5th and 6th parameters) depending on whether the Condition in parameter 4 is true or false (for information, the rule of the 7th character of the ID Number being between 5 and 9 indicating ‘Male’ applies to the South African ID Number).
- The last parameter can be either OnlyWhenEmpty or EvenWhenNotEmpty, so that in this example, the Gender will be set to ‘Male’ or ‘Female’ depending on the values of the 7th character of the IDNumber, but only if the Gender data element is empty when the IDNumber field loses focus. That gives the user the chance to change the Gender and even if the user then Tabs through the IDNumber field again, this will not reset the value of Gender.
«OnExitSet(PartyType,RefNumber,Caption,(PartyType = 'Individual'),'ID Number','Company Number')»
This example demonstrates how the value of a caption (in this case the caption on the control for data element RefNumber) can be changed depending on the value of another (or the same) data element (in this case the value of data element PartyType).
Note that when changing a caption, the initial caption on the control must be made wide enough to contain any of the values to which it might be set during the execution of OnExitSet commands. The initial caption can be padded on the right with spaces (or on the left if the AlignCaptions(Right) command is in effect) by the template author in order to make it long enough.
Note that this feature is available only in Version 4 and later of XpressDox.
Note further that with effect from version 4.3 of XpressDox, this feature works slightly differently with checkboxes, radio button lists, ChooseFromDataSource, and drop down lists with fixed values (i.e. not those created for ChooseFromSamples): in these cases the setting of the value/caption/heading/footing occurs not when the control loses focus, but when the user chooses a value from the control. This seems to be more intuitive in these instances.
Version 5 of XpressDox introduced the OnEnterSet command. As its name implies, its functionality is identical to that of OnExitSet, except for the timing. The actions performed by OnEnterSet are initiated when the focus enters the control for the trigger data element.