ChooserTable Element (Data)
Context: HL Kit … Kit Reference … Data File Reference … Portal Element (Data)
The "choose_table" Element
Choosers are similar to thing-based menus in some ways, as they allow the user to select one thing or pick from a list that is determined dynamically. One key difference with choosers is that any selected thing/pick is added to the container as a new pick. If a pick is selected, a new pick derived from the same thing is added. Another key difference is that the available things/picks are displayed for selection in a "choose form", allowing each object to be presented with detailed information. The "chooser" mechanism is ideal for selecting facets like race, profession, archetype, etc. Each chooser is defined via the use of the "chooser_table" element. The complete list of attributes for this element is below.
component Id – Specifies the unique id of the component that all selectable objects must be derived from. choosetemplate Id – Specifies the unique id of the template to be used for displaying selectable objects. choosepicks (Optional) Set – Designates whether the selectable objects consist of things or picks, and, if the latter, where the list of picks is retrieved from. Must be one of these values:
thing – The selectable objects are things.
container – The selectable objects are picks from the implicitly identified container. If the containing scene is a form associated with a gizmo, the gizmo is used, else the actor is used.
hero – The selectable objects are picks from the active actor.
actor – Same as "hero".
Default: "thing".choosesortset (Optional) Id – Specifies the unique id of the sort set to be used for sequencing all of the objects presented for selection. If empty, all objects are sorted by name. Default: Empty. choosegaphorz (Optional) Integer – Specifies the gap along the horizontal access to insert between items presented for selection. Default: "0". choosegapvert (Optional) Integer – Specifies the gap along the vertical access to insert between items presented for selection. Default: "0". descwidth (Optional) Integer – Specifies the width of the reserved "description" area on the right within the chooser form. Some items need more width for lengthy descriptions and some do not, so you can control this as you see fit. Default: "200". buytemplate (Optional) Id – Specifies the unique id of the template to be shown in the lower right corner of the choose form for controlling the details of a purchase transaction. If empty, no buy template is utilized. Default: Empty. xactspecial (Optional) Integer – When a buy template is shared between two or more portals or things, the template behavior may need to be tailored based on the usage. If this need arises, this attribute specifies a unique value that identifies this particular usage. By assigning a different value to each usage and keying on it within the template's Position script, you can tailor the template appropriately. Default: "0". linkage (Optional) Id – Specifies the unique id of a thing that will be used as a linkage. When a new pick is added via the chooser, that pick has an automatic linkage setup to any existing pick derived from the specified thing. If no derived pick exists when the new pick is added, no linkage is ever created. If empty, no linkage is established. Default: Empty. dynamic (Optional) Boolean – Indicates whether the chooser needs to be dynamically updated after any modification to the actor so that the influence of other changes are always visually reflected to the user. Default: "no". candidatepick (Optional) Id – Specifies the unique id of a pick that will contain a dynamically generated Candidate tag expression for use in determining the list of available objects to choose from. If empty, the "candidate" child element defines the tag expression to use. Default: Empty. candidatefield (Optional) Id – Specifies the unique id of a text-based field that contains the Candidate tag expression used to determine the list of available objects to choose from. This field must exist within the pick identified by the "candidatepick" attribute (above). If empty, the "candidate" child element defines the tag expression to use. Default: Empty. prereqtarget (Optional) Set – Designates the container against which all pre-requisite tests need to be performed when determining the list of items available for selection. When displacement is utilized, pre-requisites need to be tested against the container to which the new picks will ultimately be added. Must be one of these values:
container – The default parent container is used.
parent – The next parent up the hierarchy is used, which parallels the corresponding displacement target.
hero – The top-level hero is used, which parallels the corresponding displacement target.
Default: "container".empty (Optional) Text – Specifies the text message to be displayed if the user attempts to select an option and there are no available items to choose from. If empty, a default message is displayed. Default: Empty.
The "chooser_table" element also possesses child elements that define additional behaviors 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. needtag Zero or more "needtag" elements may appear as defined by the given link. This element defines a tag relationship that must exist between a prospective object and the container in order to list the object among the available items. denytag Zero or more "denytag" elements may appear as defined by the given link. This element defines a tag relationship that must not exist between a prospective object and the container in order to list the object among the available items. xacttag Zero or more "xacttag" elements may appear as defined by the given link. This element defines a tag that is assigned to the transaction pick while the choose form is visible. restriction An optional "restriction" element may appear as defined by the given link. This element defines a Restriction Tag Expression for the portal that identifies things which cannot be selected if they already exist within the container. secondary An optional "secondary" element may appear as defined by the given link. This element defines a Secondary Tag Expression that is associated with every new pick added via the portal. existence An optional "existence" element may appear as defined by the given link. This element defines an Existence Tag Expression that is associated with every new pick added via the portal. autotag Zero or more "autotag" elements may appear as defined by the given link. This element specifies tags that are automatically assigned to each added thing. chosen An optional "chosen" element may appear as defined by the given link. This element defines a Chosen Script for the portal. titlebar An optional "titlebar" element may appear as defined by the given link. This element defines a Titlebar Script for the portal. description An optional "description" element may appear as defined by the given link. This element defines a Description Script 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 "needtag" Element
The "needtag" element defines a tag relationship that must exist between the object to be added and the prospective container. Tags from one tag group are enumerated within the container, then the object is tested to make sure that it has at least one matching tag with the same id in a separate tag group. If the tag is not found, the object is not valid for selection and omitted from the available list. The complete list of attributes for this element is below.
container Id – Specifies the unique id of the tag group to utilize within the container. thing Id – Specifies the unique id of the tag group to check within the thing/pick. usehero (Optional) Boolean – Indicates whether the container tags are pulled from the prospective container for the new pick or the hero. This distinction can be important when using displacement. Default: "no".
The "denytag" Element
The "denytag" element defines a tag relationship that must not exist between the object to be added and the prospective container. Tags from one tag group are enumerated within the container, then the object is tested to make sure that it does not possess any matching tags with the same ids in a separate tag group. If any matching tags are found, the object is not valid for selection and omitted from the available list. The complete list of attributes for this element is below.
container Id – Specifies the unique id of the tag group to utilize within the container. thing Id – Specifies the unique id of the tag group to check within the thing/pick. usehero (Optional) Boolean – Indicates whether the container tags are pulled from the prospective container for the new pick or the hero. This distinction can be important when using displacement. Default: "no".
The "restriction" Element
The "restriction" element defines a Restriction Tag Expression for the portal that further limits the set of things/picks that are available for selection. This tag expression is compared against all picks that already exist within the container. Any object that exists within the restricted list is precluded from being selected again, resulting in it being omitted from the list of available choices. The complete list of attributes for this element is below.
PCDATA TagExpr – Specifies the code comprising the Restriction 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.
The "labeltext" Element
The "labeltext" element defines a Label Script for the portal. The complete list of attributes for this element is below.
PCDATA Script – Specifies the code comprising the Label script.
Example
The following example demonstrates what an output label portal might look like. All default values are assumed for optional attributes.
<portal id="name" style="outNameLg">
<output_label field="name"/>
</portal>
<portal id="oHeroName" style="outHeroNam">
<output_label>
<labeltext>
@text = hero.actorname
var result as number
result = compare(@text, "")
if (result = 0) then
@text = "- Unnamed Hero -"
endif
</labeltext>
</output_label>
</portal>
