The need to use the ApplyTemplate utility on a generated frame arises in the following situations:

In both these cases, however, it is desirable for the ApplyTemplate utility to make its changes without affecting any changes made to the frame by the user subsequent to its creation.

To solve the problem of applying template changes without affecting user changes, the ApplyTemplate utility assumes that the frame template assistant has been designed so that the generated frame is effectively partitioned into two areas:

After the ApplyTemplate utility is used on a frame generated from a frame template assistant, the area belonging to the user is not touched, but the area belonging to the frame template assistant is completely overwritten, and any changes made by a user to that area is lost.

A frame consists of three major parts: a form, a 4GL script, and a menu. For the purposes of the ApplyTemplate utility, each has a clearly defined boundary separating the user area from the frame template assistant area.

The boundary separating the two areas on the frame's form is defined by a high-level composite field that resides on the form of both the frame template and the frames that are created from it. Thus, on the form of frames created from the frame template, anything inside the high-level composite field belongs to the frame template assistant, and anything outside of it belongs to the user.

When designing a frame template for use with a frame template assistant and the ApplyTemplate utility, be sure that all form fields reside within the bounds of a high-level composite field.

A tag associated with this field is assigned to a specific macro variable defined for the frame template. The tag exists as a string value assigned to the ClientText attribute of the high-level composite field. The value of the string is equal to the value of the $_TopComposite macro variable defined for the frame template.

By evaluating the $_TopComposite macro variable for a frame template and the frame generated from it, the ApplyTemplate utility is able to identify which specific high-level composite field on the frame's form comprises the template-owned portion. By overwriting only this high-level composite, and no other, the ApplyTemplate utility can be guaranteed to not affect any user changes to the frame.

Because the high-level composite of the frame is overwritten by the corresponding high-level composite from the frame template, all of the fields generated by the frame template assistant when the frame was first created (or since the last time the ApplyTemplate utility was run) are overwritten or lost. The second function of the ApplyTemplate utility, therefore, is to regenerate the dynamic fields and queries created by the frame template assistant. This function, however, is not performed by the ApplyTemplate utility itself, but is instead performed entirely by the frame assistant, which is called from the ApplyTemplate utility.

The ApplyTemplate utility has a mode value, with the values of interactive or batch, which it passes to the frame template assistant when it is called. The ApplyTemplate utility itself does not behave differently when in these two modes.

The ApplyTemplate utility cannot itself guarantee that user customizations to a frame are not affected by sending it through its frame template assistant procedure again. The frame template assistant procedure must be designed in such a way so that it honors the $_TopComposite boundary.