ChooserTable Element (Data): Difference between revisions
From HLKitWiki
Jump to navigationJump to search
| (12 intermediate revisions by 2 users not shown) | |||
| Line 1: | Line 1: | ||
{{context|Kit Reference|Data File Reference|Portal Element (Data)}} | {{context|Kit Reference|Data File Reference|Portal Element (Data)}} | ||
==The " | ==The "chooser_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. | 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. | ||
| Line 8: | Line 8: | ||
|class="leftnormal"|component | |class="leftnormal"|component | ||
|Id – Specifies the unique id of the component that all selectable objects must be derived from. | |Id – Specifies the unique id of the component that all selectable objects must be derived from. | ||
|- | |||
|usetabledef | |||
|(Optional) Id – Specifies the [[TableDef Element (Data)|TableDef]] to reference for the selection details of this chooser. Default: None. | |||
|- | |- | ||
|choosetemplate | |choosetemplate | ||
| Line 13: | Line 16: | ||
|- | |- | ||
|choosepicks | |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:< | |(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.< | <ul class="sets"> | ||
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.< | <li>thing – The selectable objects are things.</li> | ||
hero – The selectable objects are picks from the active actor.< | <li>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.</li> | ||
actor – Same as "hero".< | <li>hero – The selectable objects are picks from the active actor.</li> | ||
Default: "thing". | <li>actor – Same as "hero".</li> | ||
<li>Default: "thing".</li> | |||
|- | |- | ||
|choosesortset | |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. | |(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. | ||
|- | |- | ||
| | |choosegapx | ||
|(Optional) Integer – Specifies the gap along the | |(Optional) Integer – Specifies the gap along the X-axis to insert between items presented for selection. Default: "0". | ||
|- | |- | ||
| | |choosegapy | ||
|(Optional) Integer – Specifies the gap along the | |(Optional) Integer – Specifies the gap along the Y-axis to insert between items presented for selection. Default: "0". | ||
|- | |- | ||
|descwidth | |descwidth | ||
|(Optional) Integer – Specifies the width of the reserved "description" area on the right within the | |(Optional) Integer – Specifies the width of the reserved "description" area on the right within the choose form. Some items need more width for lengthy descriptions and some do not, so you can control this as you see fit. Default: "250". | ||
|- | |- | ||
|buytemplate | |buytemplate | ||
| Line 42: | Line 46: | ||
|- | |- | ||
|showupdate | |showupdate | ||
|(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, such as through color highlighting. Default: "no". | |(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, such as through color highlighting. Default: "no".<br> | ||
{{note}}This option can significantly slow down display updates on slower computers, so only enable this if truly necessary. | |||
|- | |- | ||
|candidatepick | |candidatepick | ||
| Line 51: | Line 56: | ||
|- | |- | ||
|prereqtarget | |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:< | |(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.< | <ul class="sets"> | ||
parent – The next parent up the hierarchy is used, which parallels the corresponding displacement target.< | <li>container – The default parent container is used.</li> | ||
hero – The top-level hero is used, which parallels the corresponding displacement target.< | <li>parent – The next parent up the hierarchy is used, which parallels the corresponding displacement target.</li> | ||
Default: "container". | <li>hero – The top-level hero is used, which parallels the corresponding displacement target.</li> | ||
<li>Default: "container".</li> | |||
</ul> | |||
|- | |- | ||
|empty | |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. | |(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. | ||
|- | |||
|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". | |||
|- | |- | ||
|} | |} | ||
{{note}}Choosers possess a "buy" template, but there is no way to properly "sell" an item selected via a chooser. The reason for this is to allow the "buy" template to be used for customization purposes instead of actually buying and selling gear. The same mechanism can be used to allow the user to configure the item selected via the chooser, such as providing an edit or menu portal to specify an important facet of the selected item. | |||
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. | 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. | ||
| Line 76: | Line 88: | ||
|[[#xacttag|xacttag]] | |[[#xacttag|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. | |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. | ||
|- | |- | ||
|[[#secondary|secondary]] | |[[#secondary|secondary]] | ||
| Line 93: | Line 102: | ||
|- | |- | ||
|[[#titlebar|titlebar]] | |[[#titlebar|titlebar]] | ||
|An optional "titlebar" element may appear as defined by the given link. This element defines a [[ | |An optional "titlebar" element may appear as defined by the given link. This element defines a [[TitleBar Script]] for the portal. | ||
|- | |- | ||
|[[#description|description]] | |[[#description|description]] | ||
| Line 152: | Line 161: | ||
|class="leftnormal"|tag | |class="leftnormal"|tag | ||
|Id – Specifies the unique id of the tag to define within the tag group "transact". | |Id – Specifies the unique id of the tag to define within the tag group "transact". | ||
|- | |- | ||
|} | |} | ||
| Line 209: | Line 208: | ||
==The "titlebar" Element{{anchor|titlebar}}== | ==The "titlebar" Element{{anchor|titlebar}}== | ||
The "titlebar" element defines a [[ | The "titlebar" element defines a [[TitleBar Script]] for the portal, which synthesizes the text to be displayed at the top of the choose form. The complete list of attributes for this element is below. | ||
:{| class="infotable" | :{| class="infotable" | ||
|class="leftnormal"|PCDATA | |class="leftnormal"|PCDATA | ||
|Script – Specifies the code comprising the | |Script – Specifies the code comprising the TitleBar script. | ||
|- | |- | ||
|} | |} | ||
Latest revision as of 21:34, 10 November 2017
Context: HL Kit … Kit Reference … Data File Reference … Portal Element (Data)
The "chooser_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. usetabledef (Optional) Id – Specifies the TableDef to reference for the selection details of this chooser. Default: None. 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. choosegapx (Optional) Integer – Specifies the gap along the X-axis to insert between items presented for selection. Default: "0". choosegapy (Optional) Integer – Specifies the gap along the Y-axis 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 choose form. Some items need more width for lengthy descriptions and some do not, so you can control this as you see fit. Default: "250". 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. showupdate (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, such as through color highlighting. Default: "no".
NOTE! This option can significantly slow down display updates on slower computers, so only enable this if truly necessary.
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. 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".
NOTE! Choosers possess a "buy" template, but there is no way to properly "sell" an item selected via a chooser. The reason for this is to allow the "buy" template to be used for customization purposes instead of actually buying and selling gear. The same mechanism can be used to allow the user to configure the item selected via the chooser, such as providing an edit or menu portal to specify an important facet of the selected item.
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. 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 "xacttag" Element
The "xacttag" element specifies a tag that is automatically added to the transaction pick while the choose form is shown. These tags allow you to indicate contextual information about where the buy template is being used so that you can tailor the behavior appropriately. The complete list of attributes for this element is below.
tag Id – Specifies the unique id of the tag to define within the tag group "transact".
The "secondary" Element
The "secondary" element defines a Secondary Tag Expression that is automatically associated with every new pick added via the portal. This new tag expression is treated like an additional Container Tag Expression for the pick that must also be satisfied. The complete list of attributes for this element is below.
phase (Optional) Id – Specifies the unique id of the evaluation phase during which the tag expression is tested. If empty, the default timing is used from the definition file. Default: Empty. priority Integer – Specifies the evaluation priority during which the tag expression is tested. If empty, the default timing is used from the definition file. Default: Empty. PCDATA TagExpr – Specifies the code comprising the Secondary tag expression.
The "existence" Element
The "existence" element defines an Existence Tag Expression that is automatically associated with every new pick added via the portal. If a pick ever fails to satisfy the tag expression during an evaluation cycle, the pick is automatically deleted. The complete list of attributes for this element is below.
phase (Optional) Id – Specifies the unique id of the evaluation phase during which the tag expression is tested. If empty, the default timing is used from the definition file. Default: Empty. priority Integer – Specifies the evaluation priority during which the tag expression is tested. If empty, the default timing is used from the definition file. Default: Empty. PCDATA TagExpr – Specifies the code comprising the Secondary tag expression.
The "chosen" Element
The "chosen" element defines a Chosen Script for the portal, which synthesizes the text to be displayed as the chosen item within the portal. The complete list of attributes for this element is below.
PCDATA Script – Specifies the code comprising the Chosen script.
The "titlebar" Element
The "titlebar" element defines a TitleBar Script for the portal, which synthesizes the text to be displayed at the top of the choose form. The complete list of attributes for this element is below.
PCDATA Script – Specifies the code comprising the TitleBar script.
The "description" Element
The "description" element defines a Description Script for the portal, which synthesizes the text to be displayed within the description region of the choose form for the currently selected item on the left. The complete list of attributes for this element is below.
PCDATA Script – Specifies the code comprising the Description script.
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 choosertable portal might look like. All default values are assumed for optional attributes.
<portal id="stRace" style="chsNormal" width="110">
<chooser_table component="Race" choosetemplate="LargeItem">
<chosen><![CDATA[
if (@ispick = 0) then
@text = "{text ff0000}Select Race"
else
@text = "Race: " & field[name].text
endif
]]></chosen>
<titlebar>
@text = "Choose the race for your character"
</titlebar>
</chooser_table>
</portal>
