Source Element (Data)

Context: HL Kit … Kit 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".
maxchoices	(Optional) Integer - Specifies the maximum number of child sources that can be selected by the user at once. This makes it possible to limit the user to select only one option from a list of sources. If zero, there is no limit to the number of sources that can be selected. Default: "0".
minchoices	(Optional) Integer - Specifies the minimum number of child sources that must be selected by the user beneath this source. This makes it possible to require the user to select one or more options from a list of sources. If zero, there is no requirement to select any sources. Default: "0".
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! When either "minchoices" or "maxchoices" is specified as non-zero, child sources may NOT possess child sources of their own.

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>