Each item on a text form has a modified data tag, which is a status value that indicates whether the user is considered to have changed the form item when the form was last presented.
As described later, an item's modified data tag is distinct from the item's modified property, which is set in the program and which pre-sets the value of the modified data tag.
The user sets the modified data tag by typing a character in the item or by deleting a character. The modified data tag stays set, even if the user, before submitting the form, returns the field content to the value that was presented.
When a form is re-displayed due to an error, the form is still processing the same converse statement. As a result, any fields that were modified on the converse have the modified data tag set to yes when the form is re-displayed. For example, if data is entered into a field that has a validator function, the function can invoke the ConverseLib.validationFailed function to set an error message and cause the form to re-display. In this case, when an action key is pressed, the validator function will execute again because the field's modified data tag is still set to yes.
The set statements affect the value of the modified property, not the current setting of the modified data tag. A test of the type if item modified is based on the modified data tag value that was in effect when the form data was last returned to your program. If you try to test the modified data tag for an item before your logic presents the form for the first time, an error occurs at run time.
The form as a whole is considered to be modified if the modified data tag is set to yes for any of the variable form items. If you test the modified status of a form that was not yet presented to the user, the test result is FALSE.
The following logic shows the result of various tests:
// tests false because a converse statement // was not run for the form if (form01 is modified) ; end // causes a runtime error because a converse // statement was not run for the form if (item01 is modified) ; end // assume that the user modifies both items converse form01; // tests true if (item01 is modified) ; end // tests true if (item02 is modified) ; end // sets the modified property to no // at the next converse statement for the form set item01 initialAttributes; // sets the modified property to yes // at the next converse statement for the form set item02 initialAttributes; // tests true // (the previous set statement takes effect only // at the next converse statement for the form if (item01 is modified) ; end // assume that the user does not modify either item converse form01; // tests false because the program set the modified // data tag to no, and the user entered no data if (item01 is modified) ; end // tests true because the program set the modified // data tag to yes if (item02 is modified) ; end // assume that the user does not modify either item converse form01; // tests false if (item01 is modified) ; end // tests false because the presentation was not // the first, and the program did not reset the // item properties to their initial values if (item02 is modified) ; end