Tables Use Templates
[Context: HL Kit … Basic Concepts and Terminology … Manipulation of Visual Elements … Working With Tables]
Overview
Tables make extensive use of templates. All of the objects shown within a table are viewed through a template. If the table is dynamic and allows items to be added, a separate template is used for displaying the items available for selection. If a table has a header or footer, then a template is used to display that information.
In fact, everything displayed as part of a table is accomplished using a template. The reason for this is simple. Using templates makes tables highly modular, allowing authors to readily customize the contents and re-use common templates for similar purposes.
How Templates Are Used
Every item shown within a table is either a thing or a pick. Every item that can be selected for addition to a table is a thing or a pick. Templates are an ideal vehicle for display within tables, since templates are always associated with a specific thing or pick. When used for showing a list of items, the same template is simply associated separately with each item in the list to properly render the contents of each item.
When rendering the table to the display, the HL engine will retrieve the list of objects that belong to the table. Then each of those objects is rendered, one at a time, into the table. For each object, the template defines the portals to be displayed and the object provides the appropriate fields from which to pull the information. Since the template is rendered separately for each item, it's perfectly reasonable to customize the contents of the template for each object. For example, certain portals can be hidden for some objects, while styles can be changes for certain portals on other objects.
Template Sizing and Dimensions
Templates are normally sized and positioned either by the layout that contains them or by the template itself. However, templates used within tables are handled a bit differently.
First of all, the positioning of a template within a table is fixed. The table has complete control over the positioning of each template within it.
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.
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 initiated. During this initial sizing, you can use the "issizing" target reference to detect the 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.
The Show Template
Every table uses at least one template - the "show" template. This template is used to display each of the items within the table.
Reusing Table Templates In Multiple Places
Templates are not restricted to where they can be used. Consequently, you could choose to use the same template within a table and outside of that table. Or you could use the same template within multiple tables. Doing this is extremely useful. The problem is that, if you do share the template, you will probably need to make a few adjustments to how everything is handled within the template based on its context. The Kit makes this possible by providing the "intable" target reference that can be used on within the template's Position script. This target reference can be used to determine whether a template is within a table in general or to determine which specific table it is being used within.
