Adding Items to Tables

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

Overview

One of the most common mechanisms you'll be using is dynamic tables, as they allow the user to add new items to the character. Whether it be for skills, abilities, powers, spells, gear, or something else, a major part of character creation involves selecting an assortment of options from a list to customize the character. Dynamic tables are the mechanism the Kit uses to accomplish that task.

The Choose Table Vs. Show Table

Dynamic tables are actually two tables in one. First, there is the table in which the selected items are displayed, often called the "show table", and this works as outlined previously. However, there is a second table involved, which is the means through which available items are presented to the user for selection. This is often referred to as the "choose table".

The choose table behaves very similarly to the show table. It uses the same component for filtering the list of items shown. It also uses the List tag expression to filter the items shown. The reason for this is that any item that gets added to the table must fundamentally be shown within the table, so it stands to reason that the same requirements be applied.

The Candidate Tag Expression

However, the choose table also has a separate tag expression, which is called the "candidate" tag expression. The Candidate tag expression is distinct because there are often times when you'll want to be more restrictive in deciding which items can be added to the table. It is combined with the List tag expression to yield the final list of items that are presented to the user for selection.

For example, consider a table of special abilities. Many abilities will be user-selectable, while a number of them will only be added to the character as the result of another choice, such as racial abilities being automatically added only when the corresponding race is chosen. The list of abilities possessed by the character and presented in the show table must include these racial abilities, while the list of abilities that the user can freely choose from must not. To handle this distinction, two separate tag expressions are required, although the Candidate tag expression will simply be empty when no additional restrictions are needed.

The Choose Template

In addition to the separate tag expression, the choose table also has a separate template. The list of information users want to view when choosing an item will often be different from the information they want when viewing items that have been added to the table. To accommodate this, a separate template is specified, but there is no reason that the same template cannot be used for both purposes. By decoupling templates from tables, you can readily re-use the same template in multiple places.

Choosing Things Vs. Picks

Another important distinction between the choose table and the show table is the nature of the items presented for selection. Every item that has been added to the character is always a pick, which means that the show table always displays an assortment of picks. However, the choose table can contain either picks or things (never a combination). The norm will be things, such as presenting a list of weapons that the user can select from. When things are chosen, a new pick is created and that pick is then added to the character.

Sometimes, though, you will want to display picks that have already been added to the character. For example, the Wizard class in the d20 System must memorize spells from the spellbook. When spells are added to the spellbook, things are chosen and picks are created. However, when spells are memorized, the list of available spells is pulled from the picks that have already been added to the spellbook.

Customizing the Choose Form

In addition to the choose table described above, the form presented for item selection contains other elements. The contents of the choose form can be customized appropriately for whatever is being added. Some of the key elements are discussed below.

Title Bar Contents

titlebar script

Description Region

description script

Stacking Behavior

stacking

Buy/Sell Transaction Support

transaction

Presenting the Add Option

For consistency, adding an item to a table is always managed through a special option at the bottom of the table. There are two ways to configure the add option. One method is quick and easy, while the other entails more work but provides greater flexibility.

The quick and easy method is to define an "AddItem" script as part of the table. This script specifies the text to be displayed for the add option at the bottom of the table. You can use encoded text to including color highlighting and other formatting, but you are limited to a single line of text. Since a script is involved, you can change the behavior based on the prevailing conditions, such as greying out the text if all available slots have been used up or turning it red to indicate too many slots have been used. If you use this technique, the Kit will automaticallly handle all of the mechanics of presenting the add option.

The alternative is to define a custom template and specify the object to be used with that template. As with everything else for tables, the display of the add option is controlled through a template, and every template must have an object from which is can pull its information. So you can create your own custom template that contains any portals you deem necessary. This technique is rarely necessary, but it does come in handy in some situations. For example, within the d20 System data files, all gear is ascribed a size rating, and each piece of gear must have its size specified when added to the character. So the d20 System data files use a custom template for the add option that includes a menu whereby the size can be specified.