Difference between revisions of "Source Element (Data)"

From HLKitWiki
Jump to: navigation, search
(New page: {{context|Kit Reference|Structural File Reference}} ==The "source" Element== Authors can use the sources mechanism as the mean for defining configuration settings that the us...)
 
Line 22: Line 22:
 
|-
 
|-
 
|sortorder
 
|sortorder
|(Optional) Integer – Assigns an explicit sort order to this source, enabling the display sequence of sources to be controlled by the author. All sources are sequenced in increasing sort order. All sources with the same sort order are sorted alphabetically based on the name. Default: "99999999".
+
|(Optional) Integer – Assigns an explicit sort order to this source, enabling the display sequence of sources to be controlled by the author (see below). All sources are sequenced in increasing sort order. Default: "99999999".
 
|-
 
|-
 
|selectable
 
|selectable
 
|(Optional) Boolean – Indicates whether the source is selectable by the user. This option allows sources that are solely used to visually group sources in a hierarchy to be made non-selectable. Default: "yes".
 
|(Optional) Boolean – Indicates whether the source is selectable by the user. This option allows sources that are solely used to visually group sources in a hierarchy to be made non-selectable. Default: "yes".
{{note}}By convention, sources should never be used as both as parent within the hierarchy and to control behavior within the data files. This means that any source with children should be non-selectable and not control any behaviors.
 
 
|-
 
|-
|
+
|reportable
|Text –  
+
|(Optional) Boolean Indicates whether the source is included in the hierarchical summary report of selected sources. Allows authors to prune the summary report of unnecessary layers so that the informnation presented to users is both clear and reasonably compact. Default: "yes".
 
|-
 
|-
|
+
|reportname
|Text –  
+
|(Optional) Text – Alternate name to be displayed for the source within the hierarchical summary report. Allows for a more compact name to be used for this purpose. If empty, the name of the source is used in the report. Default: Empty.
 +
|-
 +
|default
 +
|(Optional) Boolean – Indicates whether the initial (default) state of the source for a new actor is selected or non-selected. Default: "no".
 
|-
 
|-
 
|}
 
|}
{ "reportable", e_xml_set, l_yes_no[0], NULL, SIZE_YES_NO, l_yes_no },
+
 
{ "reportname", e_xml_implied, "", NULL, 0, NULL },
+
{{note}}Sources that are user-selectable may '''not''' also possess child sources. If a user-selectable source is designated as the parent of another source, a compilation error will be reported.
{ "default", e_xml_set, l_yes_no[1], NULL, SIZE_YES_NO, l_yes_no }
+
 
 +
{{note}}By default, all sources are sorted alphabetically, based on their name. If an explicit sort order is specified, sources are sorted in increasing order. Sources with children are always sorted AFTER sources without children within the displayed list. This ensures that sources without children are grouped together and directly beneath the parent source for intuitive visual grouping. The handling of sources with/without children takes precedence over any explicit ordering that may be given.
  
 
==Example==
 
==Example==
  
The following example demonstrates what a "reference" element might look like. All default values are assumed for optional attributes.
+
The following example demonstrates what a "source" element might look like. All default values are assumed for optional attributes.
  
 
<pre>
 
<pre>
<reference
+
<source
   id="BulletPrf"
+
   id="Output"
   contents="Bullet-Proof Armor"/>
+
   name="Output Options"
 +
  selectable="no"
 +
  description="Assortment of options governing character sheet output">
 +
  </source>
 +
 
 +
<source
 +
  id="Validation"
 +
  name="Include Validation Report on Sheet"
 +
  abbrev="Show Validation Report"
 +
  parent="Output"
 +
  default="yes"
 +
  description="Whether validation report is included at bottom of character sheet">
 +
  </source>
 
</pre>
 
</pre>

Revision as of 02:06, 25 November 2008

Context: HL KitKit Reference … Structural File Reference 

The "source" Element

Authors can use the sources mechanism as the mean for defining configuration settings that the user can toggle on and off via the "Configure Hero" form. When a given source is enabled by the user, a corresponding tag is automatically added to the actor, which can then be tested within the data files. Each individual source can be defined via the "source" element. The complete list of attributes for this element is below.

id Id – Specifies the unique id to utilize for this source.
name Text – Name to be displayed to the user for this source. Maximum length is 50 characters.
abbrev (Optional) Text – Shortened name to be displayed within the summary of enabled sources. If empty, the name is used as the abbreviation. Maximum length is 50 characters. Default: Empty.
description (Optional) Text – Description of the source and what behavior(s) it governs within the data files. Default: Empty.
parent (Optional) Id – Specifies the unique id of a different source that is treated as the parent of this source. All sources are displayed in a hierarchy within the "Configure Hero" form. If empty, this source is presented to the user as a top-level selection. Default: Empty.
sortorder (Optional) Integer – Assigns an explicit sort order to this source, enabling the display sequence of sources to be controlled by the author (see below). All sources are sequenced in increasing sort order. Default: "99999999".
selectable (Optional) Boolean – Indicates whether the source is selectable by the user. This option allows sources that are solely used to visually group sources in a hierarchy to be made non-selectable. Default: "yes".
reportable (Optional) Boolean – Indicates whether the source is included in the hierarchical summary report of selected sources. Allows authors to prune the summary report of unnecessary layers so that the informnation presented to users is both clear and reasonably compact. Default: "yes".
reportname (Optional) Text – Alternate name to be displayed for the source within the hierarchical summary report. Allows for a more compact name to be used for this purpose. If empty, the name of the source is used in the report. Default: Empty.
default (Optional) Boolean – Indicates whether the initial (default) state of the source for a new actor is selected or non-selected. Default: "no".

NOTE! Sources that are user-selectable may not also possess child sources. If a user-selectable source is designated as the parent of another source, a compilation error will be reported.

NOTE! By default, all sources are sorted alphabetically, based on their name. If an explicit sort order is specified, sources are sorted in increasing order. Sources with children are always sorted AFTER sources without children within the displayed list. This ensures that sources without children are grouped together and directly beneath the parent source for intuitive visual grouping. The handling of sources with/without children takes precedence over any explicit ordering that may be given.

Example

The following example demonstrates what a "source" element might look like. All default values are assumed for optional attributes.

<source
  id="Output"
  name="Output Options"
  selectable="no"
  description="Assortment of options governing character sheet output">
  </source>

<source
  id="Validation"
  name="Include Validation Report on Sheet"
  abbrev="Show Validation Report"
  parent="Output"
  default="yes"
  description="Whether validation report is included at bottom of character sheet">
  </source>