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. Depending on your preferences, the Candidate tag expression can either supersede or be 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.

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.

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.

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

Across the top of the choose form is a title. By default, this title contains something generic, along the lines of "Choose an Item from the List Below". While this may be sufficient, it doesn't really tailor the form to a clear purpose. It would be significantly better to even have a title like "Select a Weapon from the List Below". And in situations where the user is selecting items that are limited (e.g. choosing two starting special abilities), it would be even better if the title provided feedback about how many selections remain.

To make this sort of customization possible, dynamic tables possess a "TitleBar" script. The script allows you to construct a suitable title that conveys whatever information is going to be most useful for the user. For example, in Savage Worlds, each starting character is given 15 skill points that can be used to add new skills and improve them. So the Savage Worlds data files display the number of remaining skill points within the title above the choose table for skills. When skill points remain, the title is highlighted in yellow. When they are all used, the title turns grey. And if they are overspent, the title turns red. This type of customization is easy and makes the data files significantly more friendly to use.

Description Region

To the right of the choose table, a large region is provided in which the detailed description of the currently selected item is shown. In some cases, you will find that the default width of this region is too narrow for the items being presented. When this happens, you can use the "descwidth" attribute on the table to change the width of the description region.

You can also control the contents of the description region if you want. This is achieved via the "Description" script for the table. By default, the description region will contain the name and description text for the currently selected item. However, you can customize this content to include more detailed information by defining a suitable Description script.

Buy/Sell Transaction Support

Some types of items involve a transaction for buying and selling the item. For example, weapons and gear will often have a cost associated with them, and characters will have some amount of currency. By integrating the process of buying and selling items directly into the adding and deleting of items, users are able to easily manage their expenses by allowing HL to track everything for them.

For items that entail buy and sell transactions, you can specify suitable templates to be used for each purpose as part of the table. When the choose form is displayed, the buy template is shown in the lower right corner, beneath the description region. The sell template is used whenever an item is deleted from the table.