Programming Guide : 15. Writing a Template Assistant : How You Can Ensure Compatibility Between the Assistant and ApplyTemplate : How You Can Use ApplyTemplate on a Frame
 
Share this page                  
How You Can Use ApplyTemplate on a Frame
The need to use the ApplyTemplate utility on a generated frame arises in the following situations:
When the static functionality provided by a frame template has changed, and the user wants to fold these changes into a frame that has already been generated
When the user wants to change the portion of a generated frame created by a specific frame template assistant by running the assistant again
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.
How You Can Partition the Frame
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:
That which belongs to and has been modified by the user
That which belongs to and has been modified by the frame template assistant that generated the frame
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.
High-level Composite Field
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.
Batch Mode Compared to Interactive Mode
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.
Note:  A frame template does not need to have changed for the ApplyTemplate utility to be run. The ability to regenerate fields and queries can also be used to reconfigure a frame to accommodate changes since the frame was first generated—for example, either in the database tables or in the application requirements.
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.