Skip to main content

WT21 panel.xml Basics

Introduction​

The panel.xml file allows developers to configure their aircraft-specific WT21 installation. A basic understanding of the XML language is recommended when working with panel.xml.

File Structure​

Below is an example of a simple panel.xml file:

<PlaneHTMLConfig>

  <Instrument>
    <Name>WT21_PFD_1</Name>
  </Instrument>

  <Instrument>
    <Name>WT21_PFD_2</Name>
  </Instrument>

  <Instrument>
    <!-- Where there is only one instrument of a specific type, the index may be omitted from the name -->
    <Name>WT21_MFD</Name>
  </Instrument>

  <Instrument>
    <Name>WT21_FMC_1</Name>
  </Instrument>

  <Instrument>
    <Name>WT21_FMC_2</Name>
  </Instrument>

</PlaneHTMLConfig>

The file contains the root tag <PlaneHTMLConfig> under which all other tags must be placed. There is one <Instrument> tag for each JS/HTML instrument in the plane. The <Name> tag identifies the specific instrument referenced by its parent <Instrument> tag. In this example, there are five declared instruments: two PFDs, one MFD, and two FMCs.

info

WT21 instrument names are standardized to the following formats:

  • PFD: WT21_PFD_[index], where index is an integer.
  • MFD: WT21_MFD_[index], where index is an integer.
  • GTC: WT21_FMC_[index], where index is an integer.

Tag Scope​

Each tag parsed by the WT21 has a required scope, defined as the parent under which it must be placed. If a tag is placed in an incorrect scope, it may not be parsed at all or it may be interpreted as a different type of tag with the same name. Therefore, it is important to ensure that all tags are defined in the correct scope.

The tags documentation details the scope of each tag. When the scope is listed as "Global", this means the tag should be placed directly under the root <PlaneHTMLConfig> tag. When the scope is listed as "PFD", "MFD", or "FMC", this means the tag should be placed directly under a PFD, MFD, or FMC <Instrument> tag, respectively.

Global vs. Instrument-Specific Options​

panel.xml options can either be global or specific to a particular instrument. Tags that are descendants of an <Instrument> tag define options specific to the instrument referenced by their parent <Instrument> tag. Tags that are not descendants of any <Instrument> tag define global options.

Certain instrument-specific tags can be defined globally by placing them them in the global scope (directly under the root <PlaneHTMLConfig> tag) instead of under an <Instrument> tag. When doing so, the option will apply to all instruments that support the option. If an instrument-specific tag is defined both globally and within a <Instrument> tag, then the version defined within the <Instrument> tag will override the global one.

caution

Not all instrument-specific tags can be defined globally. Please refer to the tags documentation to find which ones can be defined globally and which ones cannot.

Required vs. Optional Tags​

Tags and attributes can either be required or optional. Required tags/attributes must be explicitly defined for panel.xml to be successfully parsed. If a required tag/attribute is missing, the WT21 will throw a Javascript error during initialization with a message describing what was missing. Optional tags/attributes do not have to be explicitly defined, and omitting these will have no adverse effects. When an optional tag/attribute is omitted, the option it defines will revert to a default value.

The tags documentation details which tags and attributes are required and which are optional, as well as the default values for optional tags/attributes.

caution

If the WT21 detects that an optional attribute or tag was not formatted correctly (e.g. a mis-spelled option, an out-of-bounds numeral, etc), it will emit a console warning and revert the option to its default value. Therefore, during development it is recommended that you monitor the console output of all instruments to ensure that panel.xml is being parsed cleanly.

Redundant Tags​

When you define multiple copies of a tag that is meant to be a singleton, only the first instance of the tag (in tree order) will apply. Take the following example:

<Instrument>
  <Name>WT21_PFD_1</Name>

  <PfdConfig>
      <ArtificialHorizonStyle>Full</ArtificialHorizonStyle>
    </PfdConfig>

  <PfdConfig>
      <ArtificialHorizonStyle>Cropped</ArtificialHorizonStyle>
    </PfdConfig>
</Instrument>

Of the two <PfdConfig> -> <ArtificialHorizonStyle> tags defined for WT21_PFD_1, only the top one will apply. As a result, the PFD will use the full artifical horizon rather than a cropped version of the artificial horizon.