MenuThings Element (Data): Difference between revisions
No edit summary |
|||
| Line 42: | Line 42: | ||
|- | |- | ||
|} | |} | ||
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. | 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. | ||
Revision as of 12:08, 2 December 2008
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.
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 A single "candidate" element must appear as defined by the given link. This element defines a Candidate Tag Expression for the portal. restriction An optional "restriction" elements must appear as defined by the given link. This element defines a secondary Candidate Tag Expression for the portal that must also be satisfied. The restriction is only used when the Candidate tag expression is specified via a field. 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 primary 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 primary Candidate tag expression.
The "restriction" Element
The "restriction" element defines a secondary Candidate Tag Expression for the portal that further limits the set of things/picks that are available for selection. This tag expression is only utilized if the primary Candidate tag expression is determined via a field. The complete list of attributes for this element is below.
PCDATA TagExpr – Specifies the code comprising the secondary 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>
