Modified data tag and modified property

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.

Interacting with the user

In most cases, the modified data tag is pre-set to no when the program presents the form to the user; then, if the user changes the data in the form item, the modified data tag is set to yes, and your program logic can do as follows:

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 sysLib.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.

Setting the modified property

You may want your program to do a task regardless of whether the user modified a particular field; for example:

  • You may want to force the validation of a password field even if the user did not enter data into that field

  • You may specify a validation function for a critical field (even for a protected field) so that the program always does a particular cross-field validation, which means that your program logic validates a group of fields and considers how one field's value affects the validity of another.

To handle the previous cases, you can set the modified property for a particular item either in your program logic or in the form declaration:

  • In the logic that precedes the form presentation, include a statement of the type set item modified. The result is that when the form is presented, the modified data tag for the item is pre-set to yes.

  • In the form declaration, set the modified property of the item to yes. In this case, the following rules apply:

    • When the form is presented for the first time, the modified data tag for the item is pre-set to yes.

    • If any of the following situations occurs before the form is presented, the modified data tag is pre-set to yes when the form is presented:

      • The code runs a statement of the type set item initial, which reassigns the original content and property values for the item; or

      • The code runs a statement of the type set item initialAttributes, which reassigns the original property values (but not content) for each item on the form; or

      • The code runs a statement of the type set form initial, which reassigns the original content and property values for each item on the form; or

      • The code runs a statement of the type set form initialAttributes, which reassigns the original property values (but not content) for each item on the form

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.

If you need to detect whether the user (rather than the program) modified an item, make sure that the value of the modified data tag for the item is pre-set to no:

  • If the modified property of the item is set to no in the form declaration, do not use a statement of the type set item modified. In the absence of that statement, the modified property is automatically set to no prior to each form presentation.

  • If the modified property of the item is set to yes in the form declaration, use a statement of the type set item normal in the logic that precedes form presentation. That statement sets the modified property to no and (as a secondary result) presents the item as unprotected, with normal intensity.

Testing whether the form is modified

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.

Examples

Assume the following settings in the form form01:

  • The modified property for the field item01 is set to no

  • The modified property for the field item02 is set to yes

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 run-time 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