Template Sizing Within Tables

[Context: HL Kit … Basic Concepts and Terminology … Manipulation of Visual Elements … Working With Tables]

Overview

Templates are normally sized either by the layout that contains them or by the template itself. When templates are used within tables, the logic remains the same, but there are additional implications involved.

Triggering of Position Script

The Position script of the template is invoked separately for each individual item being displayed. It is also invoked once when the table sizing process is first initiated. During this initial invocation is when the dimensions of the template are actually used by the containing table. No other positioning logic within the script is applied.

During the initial sizing, you can use the "issizing" target reference to detect that state. When initial sizing is being performed, the template need only calculate its height and can bail out without doing anything else. Since any other script logic is going to be thrown away during the sizing operation, there is no need to perform it.

You will see a check of the "issizing" target reference in most table-based templates within the starting data files provided by the Kit. If sizing is occurring, the script bails out as soon as the dimensions are calculated. While not truly necessary, it is recommended that you use the same technique within your own data files.

Height Control

The height of a template is always expected to be controlled by the template when within a table. Most tables contain fixed-height items, where the height of each item is always the same. For these tables, the template dimensions are expected to be established during the special "sizing" invocation of the Position script.

During sizing, there is no specific item available to the template. The HL engine passes in a special, dummy item. This dummy item has values of zero for all numeric fields and values of the empty string ("") for all text-based fields. As a result, the template cannot base its height on the contents of an actual item. It must instead determine its size based on general characteristics, such as font heights and other such information.

Once established during the sizing invocation, the height remains fixed. Any subsequent attempt to set the height to a different value are ignored. The exception to this is with variable-height tables, which are only supported for printed output. Within such tables, each template has its height re-calculated for every item that is output.

Width Control

Secondly, the table dictates the width of the template. Table templates are always sized to span the full width of the table that contains them. The template contents do not need to be positioned to utilize the full width, but the template itself is always sized to that width.

Only the height of a template is controlled by the template when within a table. Most tables have fixed-height items, where the height of each item is always the same. For these tables, the template is sized without any specific item before the table itself is sized. Since no actual item is provided, the template cannot base its height on the contents of the item. It must instead determine its size on general characteristics, such as font heights and other such information. Any attempt to set the height to a different in subsequent invocations of the Position script are ignored.

The exception to this is variable-height tables, which are only supported for printed output. Within such tables, each template has its height re-calculated for every item that is output.