MenuThings Element (Data)
Context: HL Kit … Kit Reference … Data File Reference … Portal Element (Data)
The "menu_things" element is used when the user needs to select an item that exists within the data files. For example, an in-play adjustment can select an attribute or skill that the actor possesses, or an ability can select a weapon type that receives a bonus. The common thread is that the options presented in the menu are either things or picks within the data files. The complete list of attributes for this element is below.
IMPORTANT! Within a thing-based menu, the selected thing is not added to the container as a new pick. The thing is merely identified for reference and can be accessed via the menu, but no new pick appears within the container. Only tables and choosers can actually add new picks to a container.
field Id – Specifies the unique id of the field whose contents reflect the current selection from the menu. The field must be a value-based field of style "menu" and must exist within the pick/thing associated with the containing template. If this portal is not defined within a template, a menu is not allowed. component Id – Specifies the unique id of the component that all choices must be derived from. defthing (Optional) Id – Specifies the unique id of the thing to pre-select as the default choice within the menu. If empty, no default selection is made. Default: Empty. usepicks (Optional) Set – Designates whether the menu is populated with things or picks, and, if the latter, where the list of picks is retrieved from. Must be one of these values: - thing – The menu is populated with things.
- container – The menu is populated with picks from the container of the pick associated with the template.
- hero – The menu is populated with picks from the actor.
- actor – Same as "hero".
- Default: "thing".
sortset (Optional) Id – Specifies the unique id of the sort set to be used to determine the sequence in which the items are listed in the menu. If empty, the items are listed alphabetically. Default: Empty. maxvisible (Optional) Integer – Specifies the maximum number of items that will be visible at one time within the menu when the user opens it for selection. If there are more items to choose from, a scroller will allow the user to access them. Default: "5". usepicksfield (Optional) Id – Specifies the unique id of a value-based field that dynamically dictates when the menu is populated with things or picks. If empty, the "usepicks" attribute dictates the behavior. If specified, the field value dictates the behavior according to the list below. Default: Empty. - 0 – The menu is populated with things.
- 1 – The menu is populated with picks from the container of the pick associated with the template.
- 2 – The menu is populated with picks from the actor.
candidatefield (Optional) Id – Specifies the unique id of a text-based field that contains the Candidate tag expression to be used when populating the menu options. Default: Empty.
IMPORTANT! This mechanism is secondary to the "candidate" element, so the field is ignored if the "candidate" element is non-empty.
namefield (Optional) Id - Specifies the unique id of a text-based field that is used instead of the "name" of each thing shown within the array. This makes it possible to customize the name to be displayed in the menu differently from the standard name shown for the thing. showlabel (Optional) Boolean – (iPad only) Indicates whether the label displaying the current selection of the menu should be shown. This is used when you just want the menu control to be used as a button to make a selection which will be displayed some other way. Default: "yes".
The "menu_things" element also possesses child elements that define additional facets of the portal. The list of these child elements is below and must appear in the order shown. Click on the link to access the details for each element.
candidate An optional "candidate" element may appear as defined by the given link. This element defines a Candidate Tag Expression for the portal. change An optional "change" element may appear as defined by the given link. This element defines a Change Script for the portal.
The "candidate" Element
The "candidate" element defines a Candidate Tag Expression for the portal that limits the set of things/picks that are available for selection. The complete list of attributes for this element is below.
PCDATA TagExpr – Specifies the code comprising the Candidate tag expression.
The "change" Element
The "change" element defines a Change Script for the portal that is invoked whenever the user selects a new choice from the list of options. This script allows the implications of the new selection to be integrated and the display updated. The complete list of attributes for this element is below.
PCDATA Script – Specifies the code comprising the Change script.
Example
The following example demonstrates what a thing-based menu portal might look like. All default values are assumed for optional attributes.
<portal id="menu" style="menuNormal">
<menu_things field="adjChosen" component="none" maxvisible="20"
usepicksfield="adjUsePick" candidatefield="adjCandid">
<candidate></candidate>
</menu_things>
</portal>
