Difference between revisions of "TableAuto Element (Data)"

From HLKitWiki
Jump to: navigation, search
(New page: {{context|Kit Reference|Data File Reference|Portal Element (Data)}} ==The "table_auto" Element== Auto tables are a special kind of dynamic table that can only ever contain a single item....)
 
 
(6 intermediate revisions by 2 users not shown)
Line 8: Line 8:
 
|class="leftnormal"|component
 
|class="leftnormal"|component
 
|Id – Specifies the unique id of the component that all shown objects must be derived from.  
 
|Id – Specifies the unique id of the component that all shown objects must be derived from.  
 +
|-
 +
|usetabledef
 +
|(Optional) Id – Specifies the [[TableDef Element (Data)|TableDef]] to reference for details of this table. Default: None.
 +
|-
 +
|autothing
 +
|Id – Specifies the unique id of the thing to be added to the table whenever the user clicks on the "add" item at the bottom.
 
|-
 
|-
 
|showtemplate
 
|showtemplate
Line 16: Line 22:
 
|-
 
|-
 
|showgaphorz
 
|showgaphorz
|(Optional) Integer – Specifies the gap along the horizontal access to insert between items that exist within the table. Default: "0".
+
|(Optional) Integer – Specifies the gap along the horizontal axis to insert between items that exist within the table. Default: "0".
 
|-
 
|-
 
|showgapvert
 
|showgapvert
|(Optional) Integer – Specifies the gap along the vertical access to insert between items that exist within the table. Default: "0".
+
|(Optional) Integer – Specifies the gap along the vertical axis to insert between items that exist within the table. Default: "0".
|-
+
|choosetemplate
+
|Id – Specifies the unique id of the template to be used for displaying available objects that the user can choose from.
+
|-
+
|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:<br>
+
thing – The selectable objects are things.<br>
+
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.<br>
+
hero – The selectable objects are picks from the active actor.<br>
+
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 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".
+
 
|-
 
|-
 
|columns
 
|columns
Line 48: Line 32:
 
|scrollable
 
|scrollable
 
|(Optional) Boolean – Indicates whether the table contents can be scrolled by the user. By default, a scroller is shown whenever the number of items exceeds the visible space, but you can disable this behavior. Default: "yes".
 
|(Optional) Boolean – Indicates whether the table contents can be scrolled by the user. By default, a scroller is shown whenever the number of items exceeds the visible space, but you can disable this behavior. Default: "yes".
|-
 
|ismultiadd
 
|(Optional) Boolean – Indicates whether the user can add multiple items at a time to the table, without leaving the choose form. Default: "yes".
 
|-
 
|allowstack
 
|(Optional) Boolean – Indicates whether the user is allowed to stack items within the table, subject to the restrictions imposed for each item. Default: "yes".
 
 
|-
 
|-
 
|addtemplate
 
|addtemplate
|(Optional) Id – Specifies the unique id of the template to be used for the "add" item that always appears at the bottom of a dynamic table and that users will click on to add an item to the table. This allows detailed controlled when the simple "additem" script is not sufficient. If empty, the "additem" element must be specified. Default: Empty.
+
|(Optional) Id – Specifies the unique id of the template to be used for the "add" item that always appears at the bottom of the table and that users will click on to add an item to the table. This allows detailed controlled when the simple "additem" script is not sufficient. If empty, the "additem" element must be specified. Default: Empty.
 
|-
 
|-
|addthing
+
|addpick
 
|(Optional) Id – Specifies the unique id of a thing that is associated with the "add" item at the bottom of the table. HL will retrieve any pick based on this thing that exists within the target container and use it. This allows you to control what fields can be accessed from the "addtemplate". If empty, the "actor" pick is used, except within a gizmo, where its "defaultthing" is used instead. Default: Empty.
 
|(Optional) Id – Specifies the unique id of a thing that is associated with the "add" item at the bottom of the table. HL will retrieve any pick based on this thing that exists within the target container and use it. This allows you to control what fields can be accessed from the "addtemplate". If empty, the "actor" pick is used, except within a gizmo, where its "defaultthing" is used instead. Default: Empty.
 
|-
 
|-
Line 67: Line 45:
 
|(Optional) Id – Specifies the unique id of the template to be used for a header item that appears at the top of the table. This allows you to add column headers above various pieces of information in the table. If empty, the "headertitle" element dictates whether a header is displayed above the table. Default: Empty.
 
|(Optional) Id – Specifies the unique id of the template to be used for a header item that appears at the top of the table. This allows you to add column headers above various pieces of information in the table. If empty, the "headertitle" element dictates whether a header is displayed above the table. Default: Empty.
 
|-
 
|-
|headerthing
+
|headerpick
 
|(Optional) Id – Specifies the unique id of a thing that is associated with the header item at the top of the table. HL will retrieve any pick based on this thing that exists within the target container and use it. This allows you to control what fields can be accessed from the "headertemplate". If empty, the "actor" pick is used, except within a gizmo, where its "defaultthing" is used instead. Default: Empty.
 
|(Optional) Id – Specifies the unique id of a thing that is associated with the header item at the top of the table. HL will retrieve any pick based on this thing that exists within the target container and use it. This allows you to control what fields can be accessed from the "headertemplate". If empty, the "actor" pick is used, except within a gizmo, where its "defaultthing" is used instead. Default: Empty.
|-
 
|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".
 
|-
 
|selltemplate
 
|(Optional) Id – Specifies the unique id of the template to be shown when the user attempts to delete an item. This allows you to enable the selling of items for money. If empty, no sell template is utilized. Default: Empty.
 
|-
 
|candidatepick
 
|(Optional) Id – Specifies the unique id of a pick that will contain a dynamically generated [[Candidate Tag Expression|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|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:<br>
 
container – The default parent container is used.<br>
 
parent – The next parent up the hierarchy is used, which parallels the corresponding displacement target.<br>
 
hero – The top-level hero is used, which parallels the corresponding displacement target.<br>
 
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.
 
 
|-
 
|-
 
|showfrozenfixed
 
|showfrozenfixed
 
|(Optional) Boolean – Indicates whether the table must be converted to a "fixed" table whenever the table is designated as frozen. Default: "no".
 
|(Optional) Boolean – Indicates whether the table must be converted to a "fixed" table whenever the table is designated as frozen. Default: "no".
|-
 
|showfixedlast
 
|(Optional) Boolean – Indicates whether all non-deletable picks within the table are sorted to the end of the list of picks shown. Default: "no".
 
 
|-
 
|-
 
|allowuserorder
 
|allowuserorder
Line 117: Line 67:
 
|}
 
|}
  
The "table_dynamic" 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 "table_auto" 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.
  
 
:{| class="infotable"
 
:{| class="infotable"
 
|class="leftnormal"|[[#list|list]]
 
|class="leftnormal"|[[#list|list]]
 
|An optional "list" element may appear as defined by the given link. This element defines a [[List Tag Expression]] for the portal.
 
|An optional "list" element may appear as defined by the given link. This element defines a [[List Tag Expression]] for the portal.
|-
 
|[[#candidate|candidate]]
 
|An optional "candidate" element may appear as defined by the given link. This element defines a [[Candidate Tag Expression]] for the portal.
 
|-
 
|[[#needtag|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|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|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|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|secondary]]
 
|[[#secondary|secondary]]
Line 146: Line 81:
 
|[[AutoTag Element (Data)|autotag]]
 
|[[AutoTag Element (Data)|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.
 
|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|chosen]]
 
|An optional "chosen" element may appear as defined by the given link. This element defines a [[Chosen Script]] for the portal.
 
|-
 
|[[#titlebar|titlebar]]
 
|An optional "titlebar" element may appear as defined by the given link. This element defines a [[Titlebar Script]] for the portal.
 
|-
 
|[[#description|description]]
 
|An optional "description" element may appear as defined by the given link. This element defines a [[Description Script]] for the portal.
 
 
|-
 
|-
 
|[[#headertitle|headertitle]]
 
|[[#headertitle|headertitle]]
Line 171: Line 97:
 
|class="leftnormal"|PCDATA
 
|class="leftnormal"|PCDATA
 
|TagExpr – Specifies the code comprising the List tag expression.
 
|TagExpr – Specifies the code comprising the List tag expression.
|-
 
|}
 
 
==The "candidate" Element{{anchor|candidate}}==
 
 
The "candidate" element defines a [[Candidate Tag Expression]] for the portal that limits the set of things/picks that are available for selection. In addition to the Candidate tag expression, all available objects must also satisfy the List tag expression (above). The complete list of attributes for this element is below.
 
 
:{| class="infotable"
 
|class="leftnormal"|PCDATA
 
|TagExpr – Specifies the code comprising the Candidate tag expression.
 
|-
 
|}
 
 
==The "needtag" Element{{anchor|needtag}}==
 
 
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.
 
 
:{| class="infotable"
 
|class="leftnormal"|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{{anchor|denytag}}==
 
 
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.
 
 
:{| class="infotable"
 
|class="leftnormal"|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{{anchor|xacttag}}==
 
 
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.
 
 
:{| class="infotable"
 
|class="leftnormal"|tag
 
|Id – Specifies the unique id of the tag to define within the tag group "transact".
 
|-
 
|}
 
 
==The "restriction" Element{{anchor|restriction}}==
 
 
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.
 
 
:{| class="infotable"
 
|class="leftnormal"|PCDATA
 
|TagExpr – Specifies the code comprising the Restriction tag expression.
 
 
|-
 
|-
 
|}
 
|}
Line 265: Line 129:
 
|PCDATA
 
|PCDATA
 
|TagExpr – Specifies the code comprising the Secondary tag expression.
 
|TagExpr – Specifies the code comprising the Secondary tag expression.
|-
 
|}
 
 
==The "chosen" Element{{anchor|chosen}}==
 
 
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.
 
 
:{| class="infotable"
 
|class="leftnormal"|PCDATA
 
|Script – Specifies the code comprising the Chosen script.
 
|-
 
|}
 
 
==The "titlebar" Element{{anchor|titlebar}}==
 
 
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="leftnormal"|PCDATA
 
|Script – Specifies the code comprising the Titlebar script.
 
|-
 
|}
 
 
==The "description" Element{{anchor|description}}==
 
 
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.
 
 
:{| class="infotable"
 
|class="leftnormal"|PCDATA
 
|Script – Specifies the code comprising the Description script.
 
 
|-
 
|-
 
|}
 
|}
Line 320: Line 154:
 
==Example==
 
==Example==
  
The following example demonstrates what a dynamic table portal might look like. All default values are assumed for optional attributes.
+
The following example demonstrates what an auto table portal might look like. All default values are assumed for optional attributes.
  
 
<pre>
 
<pre>
<portal id="arMelee" style="tblNormal">
+
<portal id="peImages" style="tblNormal">
   <table_dynamic component="Gear"
+
   <table_auto component="UserImage"
       showtemplate="arWpnPick" choosetemplate="arWpnThing"
+
       showtemplate="peImage" autothing="mscUserImg">
      buytemplate="BuyCash" selltemplate="SellCash">
+
    <list>component.WeapMelee</list>
+
    <candidate>!Equipment.Natural</candidate>
+
    <description/>
+
 
     <headertitle>
 
     <headertitle>
       @text = "Melee Weapons"
+
       @text = "Gallery"
 
       </headertitle>
 
       </headertitle>
 
     <additem>
 
     <additem>
       @text = "Add New Melee Weapons"
+
       @text = "Add Another Image"
 
       </additem>
 
       </additem>
     </table_dynamic>
+
     </table_auto>
 
   </portal>
 
   </portal>
 
</pre>
 
</pre>

Latest revision as of 14:35, 10 November 2017

Context: HL KitKit Reference … Data File Reference … Portal Element (Data) 

The "table_auto" Element

Auto tables are a special kind of dynamic table that can only ever contain a single item. As such, an auto table looks like a dynamic table until the user clicks on the "add" item at the bottom. Instead of displaying a choose form, a new instance of a specific item is added to the table. This is extremely useful for tables of journal entries and character portraits. Each auto table is defined via the use of the "table_auto" element. The complete list of attributes for this element is below.

component Id – Specifies the unique id of the component that all shown objects must be derived from.
usetabledef (Optional) Id – Specifies the TableDef to reference for details of this table. Default: None.
autothing Id – Specifies the unique id of the thing to be added to the table whenever the user clicks on the "add" item at the bottom.
showtemplate Id – Specifies the unique id of the template to be used for displaying the picks that have been added to the table.
showsortset (Optional) Id – Specifies the unique id of the sort set to be used for sequencing the items that exist within the table. If empty, all objects are sorted by name. Default: Empty.
showgaphorz (Optional) Integer – Specifies the gap along the horizontal axis to insert between items that exist within the table. Default: "0".
showgapvert (Optional) Integer – Specifies the gap along the vertical axis to insert between items that exist within the table. Default: "0".
columns (Optional) Integer – Specifies the number of columns of data to display within the table. Default: "1".
scrollable (Optional) Boolean – Indicates whether the table contents can be scrolled by the user. By default, a scroller is shown whenever the number of items exceeds the visible space, but you can disable this behavior. Default: "yes".
addtemplate (Optional) Id – Specifies the unique id of the template to be used for the "add" item that always appears at the bottom of the table and that users will click on to add an item to the table. This allows detailed controlled when the simple "additem" script is not sufficient. If empty, the "additem" element must be specified. Default: Empty.
addpick (Optional) Id – Specifies the unique id of a thing that is associated with the "add" item at the bottom of the table. HL will retrieve any pick based on this thing that exists within the target container and use it. This allows you to control what fields can be accessed from the "addtemplate". If empty, the "actor" pick is used, except within a gizmo, where its "defaultthing" is used instead. Default: Empty.
addspace (Optional) Integer – Specifies the additional vertical space to be inserted when displaying the simple "add" item at the bottom of the table by using the "additem" script. The height of the item is based on the font height of the text shown, so this attribute allows you to insert additional padding if you wish. Default: "2".
headertemplate (Optional) Id – Specifies the unique id of the template to be used for a header item that appears at the top of the table. This allows you to add column headers above various pieces of information in the table. If empty, the "headertitle" element dictates whether a header is displayed above the table. Default: Empty.
headerpick (Optional) Id – Specifies the unique id of a thing that is associated with the header item at the top of the table. HL will retrieve any pick based on this thing that exists within the target container and use it. This allows you to control what fields can be accessed from the "headertemplate". If empty, the "actor" pick is used, except within a gizmo, where its "defaultthing" is used instead. Default: Empty.
showfrozenfixed (Optional) Boolean – Indicates whether the table must be converted to a "fixed" table whenever the table is designated as frozen. Default: "no".
allowuserorder (Optional) Boolean – Indicates whether the items in the table can be re-ordered by the user. If enabled, the specified component must designate a suitable ordering field or a separate component with such a field must be specified via the "ordercomponent" attribute. Default: "no".

NOTE! Verify that whatever sort set you use for showing the items includes the designated ordering field as its first sort key.

ordercomponent (Optional) Id – Specifies the unique id of an alternate component that possesses a suitable ordering field. This attribute is only applicable when the table supports user ordering. If empty, the ordering field is dictated by the component associated with the table. Default: Empty.
linkage (Optional) Id – Specifies the unique id of a thing that will be used as a linkage. When a new pick is added to the table, 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.
alwaysupdate (Optional) Boolean – Indicates whether the table must 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".

NOTE! This option can significantly slow down display updates on slower computers, so only enable this if truly necessary.

The "table_auto" 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.

list An optional "list" element may appear as defined by the given link. This element defines a List Tag Expression for the portal.
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.
headertitle An optional "headertitle" element may appear as defined by the given link. This element defines a HeaderTitle Script for the portal.
additem An optional "additem" element may appear as defined by the given link. This element defines a AddItem Script for the portal.

The "list" Element

The "list" element defines a List Tag Expression for the portal that limits the set of picks that are shown. Regardless of this tag expression, all picks added via this portal are always shown within it, enabling deletion of any object added through the table. The complete list of attributes for this element is below.

PCDATA TagExpr – Specifies the code comprising the List tag expression.

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 "headertitle" Element

The "headertitle" element defines a HeaderTitle Script for the portal that synthesizes the text to be displayed at the top of the table as a header. The complete list of attributes for this element is below.

PCDATA Script – Specifies the code comprising the HeaderTitle script.

The "additem" Element

The "additem" element defines a AddItem Script for the portal that synthesizes the text to be displayed within the "add" item at the bottom of the table, where the user will click to add a new item. The complete list of attributes for this element is below.

PCDATA Script – Specifies the code comprising the AddItem script.

Example

The following example demonstrates what an auto table portal might look like. All default values are assumed for optional attributes.

<portal id="peImages" style="tblNormal">
  <table_auto component="UserImage"
      showtemplate="peImage" autothing="mscUserImg">
    <headertitle>
      @text = "Gallery"
      </headertitle>
    <additem>
      @text = "Add Another Image"
      </additem>
    </table_auto>
  </portal>